جهاز توجيه التطبيقات Next.js 16: أنماط الإنتاج والمزالق

غيّر جهاز توجيه التطبيقات Next.js بشكل أساسي الطريقة التي نبني بها تطبيقات React، وبحلول Next.js 16، نضجت الأنماط لتصبح شيئًا جاهزًا للإنتاج حقًا. لكن التحول المفاهيمي من جهاز توجيه الصفحات يعد أمرًا حادًا - فمكونات الخادم، والعرض المسبق الجزئي، والتخطيطات المتداخلة، ونموذج جلب البيانات المعاد تصميمه بالكامل، كلها تتطلب إعادة صياغة النموذج العقلي الذي لا يمكن للوثائق وحدها نقله بشكل كامل.

يغطي هذا الدليل الأنماط التي تهم فعليًا في الإنتاج: تلك التي تمنع تسمم ذاكرة التخزين المؤقت، وتتخلص من حزم العملاء غير الضرورية، وتحافظ على حيوية الويب الأساسية خضراء على نطاق واسع. سنستفيد من تجربة إنشاء تطبيق Next.js 16 المكون من 249 صفحة مع i18n ذو 11 لغة وصور OG الديناميكية والعرض من جانب الخادم لـ 5577 ملف محتوى MDX.

الوجبات الرئيسية

لا تستخدم مطلقًا export const metadata على الصفحات التي تحتاج إلى تحسين محركات البحث المدركة للغة - استخدم دائمًا generateMetadata()

مكونات الخادم هي المكونات الافتراضية؛ أضف 'use client' فقط عندما تحتاج إلى التفاعل فعليًا

loading.tsx وerror.tsx يتواجدان مع جزء المسار الخاص بهما، وليس عند الجذر

الملف proxy.ts هو البرنامج الوسيط لـ Next.js 16 — لا تقم بإنشاء كل من middleware.ts و proxy.ts

fetch() في مكونات الخادم يقوم تلقائيًا بإلغاء تكرار الطلبات المتطابقة داخل نفس العرض

unstable_cache مع العلامات يتيح إبطال ذاكرة التخزين المؤقت الجراحية دون إعادة التحقق من كل شيء

generateStaticParams() مطلوب للمسارات الديناميكية التي تريد إنشاءها بشكل ثابت في وقت الإنشاء

يجب أن تقوم البيانات المنظمة JSON-LD بتطهير اختراقات البرنامج النصي باستخدام تشفير Unicode

النموذج العقلي لمكونات الخادم

أكبر خطأ يرتكبه المطورون باستخدام جهاز توجيه التطبيقات هو الوصول إلى 'use client' مبكرًا. في Next.js 16، كل مكون في الدليل app/ هو مكون خادم افتراضيًا. هذا هو الإعداد الافتراضي الصحيح - يتم عرض مكونات الخادم على الخادم، وليس لها أي تأثير على حزمة JavaScript، ويمكنها الوصول مباشرة إلى قواعد البيانات وواجهات برمجة التطبيقات.

القاعدة: ادفع 'use client' إلى أوراق الشجرة المكونة الخاصة بك. يمكن أن تكون الصفحة عبارة عن مكون خادم يقوم بجلب البيانات وتمريرها إلى غلاف مكون عميل رفيع يتعامل مع التفاعلات.

// app/[locale]/blog/[slug]/page.tsx — Server Component (no directive needed)
import { getBlogPost } from '@/lib/blog';
import { BlogContent } from '@/components/blog/blog-content'; // Client Component

export default async function BlogPostPage({
  params,
}: {
  params: Promise<{ slug: string; locale: string }>;
}) {
  const { slug, locale } = await params;
  const post = await getBlogPost(slug, locale);

  if (!post) notFound();

  return (
    <article>
      <h1>{post.title}</h1>
      {/* Server Component — no JS sent to browser */}
      <PostMeta author={post.author} date={post.date} />
      {/* Client Component — only this file sent as JS */}
      <BlogContent content={post.content} />
    </article>
  );
}

// components/blog/blog-content.tsx — Client Component
'use client';

import { useState } from 'react';

export function BlogContent({ content }: { content: string }) {
  const [expanded, setExpanded] = useState(false);

  return (
    <div>
      <div>{content}</div>
      {/* Client-side interactivity lives here */}
    </div>
  );
}

الفكرة الرئيسية: BlogContent يرسل JavaScript إلى المتصفح. PostMeta لا. كل توجيه 'use client' غير ضروري يؤدي إلى تضخيم الحزمة الخاصة بك.

توليد البيانات الوصفية عبر البيانات الوصفية الثابتة

يعد export const metadata الثابت أمرًا مغريًا بسبب بساطته، لكنه لا يمكن أن يكون على دراية باللغة المحلية، ولا يمكنه الوصول إلى معلمات المسار، ولا يمكنه جلب البيانات. لأي تطبيق حقيقي، generateMetadata() هو الاختيار الصحيح الوحيد:

// app/[locale]/blog/[slug]/page.tsx
import type { Metadata } from 'next';
import { getTranslations } from 'next-intl/server';

export async function generateMetadata({
  params,
}: {
  params: Promise<{ slug: string; locale: string }>;
}): Promise<Metadata> {
  const { slug, locale } = await params;
  const post = await getBlogPost(slug, locale);

  if (!post) return {};

  const locales = ['en', 'zh', 'es', 'ar', 'pt', 'fr', 'de', 'ja', 'tr', 'hi', 'ur'];

  return {
    title: post.title,
    description: post.description,
    alternates: {
      canonical: `https://ecosire.com/${locale === 'en' ? '' : locale + '/'}blog/${slug}`,
      languages: Object.fromEntries(
        locales.map((loc) => [
          loc,
          `https://ecosire.com/${loc === 'en' ? '' : loc + '/'}blog/${slug}`,
        ])
      ),
    },
    openGraph: {
      title: post.title,
      description: post.description,
      images: [`/api/og/blog/${slug}?locale=${locale}`],
      type: 'article',
      publishedTime: post.date,
    },
  };
}

يُنشئ الحقل alternates.languages علامات hreflang لكل لغة، وهي ضرورية لتحسين محركات البحث متعددة اللغات. تستخدم محركات البحث هذه لتقديم إصدار اللغة الصحيح لكل مستخدم.

التخطيطات المتداخلة والحالة المشتركة

يعد نظام التخطيط المتداخل لجهاز توجيه التطبيقات قويًا ولكن به قيود غير واضحة: لا يمكن للتخطيطات تمرير البيانات إلى أطفالها عبر الدعائم. الحل البديل هو إما سياق التفاعل (مكونات العميل فقط) أو جلب البيانات بشكل مستقل على كل مستوى.

app/
  [locale]/
    layout.tsx          <- Locale layout: fonts, i18n provider, theme
    page.tsx            <- Homepage
    blog/
      layout.tsx        <- Blog layout: sidebar, breadcrumbs
      page.tsx          <- Blog list
      [slug]/
        layout.tsx      <- Post layout: reading progress, TOC
        page.tsx        <- Post content
        loading.tsx     <- Skeleton while post loads
        error.tsx       <- Error boundary for this segment

كل layout.tsx يغلف أطفاله بشكل مستقل. لا تكون البيانات التي يتم جلبها في التخطيط الأصلي متاحة تلقائيًا للأطفال — حيث يقوم كل مكون يحتاج إلى البيانات بجلبها بشكل مستقل. يقوم Next.js 16 بإلغاء تكرار استدعاءات fetch() المتطابقة ضمن دورة العرض، لذا فإن هذا ليس مكلفًا كما يبدو.

// app/[locale]/layout.tsx
import { NextIntlClientProvider } from 'next-intl';
import { getMessages } from 'next-intl/server';

export default async function LocaleLayout({
  children,
  params,
}: {
  children: React.ReactNode;
  params: Promise<{ locale: string }>;
}) {
  const { locale } = await params;
  const messages = await getMessages();

  return (
    <html lang={locale} dir={['ar', 'ur'].includes(locale) ? 'rtl' : 'ltr'}>
      <body>
        <NextIntlClientProvider messages={messages}>
          {children}
        </NextIntlClientProvider>
      </body>
    </html>
  );
}

استراتيجية التخزين المؤقت: الطبقات الأربع

يحتوي Next.js 16 على أربع طبقات تخزين مؤقت مميزة. من الضروري فهم هذه الأمور الأربعة لمعرفة سبب تحديث الصفحة أو عدم تحديثها:

1. طلب التذكير — يتم استدعاء نفس عنوان URL الخاص بـ fetch() خلال دورة عرض واحدة مرة واحدة. تلقائي، لا يوجد تكوين.

**2. ذاكرة التخزين المؤقت للبيانات ** — ثابتة عبر الطلبات. يتم تخزين استجابات fetch() مؤقتًا إلى أجل غير مسمى بشكل افتراضي.

// Force revalidation every hour
const data = await fetch('/api/posts', { next: { revalidate: 3600 } });

// Never cache (equivalent to SSR)
const data = await fetch('/api/posts', { cache: 'no-store' });

3. ذاكرة التخزين المؤقت الكاملة للمسار — يتم تخزين حمولة HTML وRSC الثابتة مؤقتًا في وقت الإنشاء للمسارات الثابتة.

4. ذاكرة التخزين المؤقت لجهاز التوجيه — ذاكرة التخزين المؤقت من جانب العميل للمسارات التي تمت زيارتها. يستمر لجلسة المتصفح.

بالنسبة لاستعلامات قاعدة البيانات (غير جلبية)، استخدم unstable_cache:

import { unstable_cache } from 'next/cache';

const getCachedBlogPosts = unstable_cache(
  async (locale: string) => {
    return db.select().from(posts).where(eq(posts.locale, locale));
  },
  ['blog-posts'], // Cache key
  {
    revalidate: 3600, // Revalidate hourly
    tags: ['blog'], // Tag for manual invalidation
  }
);

// Invalidate from a Server Action or Route Handler:
import { revalidateTag } from 'next/cache';
revalidateTag('blog'); // All blog-tagged caches cleared

حدود الخطأ: مطلوب مستويين

تحتاج تطبيقات الإنتاج إلى حدين للأخطاء: أحدهما للصفحات المدركة للغة المحلية والآخر احتياطي عام للأخطاء على مستوى الجذر.

// app/[locale]/error.tsx — Locale-level error boundary
'use client';

import { useTranslations } from 'next-intl';
import { useEffect } from 'react';

export default function LocaleError({
  error,
  reset,
}: {
  error: Error & { digest?: string };
  reset: () => void;
}) {
  const t = useTranslations('errors');

  useEffect(() => {
    // Log to error tracking service
    console.error(error);
  }, [error]);

  return (
    <div className="flex flex-col items-center justify-center min-h-screen">
      <h2>{t('title')}</h2>
      <p>{t('description')}</p>
      <button onClick={reset}>{t('retry')}</button>
    </div>
  );
}

// app/global-error.tsx — Root fallback (no i18n available here)
'use client';

export default function GlobalError({
  error,
  reset,
}: {
  error: Error & { digest?: string };
  reset: () => void;
}) {
  // Cannot use useTranslations here — no NextIntlClientProvider above
  // Use inline styles — no Tailwind in root error boundaries
  return (
    <html>
      <body>
        <div style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', padding: '2rem' }}>
          <h2 style={{ fontSize: '1.5rem', fontWeight: 'bold' }}>Something went wrong</h2>
          <button
            onClick={reset}
            style={{ marginTop: '1rem', padding: '0.5rem 1rem', cursor: 'pointer' }}
          >
            Try again
          </button>
        </div>
      </body>
    </html>
  );
}

يحل global-error.tsx محل الجذر layout.tsx عند تنشيطه، لذلك يجب أن يتضمن علامتي <html> و<body>. لا يمكنه الوصول إلى موفري السياق الذين يعيشون في التخطيط - لا يوجد i18n، ولا موضوع، ولا سياق مصادقة.

البرامج الوسيطة: proxy.ts vs middleware.ts

يستخدم Next.js middleware.ts (أو middleware.js) للبرمجيات الوسيطة. في المشروع الذي يستخدم next-intl v4، غالبًا ما تتم إعادة تسمية إعداد البرنامج الوسيط إلى proxy.ts وإعادة تصديره، مما يؤدي إلى حدوث مأزق حرج: لا تقم بإنشاء كل من middleware.ts وproxy.ts. يؤدي وجود كلاهما إلى حدوث خطأ في البناء.

النمط الصحيح لدمج i18n مع حماية المصادقة:

// src/proxy.ts — This IS the Next.js middleware
import createMiddleware from 'next-intl/middleware';
import { NextRequest, NextResponse } from 'next/server';
import { routing } from './i18n/routing';

const intlMiddleware = createMiddleware(routing);

const protectedPaths = ['/dashboard', '/portal'];

export default function middleware(request: NextRequest) {
  const { pathname } = request.nextUrl;

  // Check auth for protected paths
  const isProtected = protectedPaths.some((path) =>
    pathname.includes(path)
  );

  if (isProtected) {
    const token = request.cookies.get('ecosire_auth');
    if (!token) {
      const url = request.nextUrl.clone();
      url.pathname = '/auth/login';
      // Prevent open redirect — never allow // prefix
      const redirect = pathname.startsWith('//') ? '/' : pathname;
      url.searchParams.set('redirect', redirect);
      return NextResponse.redirect(url);
    }
  }

  return intlMiddleware(request);
}

export const config = {
  matcher: ['/((?!api|_next/static|_next/image|favicon.ico|.*\\..*).*)'],
};

يعالج هذا الملف الفردي كلاً من اكتشاف لغة i18n وحماية المصادقة. يستثني config.matcher الملفات الثابتة ومسارات API والمكونات الداخلية لـ Next.js.

أمن البيانات المنظمة JSON-LD

تعد البرامج النصية JSON-LD من ناقلات XSS الشائعة. إذا كانت بياناتك تحتوي على علامة برنامج نصي للإغلاق، فيمكن أن تنفصل عن كتلة البرنامج النصي. الإصلاح إلزامي — قم بتشفير الحرف الأقل من:

// components/seo/JsonLd.tsx
interface JsonLdProps {
  data: Record<string, unknown>;
}

export function JsonLd({ data }: JsonLdProps) {
  // Sanitize script tag breakout attempts by encoding '<' as unicode
  const json = JSON.stringify(data).replace(/</g, '\\u003c');

  return (
    <script
      type="application/ld+json"
      // Safe: content is JSON-serialized and sanitized above
      suppressHydrationWarning
      ref={(el) => { if (el) el.textContent = json; }}
    />
  );
}

الاستخدام في الصفحة:

<JsonLd
  data={{
    '@context': 'https://schema.org',
    '@type': 'BlogPosting',
    headline: post.title,
    description: post.description,
    inLanguage: locale,
    author: {
      '@type': 'Organization',
      name: 'ECOSIRE',
    },
  }}
/>

يعد الحقل inLanguage ضروريًا لتحسين محركات البحث متعدد اللغات - فهو يخبر برامج زحف الذكاء الاصطناعي ومحركات البحث باللغة التي يوجد بها المحتوى، مما يحسن دقة التصنيف للاستعلامات غير الإنجليزية.

صور OG الديناميكية

تقوم واجهة برمجة التطبيقات ImageResponse الخاصة بـ Next.js 16 بإنشاء صور OG لكل صفحة على الحافة. الإعداد لمشاركات المدونة:

// app/api/og/blog/[slug]/route.tsx
import { ImageResponse } from 'next/og';

export const runtime = 'edge';

export async function GET(
  request: Request,
  { params }: { params: Promise<{ slug: string }> }
) {
  const { slug } = await params;
  const post = await getPostMeta(slug);

  return new ImageResponse(
    (
      <div
        style={{
          display: 'flex',
          flexDirection: 'column',
          justifyContent: 'flex-end',
          width: '100%',
          height: '100%',
          background: 'linear-gradient(135deg, #0a0a0a 0%, #1a1a2e 100%)',
          padding: '60px',
        }}
      >
        <div style={{ fontSize: 48, fontWeight: 700, color: 'white', lineHeight: 1.2 }}>
          {post.title}
        </div>
        <div style={{ fontSize: 24, color: '#94a3b8', marginTop: 20 }}>
          {post.description}
        </div>
      </div>
    ),
    { width: 1200, height: 630 }
  );
}

المخاطر والحلول الشائعة

المأزق 1: جلب البيانات في مكونات العميل عندما تعمل مكونات الخادم

إذا كان أحد المكونات يعرض البيانات فقط ولا يحتاج إلى واجهات برمجة تطبيقات حالة React أو المتصفح، فيجب أن يكون مكون خادم. تؤدي إضافة 'use client' إلى فرض كل شيء يتم استيراده إلى حزمة العميل.

المأزق 2: حدود التشويق المفقودة حول مكونات الخادم غير المتزامنة

// Without Suspense — entire page blocks until data loads
export default async function Page() {
  const data = await slowFetch(); // 2 seconds
  return <div>{data}</div>;
}

// With Suspense — page streams, slow part shows skeleton
export default function Page() {
  return (
    <Suspense fallback={<DataSkeleton />}>
      <SlowDataComponent />
    </Suspense>
  );
}

المأزق 3: استخدام ملفات تعريف الارتباط() أو الرؤوس() في الوظائف المخزنة مؤقتًا

cookies() وheaders() عبارة عن واجهات برمجة التطبيقات الديناميكية التي تختار المسار إلى العرض الديناميكي. يؤدي استخدامها داخل رد الاتصال unstable_cache إلى قطع ذاكرة التخزين المؤقت بصمت.

المأزق 4: نسيان انتظار المعلمات في Next.js 16

في Next.js 16، أصبح params الآن وعدًا. يؤدي نسيان await إلى حدوث أخطاء في وقت التشغيل:

// Next.js 15 — params was synchronous
export default function Page({ params }: { params: { slug: string } }) {
  const { slug } = params;
}

// Next.js 16 — params is async
export default async function Page({
  params,
}: {
  params: Promise<{ slug: string }>;
}) {
  const { slug } = await params; // Required
}

الأسئلة المتداولة

متى يجب علي استخدام generatorStaticParams()‎ مقابل العرض الديناميكي؟

استخدم generateStaticParams() للمحتوى الذي يتغير بشكل غير متكرر (منشورات المدونة، صفحات المنتج، الوثائق). يؤدي هذا إلى إنشاء HTML ثابت في وقت الإنشاء دون أي تكلفة وقت تشغيل. استخدم العرض الديناميكي للمحتوى المخصص، أو البيانات في الوقت الفعلي، أو الصفحات التي تحتوي على آلاف المتغيرات حيث يكون وقت الإنشاء باهظًا. ادمج كليهما مع ISR (revalidate) للمحتوى الذي يتغير من حين لآخر.

كيف أتعامل مع المصادقة في جهاز توجيه التطبيقات؟

قم بتخزين رموز المصادقة المميزة في ملفات تعريف الارتباط HttpOnly - لا تستخدم التخزين المحلي أو تخزين الجلسة مطلقًا. استخدم البرامج الوسيطة (proxy.ts) للتحقق من وجود ملفات تعريف الارتباط للمسارات المحمية. في مكونات الخادم، اقرأ ملفات تعريف الارتباط التي تحتوي على cookies() من next/headers. قم بتمرير بيانات المستخدم من الخادم إلى العميل عبر الدعائم أو سياق التفاعل، وليس من خلال إعادة قراءة ملف تعريف الارتباط في مكونات العميل.

ما الفرق بين Load.tsx وSuspense؟

loading.tsx هو ملف خاص يقوم Next.js بتغليفه تلقائيًا في حدود معلقة لمقطع المسار بأكمله. ويظهر على الفور أثناء تحميل المحتوى غير المتزامن للمقطع. تمنحك حدود Suspense اليدوية تحكمًا أفضل — حيث يمكنك إظهار هياكل مختلفة لأجزاء مختلفة من الصفحة. كلاهما يستخدم نفس آلية React Suspense الأساسية.

كيف يمكنني مشاركة الحالة بين مكونات الخادم والعميل؟

لا يمكنك ذلك — يتم عرض مكونات الخادم مرة واحدة وليس لها حالة وقت تشغيل. تمرير البيانات من الخادم إلى العميل عبر الدعائم. بالنسبة للحالة من جانب العميل التي تحتاج إلى الاستمرار عبر عمليات التنقل، استخدم معلمات بحث URL (للحالة القابلة للمشاركة)، أو Zustand أو Redux (للحالة المؤقتة)، أو ملفات تعريف الارتباط (لتفضيلات المستخدم). لا تحاول أبدًا استيراد حالة مكون العميل إلى مكون الخادم.

كيف أقوم بإعداد Turbopack للتطوير؟

أضف --turbo إلى برنامج التطوير الخاص بك: "dev": "next dev --turbo". Turbopack عبارة عن أداة تجميع مبنية على الصدأ من Next.js 16 مع عمليات تشغيل باردة وHMR أسرع بشكل ملحوظ. إنه جاهز للإنتاج لمعظم المشاريع ولكنه يحتوي على بعض حالات عدم توافق المكونات الإضافية لحزمة الويب. تحقق من تبعياتك المحددة مقابل قائمة توافق Turbopack قبل التبديل.

الخطوات التالية

يعد إنشاء تطبيق إنتاج Next.js 16 الذي يتعامل مع 11 لغة وآلاف الصفحات ومتطلبات الأداء على مستوى المؤسسة بمثابة مهمة هندسية هامة. لقد قام فريق الواجهة الأمامية في ECOSIRE بشحن هذا بالضبط - منصة Next.js 16 المكونة من 249 صفحة مع تحسين محركات البحث متعددة اللغات، وصور OG الديناميكية، وأوقات استجابة أقل من الثانية.

إذا كنت تعمل على توسيع نطاق تطبيق Next.js الخاص بك أو تحتاج إلى دعم هندسي للواجهة الأمامية للمؤسسة، استكشف خدمات التطوير لدينا لترى كيف يمكننا مساعدتك.

Next.js 16 App Router: Production Patterns and Pitfalls