دليل تعيين إصدار Node.js مستقل لكل مشروع باستخدام ServBay (macOS)

يعد ServBay بيئة تطوير محلية قوية صُممت خصيصًا للمطورين، وتوفر حلًا متكاملًا يشمل لغات برمجة متعددة مثل Node.js، بالإضافة إلى قواعد البيانات وخوادم الويب. من أبرز مميزاته دعمه الفعلي لتعدد إصدارات Node.js وإدارته المرنة لها. من خلال ملف إعداد بسيط، يمكنك تخصيص الإصدار المطلوب لكل مشروع بسهولة دون الاعتماد على أدوات خارجية مثل NVM أو fnm أو الحاجة لاستعمال حاويات Docker، ما يبسّط سير العمل ويتجنب تلوث البيئة العامة للنظام وتعارض الإصدارات بين المشاريع.

في هذا المقال، سنوضح كيفية استخدام ملف إعدادات ServBay .servbay.config للتحكم في إصدار Node.js على مستوى كل مشروع.

لماذا استخدام ملف .servbay.config لإدارة إصدارات Node.js مع ServBay؟

الطرق التقليدية لإدارة إصدارات Node.js (مثل NVM أو التثبيت اليدوي) قد تتسبب في بعض الإشكالات:

• تلوث البيئة العامة وتعارض الإصدارات: تثبيت الإصدارات أو التبديل بينها على مستوى النظام قد يؤدي لتعارض تبعيات بين المشاريع المختلفة بسهولة.
• الاستهلاك الزمني للتثبيت وإعادة البناء: تثبيت إصدارات جديدة أو التبديل بين معماريات مثل x86_64 وarm64 قد يتطلب إعادة بناء الحزم، الأمر الذي يستهلك وقتًا وجهدًا.
• ثقل حاويات Docker: استخدام Docker للحصول فقط على إصدار معين من Node.js قد يكون مبالغًا فيه وغير عملي لمثل هذه الحاجة.

يأتي حل ServBay عبر تثبيت عدة إصدارات شائعة من Node.js مسبقًا (حاليًا يدعم جميع الإصدارات من v12 حتى v23، ويمكنك إدارتها من جزء "الحزم" في التطبيق)، بالإضافة إلى إمكانيات ملف .servbay.config ما يوفر:

• تبديل فوري: جميع الإصدارات مثبتة مسبقًا، ما يجعل التبديل شبه لحظي.
• عزل المشاريع: الإعدادات تطبق فقط على مجلد المشروع، لضمان عزل بيئة العمل لكل مشروع.
• لا تلوث للبيئة العامة: لا يتم تعديل إعدادات النظام العامة، ما يحافظ على نظافة بيئته.
• تكامل مع ServBay: تندمج هذه الآلية ضمن بيئة ServBay بالكامل، لتعمل بتناغم مع حزم أخرى يديرها كـ PHP وقواعد البيانات وخوادم الويب.

المتطلبات الأساسية

يرجى التأكد قبل البدء من:

1. أنك قمت بتثبيت وتشغيل ServBay على نظام macOS بنجاح.
2. أنك فعّلت الإصدار المطلوب من Node.js عن طريق واجهة تطبيق ServBay ضمن قائمة "الحزم" (Packages).
3. لديك مجلد مشروع يتطلب تخصيص إصدار محدد من Node.js.

المبدأ الأساسي

عند استخدامك الطرفية المدمجة في ServBay، يراقب البيئة الحالية للمجلد. بمجرد دخولك مجلدًا باستخدام أمر cd، يبحث ServBay عن ملف باسم .servbay.config في هذا المجلد أو أي من مجلداته الأب حتى الجذر، ويقرأ الإعداد من أقرب ملف تم العثور عليه. عندها، يحدث البيئة تلقائيًا (مثل متغير PATH) للإشارة إلى مسار التثبيت الخاص بإصدار Node.js المحدد في الإعداد.

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

خطوات الإعداد

تعيين إصدار مستقل من Node.js لكل مشروع مسألة سهلة جدًا:

الخطوة الأولى: إنشاء وتعديل ملف .servbay.config

اذهب إلى مجلد الجذر لمشروعك (غالبًا حيث يوجد ملف package.json).

افتح ملف إعداد جديد باسم .servbay.config باستخدام محررك المفضل، ثم أضف المحتوى التالي:

# تحديد رقم الإصدار الرئيسي لـ Node.js الذي سيستخدمه المشروع
# ServBay سيختار تلقائيًا أحدث إصدار متوفر من هذا الفرع
NODE_VERSION=20

# اختياري: تعيين مرآة npm أو pnpm لتسريع تحميل الاعتمادات
# إن كنت في الصين مثلا، يوصى باستخدام مرآة محلية
YARN_CONFIG_REGISTRY=https://npmreg.proxy.ustclug.org/
NPM_CONFIG_REGISTRY=https://registry.npmmirror.com

# اختياري: تحديد مجلد كاش npm أو pnpm
# من الأفضل وضع الكاش في المجلد المؤقت لـ ServBay لتفادي تلوث النظام أو مجلد المستخدم
NPM_CONFIG_CACHE=/Applications/ServBay/tmp/npm/cache

شرح خيارات الإعداد:

• NODE_VERSION: إلزامي. يحدد رقم الإصدار الرئيسي المطلوب لـ Node.js. فعلى سبيل المثال، الإعداد كـ 20 سيستخدم أعلى إصدار متوفر من السلسلة 20.x.x على ServBay. يرجى التأكد أن الإصدار مثبت بالفعل على ServBay.
• YARN_CONFIG_REGISTRY / NPM_CONFIG_REGISTRY: اختياري. تعيين عنوان مرآة تحميل الحزم لـ Yarn أو npm. مفيد جدًا في حال ضعف اتصال الإنترنت.
• NPM_CONFIG_CACHE: اختياري. تحديد مسار كاش npm أو pnpm. وضعه في /Applications/ServBay/tmp/npm/cache يساعد في إدارة الكاش مركزيًا وتفادي تشتت الملفات المؤقتة.

بعد اكتمال التعديلات، احفظ وأغلق الملف.

الخطوة الثانية: التحقق من الإصدار في طرفية ServBay

1. افتح الواجهة الرئيسية لتطبيق ServBay.

2. انقر على زر "طرفية" (Terminal) لتشغيل الطرفية المدمجة.

3. باستخدام أمر cd، انتقل إلى مجلد مشروعك:

   cd /Applications/ServBay/www/your-project-name

   (استبدل /Applications/ServBay/www/your-project-name بمسار مشروعك الفعلي)

4. تحقق من إصدار Node.js عبر الأمر:

   node -v

   يجب أن يظهر في الإخراج الإصدار الذي قمت بتعيينه في ملف .servbay.config (مثلاً v20.x.x).

5. يمكنك كذلك فحص إصدار npm أو pnpm أو yarn عبر الأوامر: npm -v, pnpm -v, yarn -v للتأكد من توافق مدير الحزم كذلك مع إصدار Node.js النشط.

الآن، أي أوامر تتعلق بـ Node.js أو npm/pnpm/yarn داخل هذا المشروع ستستخدم تلقائيًا الإعدادات المحددة في .servbay.config.

مثال عملي

لنوضح كيفية التبديل التلقائي بين إصدارات Node.js عبر مشاريع مختلفة باستخدام .servbay.config.

لنفترض أن لديك مشروعين: project-a بحاجة Node.js v18 وproject-b بحاجة Node.js v20.

1. إنشاء مجلدات المشاريع وملفات الإعداد:

   # أنشئ مجلدات المشاريع تحت www في ServBay
   mkdir /Applications/ServBay/www/project-a
   mkdir /Applications/ServBay/www/project-b
   
   # إعداد Node.js v18 لـ project-a
   echo "NODE_VERSION=18" > /Applications/ServBay/www/project-a/.servbay.config
   
   # إعداد Node.js v20 لـ project-b
   echo "NODE_VERSION=20" > /Applications/ServBay/www/project-b/.servbay.config

2. التحقق من التبديل التلقائي في الطرفية:

   افتح طرفية ServBay ونفذ التالي:

   # انتقل إلى project-a
   cd /Applications/ServBay/www/project-a
   # افحص إصدار Node.js
   node -v
   # متوقع: v18.x.x
   
   # انتقل إلى project-b
   cd ../project-b
   # افحص الإصدار
   node -v
   # متوقع: v20.x.x
   
   # عد إلى project-a
   cd ../project-a
   # افحص الإصدار ثانيةً
   node -v
   # متوقع: v18.x.x

من خلال هذه الخطوات يظهر أن ServBay يحمّل ويطبق تلقائيًا إعداد NODE_VERSION من ملف .servbay.config حسب مجلد المشروع العامل، ما يوفر انتقالًا سلسًا بين بيئات العمل المختلفة.

توضح الصورة التالية كيف يتغير إصدار Node.js تلقائيًا عند الانتقال بين مجلدات المشاريع حسب الإعداد (الصورة لغرض الشرح – قد تختلف الواجهة في الواقع):

ملاحظات هامة

• يجب وضع ملف .servbay.config داخل مجلد المشروع أو أي من المجلدات الأعلى منه. سيبحث ServBay في المسار للأعلى ويستخدم أول ملف يجده (أي الأقرب للمجلد الحالي).
• تأكد من العمل داخل طرفية ServBay أو طرفية خارجية تم تهيئتها بمتغيرات البيئة الخاصة بـ ServBay.
• إصدار NODE_VERSION الذي تعينه واجب أن يكون مثبتًا ومفعّلًا في تطبيق ServBay. إذا لم يكن متوفرًا، قد يرجع ServBay للإصدار الافتراضي أو يتعذر تحديد Node.js.
• إعدادات .servbay.config تطبق فقط على جلسات الطرفية الحالية وتوابعها، ولا تؤثر على بيئة النظام أو أي عمليات تعمل خارج بيئة ServBay.

الأسئلة الشائعة (FAQ)

س: ماذا سيحدث إذا لم يوجد ملف .servbay.config في مجلدي؟

ج: لو لم يعثر ServBay على ملف .servbay.config في المجلد الحالي أو أي من المجلدات الأعلى منه، سيطبق إعداداته العامة أو إصدار Node.js الافتراضي (عادة المحدد كـ "افتراضي" في الإعدادات).

س: كيف أعرف ما هي إصدارات Node.js المدعومة في ServBay؟

ج: افتح تطبيق ServBay وتوجه إلى قسم "الحزم" (Packages) من القائمة اليمنى. سترى قائمة بجميع الإصدارات المتوفرة والمثبتة، ويمكنك تفعيل أو تعطيل أي إصدار بسهولة.

س: هل إعدادات .servbay.config تؤثر على نظامي بالكامل؟

ج: إطلاقًا. إعدادات .servbay.config مؤقتة وتطبق فقط على جلسة الطرفية ضمن ServBay أو العمليات التي تعمل في نفس البيئة. لا تعدّل متغيرات البيئة العامة للنظام أو تؤثر على العمليات خارج ServBay، ما يضمن عزل الإعداد لكل مشروع.

س: هل يمكنني تعيين إعدادات تخص ServBay غير NODE_VERSION في .servbay.config؟

ج: نعم، تدعم ServBay تعيين متغيرات بيئة أخرى بجانب Node.js عبر .servbay.config. يمكنك تمرير أي إعداد بيئي يدعمه ServBay، وتطبيقاته أو التحديثات المستقبلية قد تضيف المزيد من الخيارات، لكن يبقى الهدف الرئيسي تعيين بيئة خاصة لكل مشروع.

الخلاصة

باستخدام ملف .servbay.config في ServBay، يمكنك بسهولة وفاعلية تخصيص وإدارة إصدارات Node.js بشكل مستقل لكل مشروع تطوير محلي. هذه الطريقة أخف وأكثر مرونة من حلول تقليدية كمديري الإصدارات أو الحاويات، وتتكامل بسلاسة مع بيئة التطوير المدمجة في ServBay لتبني سير عمل أكثر استقرارًا وتعاونًا. بادر بتجربة .servbay.config في مشاريعك الآن ويتمتع بسهولة إدارة البيئات مع ServBay!