تكوين قطعة المسار (Route Segment Config)

الخيارات الموضحة في هذه الصفحة تكون معطلة إذا كان علم dynamicIO مفعلاً، وسيتم إهمالها في المستقبل.

تتيح خيارات قطعة المسار تكوين سلوك الصفحة، أو التخطيط، أو معالج المسار عن طريق تصدير المتغيرات التالية مباشرة:

الخيارات

experimental_ppr

تمكين التصيير الجزئي المسبق (PPR) للتخطيط أو الصفحة.

export const experimental_ppr = true
// true | false

export const experimental_ppr = true
// true | false

dynamic

تغيير السلوك الديناميكي للتخطيط أو الصفحة ليصبح ثابتًا بالكامل أو ديناميكيًا بالكامل.

export const dynamic = 'auto'
// 'auto' | 'force-dynamic' | 'error' | 'force-static'

export const dynamic = 'auto'
// 'auto' | 'force-dynamic' | 'error' | 'force-static'

ملاحظة جيدة: النموذج الجديد في دليل app يفضل التحكم الدقيق في التخزين المؤقت على مستوى طلب fetch بدلاً من النموذج الثنائي الكل أو لا شيء لـ getServerSideProps و getStaticProps على مستوى الصفحة في دليل pages. خيار dynamic هو طريقة للعودة إلى النموذج السابق كتسهيل ويوفر مسار هجرة أبسط.

• 'auto' (الافتراضي): الخيار الافتراضي لتخزين أكبر قدر ممكن دون منع أي مكونات من اختيار السلوك الديناميكي.
• 'force-dynamic': فرض التصيير الديناميكي، مما يؤدي إلى تصيير المسارات لكل مستخدم عند وقت الطلب. هذا الخيار يعادل:
  • تعيين خيار كل طلب fetch() في التخطيط أو الصفحة إلى { cache: 'no-store', next: { revalidate: 0 } }.
  • تعيين تكوين القطعة إلى export const fetchCache = 'force-no-store'
• 'error': فرض التصيير الثابت وتخزين بيانات التخطيط أو الصفحة عن طريق التسبب في خطأ إذا استخدمت أي مكونات واجهات برمجة التطبيقات الديناميكية أو بيانات غير مخزنة. هذا الخيار يعادل:
  • getStaticProps() في دليل pages.
  • تعيين خيار كل طلب fetch() في التخطيط أو الصفحة إلى { cache: 'force-cache' }.
  • تعيين تكوين القطعة إلى fetchCache = 'only-cache', dynamicParams = false.
  • dynamic = 'error' يغير الافتراضي لـ dynamicParams من true إلى false. يمكنك العودة إلى تصيير الصفحات ديناميكيًا للمعاملات الديناميكية التي لم يتم إنشاؤها بواسطة generateStaticParams عن طريق تعيين dynamicParams = true يدويًا.
• 'force-static': فرض التصيير الثابت وتخزين بيانات التخطيط أو الصفحة عن طريق إجبار cookies، و headers()، و useSearchParams() على إرجاع قيم فارغة. من الممكن استخدام revalidate، أو revalidatePath، أو revalidateTag في الصفحات أو التخطيطات المصممة بـ force-static.

ملاحظة جيدة:

• يمكن العثور على تعليمات كيفية الهجرة من getServerSideProps و getStaticProps إلى dynamic: 'force-dynamic' و dynamic: 'error' في دليل الترقية.

dynamicParams

التحكم فيما يحدث عند زيارة قطعة ديناميكية لم يتم إنشاؤها باستخدام generateStaticParams.

export const dynamicParams = true // true | false,

export const dynamicParams = true // true | false,

• true (الافتراضي): يتم إنشاء القطع الديناميكية غير المضمنة في `generateStaticParams عند الطلب.
• false: ستعيد القطع الديناميكية غير المضمنة في generateStaticParams خطأ 404.

ملاحظة جيدة:

• يحل هذا الخيار محل خيار fallback: true | false | blocking لـ getStaticPaths في دليل pages.
• لتصيير جميع المسارات ثابتًا في المرة الأولى التي يتم زيارتها فيها، ستحتاج إلى إرجاع مصفوفة فارغة في generateStaticParams أو استخدام export const dynamic = 'force-static'.
• عندما يكون dynamicParams = true، تستخدم القطعة تصيير الخادم المتدفق (Streaming Server Rendering).

revalidate

تعيين وقت إعادة التحقق الافتراضي للتخطيط أو الصفحة. لا يتجاوز هذا الخيار قيمة revalidate المعينة بواسطة طلبات fetch الفردية.

export const revalidate = false
// false | 0 | number

export const revalidate = false
// false | 0 | number

• false (الافتراضي): الاستدلال الافتراضي لتخزين أي طلبات fetch التي تعين خيار cache إلى 'force-cache' أو يتم اكتشافها قبل استخدام واجهة برمجة التطبيقات الديناميكية. يعادل دلاليًا revalidate: Infinity مما يعني بشكل فعال أنه يجب تخزين المورد إلى أجل غير مسمى. لا يزال بإمكان طلبات fetch الفردية استخدام cache: 'no-store' أو revalidate: 0 لتجنب التخزين وجعل المسار مصممًا ديناميكيًا. أو تعيين revalidate إلى رقم موجب أقل من الافتراضي للمسار لزيادة تكرار إعادة التحقق للمسار.
• 0: ضمان تصيير التخطيط أو الصفحة ديناميكيًا دائمًا حتى إذا لم يتم اكتشاف أي واجهات برمجة تطبيقات ديناميكية أو جلب بيانات غير مخزنة. يغير هذا الخيار الافتراضي لطلبات fetch التي لا تعين خيار cache إلى 'no-store' ولكن يترك طلبات fetch التي تختار 'force-cache' أو تستخدم revalidate موجبًا كما هي.
• number: (بالثواني) تعيين تكرار إعادة التحقق الافتراضي للتخطيط أو الصفحة إلى n ثانية.

ملاحظة جيدة:

• يجب أن تكون قيمة إعادة التحقق قابلة للتحليل الثابت. على سبيل المثال revalidate = 600 صالحة، ولكن revalidate = 60 * 10 ليست صالحة.
• قيمة إعادة التحقق غير متاحة عند استخدام runtime = 'edge'.
• في وضع التطوير، يتم تصيير الصفحات دائمًا عند الطلب ولا يتم تخزينها مؤقتًا أبدًا. يسمح لك هذا برؤية التغييرات على الفور دون انتظار انتهاء فترة إعادة التحقق.

تكرار إعادة التحقق

• سيحدد أقل revalidate عبر كل تخطيط وصفحة لمسار واحد تكرار إعادة التحقق للمسار بأكمله. يضمن هذا إعادة التحقق من الصفحات الفرعية بشكل متكرر مثل تخطيطاتها الأصلية.
• يمكن لطلبات fetch الفردية تعيين revalidate أقل من revalidate الافتراضي للمسار لزيادة تكرار إعادة التحقق للمسار بأكمله. يسمح لك هذا بالاشتراك ديناميكيًا في إعادة التحقق الأكثر تكرارًا لمسارات معينة بناءً على بعض المعايير.

fetchCache

export const fetchCache = 'auto'
// 'auto' | 'default-cache' | 'only-cache'
// 'force-cache' | 'force-no-store' | 'default-no-store' | 'only-no-store'

export const fetchCache = 'auto'
// 'auto' | 'default-cache' | 'only-cache'
// 'force-cache' | 'force-no-store' | 'default-no-store' | 'only-no-store'

runtime

نوصي باستخدام وقت تشغيل Node.js لتصيير تطبيقك، ووقت تشغيل Edge للبرمجيات الوسيطة (Middleware).

export const runtime = 'nodejs'
// 'nodejs' | 'edge'

export const runtime = 'nodejs'
// 'nodejs' | 'edge'

• 'nodejs' (الافتراضي)
• 'edge'

preferredRegion

export const preferredRegion = 'auto'
// 'auto' | 'global' | 'home' | ['iad1', 'sfo1']

export const preferredRegion = 'auto'
// 'auto' | 'global' | 'home' | ['iad1', 'sfo1']

يعتمد دعم preferredRegion والمناطق المدعومة على منصة النشر الخاصة بك.

ملاحظة جيدة:

• إذا لم يتم تحديد preferredRegion، فسوف يرث الخيار من أقرب تخطيط أب.
• التخطيط الجذري افتراضيًا لجميع المناطق.

maxDuration

بشكل افتراضي، لا يحد Next.js من تنفيذ المنطق من جانب الخادم (تصيير صفحة أو معالجة API). يمكن لمنصات النشر استخدام maxDuration من إخراج بناء Next.js لإضافة حدود تنفيذ محددة.

ملاحظة: يتطلب هذا الإعداد Next.js 13.4.10 أو أعلى.

export const maxDuration = 5

export const maxDuration = 5

ملاحظة جيدة:

• إذا كنت تستخدم إجراءات الخادم (Server Actions)، فاضبط maxDuration على مستوى الصفحة لتغيير المهلة الافتراضية لجميع إجراءات الخادم المستخدمة في الصفحة.

generateStaticParams

يمكن استخدام الدالة generateStaticParams بالاشتراك مع قطع المسار الديناميكية لتحديد قائمة معلمات قطعة المسار التي سيتم إنشاؤها ثابتًا في وقت البناء بدلاً من عند الطلب في وقت الطلب.

راجع مرجع API لمزيد من التفاصيل.

سجل الإصدارات