انتهاء دعم Node.js 20 على Vercel: ترحيلنا إلى Node 24 LTS

أهم النقاط

أصبح Node.js 20 غير مدعوم (deprecated) على Vercel منذ 1 أكتوبر 2026، كما تم إلغاء Node.js 18 بالكامل كبيئة تشغيل متاحة.

بيئة Node.js 24 LTS هي الافتراضية حاليًا على Vercel، لذا أي مشروع بدون تثبيت صريح لحقل engines.node ينتقل إليها تلقائيًا في النشر (deploy) التالي.

الأعطال التي واجهناها أثناء الترحيل لم تكن في كود التطبيق، بل في إضافات native مثل sharp و better-sqlite3 التي تشحن ملفات ثنائية مبنية مسبقًا لإصدار ABI أقدم من Node.

مهلة التنفيذ الافتراضية للدوال على Vercel أصبحت الآن 300 ثانية، بعد أن كانت بحدود 60-90 ثانية، وهذا يغيّر معنى 'تعلّق النشر' أثناء تصحيح الأخطاء.

ثبّت engines.node في package.json قبل أن يُفرض عليك ترقية الإصدار — اكتشاف بناء native قديم داخل lockfile وسط حادثة في الإنتاج هو أسوأ وقت ممكن لتعلّم هذا الدرس.

ما معنى انتهاء دعم Node.js 20 على Vercel لمشروعك؟

يعني أن Vercel لن يُشغّل الدوال على Node.js 20 بعد الآن، وأي مشروع لا يثبّت إصدار Node بشكل صريح ينتقل إلى Node.js 24 LTS في النشر التالي مباشرة، دون أي تعديل في الكود يُحفّز ذلك. اكتشفنا هذا في مشروع لم يُلمس منذ شهور: فشل نشر عادي في خطوة البناء لأن الملف الثنائي المبني مسبقًا لـ better-sqlite3 لم يطابق إصدار ABI الجديد لـ Node، ثم فشلت محاولة npm البناء من المصدر بسبب غياب رؤوس بناء لم تكن بيئة التشغيل القديمة تحتاجها.

كيف تتحقق من إصدار Node.js الذي يعمل عليه مشروعك على Vercel؟

شغّل الأمر vercel inspect <deployment-url> --logs، أو افتح سجل بناء النشر من لوحة التحكم — إصدار Node مطبوع في أعلى كل سجل بناء. محليًا، قارن node -v مع حقل engines في package.json؛ وإن كان هذا الحقل غير موجود، فالمشروع يعتمد ضمنيًا على ما هو افتراضي حاليًا على Vercel.

ما الذي يتعطل فعليًا عند الترقية من Node.js 20 إلى Node.js 24؟

في تجربتنا، كود التطبيق نفسه نادرًا ما يتعطل عند ترقية إصدار رئيسي من Node على Vercel — العطل يظهر طبقة أسفل، في الاعتماديات native وأدوات البناء. ثلاث حالات أعطال غطّت كل ما واجهناه: عدم تطابق ABI لإضافات native يفرض إعادة بناء من المصدر، استدعاءات مُهمَلة لدالة Buffer() في اعتماديات غير مباشرة تحوّلت من تحذير إلى فشل صريح، وذاكرة تخزين بناء قديمة في أول نشر بعد الترقية. لا شيء من هذا تراجع خاص بـ Node 24 — إنه التكلفة المتراكمة لتخطي إصدارين رئيسيين دفعة واحدة لأن شيئًا لم يفرض ترقية أبكر.

كيف تثبّت إصدار Node.js لنشر على Vercel؟

اضبط حقل engines.node في package.json، مثلًا على "24.x" — يقرأ Vercel هذا الحقل ويُفشل البناء بوضوح إن لم يتطابق، بدلًا من تشغيل إصدار لم يختره أحد بصمت. المشاريع التي تستخدم ملف الإعداد الأحدث vercel.ts يمكنها الاحتفاظ بإعدادات البناء والتوجيه في مكان واحد مع هذا الحقل، لكن حقل engines في package.json يبقى ما يفحصه Vercel لتحديد إصدار بيئة التشغيل نفسها.

ما الذي تغيّر مع Fluid Compute ويؤثر على هذا النوع من الترحيل؟

يعيد Fluid Compute استخدام نسخ الدوال الدافئة عبر طلبات متزامنة متعددة بدل تشغيل نسخة واحدة لكل طلب، ويدعم الآن إيقافًا تدريجيًا وإلغاء الطلبات. هذا مهم لترحيل الإصدار لأن نسخة كانت تعيش لطلب واحد فقط قد تُعاد استخدامها الآن عبر طلبات عدة — فأي تسرّب حالة دقيق على مستوى الطلب نتج عن الترقية، كذاكرة تخزين مؤقت على مستوى الوحدة افترضت بداية باردة كل مرة، يظهر أسرع تحت Fluid Compute مما كان سيظهر تحت نموذج نسخة واحدة لكل طلب القديم.

ما خطة التراجع إذا تعطّل الإنتاج بسبب Node 24؟

احتفظ بالنشر السابق العامل على مسافة أمر واحد: يحتفظ Vercel بالنشرات السابقة، وأمر vercel rollback يُعيد ترقية آخر نشر سليم فورًا دون إعادة بناء. قبل تعديل engines.node في مشروع إنتاجي، افتح نشر معاينة (preview) على الإصدار الجديد أولًا، شغّل مجموعة الاختبارات الحقيقية عليه، واختبر يدويًا أي شيء لا تغطيه الاختبارات — معالجة الصور وإنشاء PDF وقواعد البيانات المدمجة هي المرشحون المعتادون.

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

**س: هل Node.js 18 متاح على Vercel حتى الآن؟**

**ج:** لا. تمت إزالة Node.js 18 بالكامل كبيئة تشغيل متاحة على Vercel؛ المشاريع التي ما زالت تستهدفه يجب أن تُرقّى قبل أن تتمكن من النشر.

**س: هل يتطلب الانتقال من Node 20 إلى Node 24 إعادة كتابة الكود؟**

**ج:** عادة لا. معظم الأعطال مصدرها إضافات native وأدوات البناء، وليس كود JavaScript أو TypeScript على مستوى التطبيق.

**س: هل يغيّر هذا الترحيل أيضًا مهلة تنفيذ الدوال؟**

**ج:** نعم، بشكل مستقل — مهلة تنفيذ الدوال الافتراضية على Vercel أصبحت 300 ثانية على جميع الخطط، بغض النظر عن إصدار Node الذي يعمل عليه المشروع.

**س: هل يوقف تثبيت engines.node الترقيات التلقائية المستقبلية؟**

**ج:** نعم. قيمة engines.node الصريحة تُقفل المشروع على ذلك الإصدار الرئيسي حتى تُغيَّر عن قصد، بدل تتبع الإصدار الافتراضي للمنصة.

**س: هل يجب الترقية مباشرة إلى Node 24 أم التوقف عند Node 22 أولًا؟**

**ج:** الترقية المباشرة إلى Node 24 أفضل إن كانت الاعتماديات تدعمها. إنه خط LTS الحالي الذي يعتمده Vercel افتراضيًا، والتوقف عند 22 يعني فقط تكرار هذا الترحيل لاحقًا.