الترحيل من vercel.json إلى vercel.ts: ما تعلمناه من إعدادات Vercel المكتوبة بـ TypeScript

أهم النقاط

يُعد vercel.ts الطريقة الموصى بها حاليًا لإعداد مشروع على Vercel، ليحل محل ملف vercel.json الثابت.

استيراد VercelConfig من @vercel/config/v1 يمنحك كائن إعدادات مزوّدًا بالأنواع، فخطأ إملائي في مفتاح مثل rewrtes يوقف عملية البناء بدل أن يمر بصمت دون أي تأثير — وهو أمر لا يستطيع ملف JSON العادي اكتشافه.

دوال مساعدة مثل routes.rewrite() و routes.redirect() و routes.cacheControl() تحل محل الشكل الخام لمصفوفات الكائنات في vercel.json الخاص بإعادة الكتابة وإعادة التوجيه والرؤوس.

ملف vercel.ts هو كود TypeScript قابل للتنفيذ يُقيَّم وقت البناء والنشر، لذلك يمكنه قراءة متغيرات البيئة وتفريع المنطق حسب كل بيئة، وهو أمر لا يمكن لملف JSON بحت فعله من الأساس.

لا يعمل vercel.ts مع كل طلب على حدة. منطق التفريع وقت الطلب (كوكيز اختبار A/B، بوابات التوثيق) يبقى مكانه في Middleware لـ Next.js أو في Routing Middleware المستقل عن إطار العمل من Vercel، وليس في هذا الملف.

في Devya نتعامل مع إعدادات المشروع كما نتعامل مع أي ملف JSON كان يحمل قرارات ضمنية: بمجرد أن يصبح بإمكانه التحول إلى TypeScript، يجب أن يتحول. ملف vercel.json لم يكن يشتكي أبدًا من مفتاح مكتوب بشكل خاطئ، أو عبارة cron غير صحيحة، أو نمط إعادة كتابة لا يطابق أي شيء — كان فقط لا يفعل شيئًا بصمت، وكنا نكتشف ذلك في بيئة الإنتاج. يحل vercel.ts هذه المشكلة بجعل ملف الإعدادات وحدة حقيقية يتحقق منها مترجم TypeScript قبل أن تبدأ عملية النشر.

ما هو vercel.ts، ولماذا يحل محل vercel.json؟

ملف vercel.ts هو ملف TypeScript في جذر المشروع يُصدّر كائن إعدادات مزوّدًا بالأنواع يصف إعدادات البناء والتوجيه والرؤوس والمهام المجدولة (crons) لمشروع على Vercel. أضافت Vercel هذا الملف كصيغة الإعدادات الموصى بها، مبني على حزمة @vercel/config، ليحل محل ملف JSON الخالي من أي مخطط تحقق والذي استخدمته جميع مشاريع Vercel منذ الإصدارات الأولى للمنصة.

المشكلة الجوهرية التي يحلها هي أن vercel.json بيانات لا كود. ملف بيانات لا يمكنه التحقق من صحة نفسه، ولا يمكنه الإشارة إلى متغير بيئة، ولا يمكنه التعبير عن "نفّذ X في بيئة المعاينة وY في الإنتاج" دون كتابة سكربت يولّد ملف JSON يدويًا قبل البناء. أما vercel.ts فهو وحدة Node عادية، فتتحول هذه الثلاث قدرات إلى TypeScript عادي.

كيف يبدو ملف vercel.ts عامل بشكل صحيح؟

مثال بسيط وواقعي لتطبيق Next.js يُمرّر الطلبات إلى واجهة برمجية خلفية ويشغّل مهمة تنظيف ليلية: يستورد routes و VercelConfig من @vercel/config/v1، ثم يُصدّر كائن إعدادات يضبط buildCommand على سكربت البناء في npm، وframework على nextjs، وإعادة كتابة من /api/(.*) إلى عنوان خلفي عبر routes.rewrite()، وإعادة توجيه دائمة من مسار وثائق قديم عبر routes.redirect()، ورأس تخزين مؤقت طويل الأمد على الملفات الثابتة عبر routes.cacheControl()، ومهمة cron ليلية تستدعي مسار تنظيف وفق جدول crontab معتاد.

يتم التحقق من كل حقل في هذا الكائن مقابل نوع VercelConfig وقت البناء. إذا كتبت عبارة جدولة cron بشكل خاطئ، أو مررت وجهة إعادة كتابة ليست نصًا، تفشل عملية البناء محليًا قبل أن تصل أي بايت إلى خوادم بناء Vercel.

كيف نرحّل ملف vercel.json قائم دون كسر نشر يعمل؟

رحّل مجموعة إعدادات واحدة في كل مرة، لا الملف كاملًا في التزام واحد. أولًا، ثبّت @vercel/config كاعتمادية تطوير. ثانيًا، أنشئ vercel.ts ورحّل buildCommand وframework أولًا، لأن هذين الحقلين أقل احتياجًا لأي منطق. ثالثًا، رحّل rewrites إلى استدعاءات routes.rewrite()، وredirects إلى routes.redirect()، وheaders إلى routes.cacheControl() أو الدالة المساعدة العامة للرؤوس، مع مطابقة كل زوج مصدر ووجهة بدقة. رابعًا، رحّل crons في الأخير، لأن عبارة cron الخاطئة هي أسهل خطأ يمكن تفويته عند مراجعة الفرق.

شغّل عملية بناء كاملة محليًا قبل حذف vercel.json، ثم انشر إلى بيئة معاينة وقارن رؤوس الاستجابة وسلوك إعادة التوجيه مقابل النشر السابق في الإنتاج. لا تحذف vercel.json إلا بعد التحقق من بيئة المعاينة. الاحتفاظ بالملفين "للاحتياط" يعني مصدرين للحقيقة لنفس الإعدادات، وهذا خلل انحراف ينتظر أن يحدث.

ما الذي يتعطل فعليًا عندما تتحول الإعدادات إلى TypeScript قابل للتنفيذ؟

ظهرت لدينا ثلاثة أنماط فشل في عمليات الترحيل الخاصة بنا، وليست أي منها افتراضية.

انحراف الإعدادات بين بيئة المعاينة والإنتاج يحدث لأن vercel.ts يُنفَّذ كشيفرة حقيقية، فقيمة Date.now() أو قيمة عشوائية مضمّنة في كائن الإعدادات تختلف من تشغيل لآخر. الحل هو التعامل مع vercel.ts كملف نقي وحتمي: بلا ساعات، بلا عشوائية، وبلا استدعاءات شبكة داخل الملف.

قراءة متغير بيئة كـ undefined داخل الإعدادات تحدث لأن الملف يُقيَّم وقت البناء، فلا يرى إلا المتغيرات المكشوفة لخطوة البناء، وليس الأسرار الخاصة بوقت التشغيل فقط. الحل هو التأكد من ضبط المتغير لبيئة البناء في إعدادات المشروع، لا لبيئة الإنتاج أو المعاينة وقت التشغيل فقط.

تجاهل نسخة CLI قديمة للملف بالكامل يحدث لأن نسخة من Vercel CLI سابقة لدعم vercel.ts لا تعرف أنها يجب أن تقيّمه. الحل هو تثبيت نسخة CLI في بيئة CI وترقيتها بشكل متعمد، لا كأثر جانبي لأمر تثبيت عام.

هل يحل vercel.ts محل next.config.ts أيضًا؟

لا. يضبط next.config.ts إطار عمل Next.js نفسه — نطاقات الصور، الأعلام التجريبية، خط أنابيب البناء الخاص بـ Next. أما vercel.ts فيضبط طبقة منصة Vercel أسفل أي إطار عمل — التوجيه، المهام المجدولة، أمر البناء، والرؤوس التي تنطبق بغض النظر عمّا يولّد الاستجابة. يتداخل الملفان عند الحواف، لأن كلاهما يمكنه تعريف الرؤوس وإعادة التوجيه. عند التداخل، اختر ملفًا واحدًا بالضبط يملك قاعدة معينة؛ تعريف نفس إعادة التوجيه في الملفين هو الطريقة التي ينتهي بها الأمر بتتبّع حلقة إعادة توجيه في منتصف الليل.

الأسئلة الشائعة

س: هل يحل vercel.ts محل vercel.json بالكامل، أم يمكننا الاحتفاظ بكليهما؟

ج: لا تزال Vercel تقرأ vercel.json إن كان موجودًا، لكن تشغيل الملفين لنفس المشروع يفتح الباب لتعارضهما. اختر واحدًا واحذف الآخر بعد التحقق من نجاح الترحيل.

س: هل يعمل vercel.ts مع كل طلب وارد؟

ج: لا. يُقيَّم فقط وقت البناء والنشر. التفريع وقت الطلب — بوابات التوثيق، منطق كوكيز اختبار A/B، التوجيه بحسب الموقع الجغرافي — يبقى مكانه في Middleware لـ Next.js أو في Routing Middleware من Vercel، لا في vercel.ts.

س: هل نحتاج إلى تثبيت أي شيء إضافي لاستخدام vercel.ts؟

ج: نعم. ثبّت حزمة @vercel/config واستورد VercelConfig ودوال routes المساعدة من @vercel/config/v1.

س: هل ستقرأ نسخة قديمة من Vercel CLI ملف vercel.ts الجديد؟

ج: نسخة CLI قديمة سابقة لدعم vercel.ts لن تُقيّمه، فثبّت نسخة حديثة في بيئة CI قبل تبني هذا الملف.

س: هل يعمل vercel.ts فقط مع Next.js؟

ج: لا. إنه إعداد منصة مستقل عن إطار العمل، فيعمل بنفس الطريقة مع Nuxt أو SvelteKit أو Astro أو خلفية Node عادية منشورة على Vercel.