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

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

export const dynamic = 'auto'
export const dynamicParams = true
export const revalidate = false
export const fetchCache = 'auto'
export const runtime = 'nodejs'
export const preferredRegion = 'auto'
export const maxDuration = 5

export default function MyComponent() {}

export const dynamic = 'auto'
export const dynamicParams = true
export const revalidate = false
export const fetchCache = 'auto'
export const runtime = 'nodejs'
export const preferredRegion = 'auto'
export const maxDuration = 5

export default function MyComponent() {}

معلومة مفيدة:

• يجب أن تكون قيم خيارات التكوين قابلة للتحليل الثابت حالياً. على سبيل المثال revalidate = 600 صالحة، لكن revalidate = 60 * 10 غير صالحة.

الخيارات

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': إجبار التصيير الديناميكي (dynamic rendering)، مما سيؤدي إلى تصيير المسارات لكل مستخدم عند وقت الطلب. هذا الخيار يعادل getServerSideProps() في دليل pages.

• 'error': إجبار التصيير الثابت وتخزين بيانات التخطيط أو الصفحة عن طريق التسبب في خطأ إذا استخدمت أي مكونات وظائف ديناميكية (dynamic functions) أو بيانات غير مخزنة مؤقتاً. هذا الخيار يعادل:

  • getStaticProps() في دليل pages.
  • تعيين خيار كل طلب fetch() في تخطيط أو صفحة إلى { cache: 'force-cache' }.
  • تعيين تكوين المقطع إلى fetchCache = 'only-cache', dynamicParams = false.
  • dynamic = 'error' يغير الافتراضي لـ dynamicParams من true إلى false. يمكنك العودة إلى تصيير الصفحات ديناميكياً للمعلمات الديناميكية التي لم يتم إنشاؤها بواسطة generateStaticParams عن طريق تعيين dynamicParams = true يدوياً.

• 'force-static': إجبار التصيير الثابت وتخزين بيانات التخطيط أو الصفحة عن طريق إجبار cookies()، و headers() و useSearchParams() على إرجاع قيم فارغة.

معلومة مفيدة:

• يمكن العثور على إرشادات حول كيفية الترقية من 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.
• عندما يكون dynamicParams = true، يستخدم المقطع تصيير الخادم المتدفق (Streaming Server Rendering).
• إذا تم استخدام dynamic = 'error' و dynamic = 'force-static'، فسيغير الافتراضي لـ dynamicParams إلى false.

revalidate

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

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

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

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

معلومة مفيدة: خيار revalidate متاح فقط عند استخدام وقت تشغيل Node.js (Node.js Runtime). هذا يعني أن استخدام خيار revalidate مع 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

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

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

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

تعلم المزيد عن وقت تشغيل Edge و Node.js (Edge and Node.js runtimes).

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 لإضافة حدود تنفيذ محددة. على سبيل المثال، على Vercel.

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

export const maxDuration = 5

export const maxDuration = 5

معلومة مفيدة:

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

generateStaticParams

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

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