استكشاف أخطاء Node.js وإصلاحها

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

عدم العثور على إصدار أوامر Node.js/npm/pnpm/yarn أو تعذر العثور عليها

إذا واجهت أثناء استخدامك لـ Node.js أو npm أو pnpm أو yarn ضمن ServBay رسائل خطأ مشابهة لما يلي، فهذا يعني أن النظام لم يتمكن من العثور على نسخة Node.js المحددة التي تحاول استخدامها:

Warning: Specified Node.js version '22' for 'node' not found.
If this is not your intention, please delete the 'NODE_VERSION' configuration
from the '.servbay.config' file in the current directory.

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

ملاحظة

بعد تثبيت ServBay، يقوم النظام بإعداد اختصارات للأوامر تضمن أولوية استخدام نسخ Node.js المُثبتة ضمن ServBay. إذا لم يتم إيجاد النسخة المحددة داخل ServBay، يحاول النظام تلقائياً البحث عن إصدار افتراضي تم تثبيته عبر nvm، ثم عن النسخ التي تمت عبر homebrew. إذا لم يتم العثور على أي منها، سيظهر الخطأ أعلاه.

تحليل السبب:

1. إصدار Node.js المطلوب لم يتم تثبيته عبر تطبيق ServBay.
2. يوجد لديك تثبيتات عبر nvm أو homebrew وتتوقع استخدام الإصدارات التي تديرها هذه الأدوات، لكن بسبب مشكلة في إعداد متغيرات البيئة في الـ shell (خصوصاً متغيرات PATH أو NVM_BIN) يتعذر على ServBay الوصول لهذه النسخ الخارجية.

الحل المقترح:

إذا كنت قد ثبتَّ nvm وقمت بتثبيت إصدار Node.js عن طريقه وما زلت تواجه هذه المشكلة، ففي الغالب السبب هو غياب أو خطأ في تكوين متغير البيئة NVM_BIN في إعدادات الـ shell لديك. عند تثبيت nvm بشكل صحيح يُفترض أن يتم إعداد هذا المتغير تلقائياً بحيث يشير إلى مكان تنفيذ Node.js الذي يديره nvm، وهو أمر أساسي لعمله.

كل ما عليك فعله هو مراجعة وضبط إعدادات ملفات التكوين الخاصة بالـ shell (مثل ~/.zshrc, ~/.bash_profile وغيرها) والحرص على إعداد متغير NVM_BIN وتصديره (export) بشكل صحيح، ثم إعادة تحميل الإعدادات (مثلاً عبر الأمر source ~/.zshrc أو بإعادة تشغيل الطرفية). بعد إصلاح التكوين، يُفترض أن يتمكن ServBay من إيجاد إصدار Node.js المُدار عبر nvm.

إذا كنت لا تستخدم nvm أو homebrew، أو ترغب باستخدام إصدارات Node.js التي يديرها ServBay فقط، تأكد من تثبيت الإصدار الذي ترغب باستخدامه من خلال واجهة “الحزم البرمجية” ضمن تطبيق ServBay.

ظهور رسالة "المعمارية غير مدعومة" عند استخدام حزم npm مثل node-sass

لمستخدمي أجهزة Mac التي تعمل بمعالجات Apple Silicon (مثل M1/M2/M3/M4 بمعمارية Arm64)، قد تظهر رسالة خطأ مثل Unsupported architecture (arm64) عند محاولة استخدام بعض حزم npm القديمة أو التي تعتمد على وحدات برمجية مكتوبة بلغة برمجة أصلية (كمثال: node-sass). يعود السبب إلى أن هذه الحزم القديمة غالباً ما توفر ملفات تنفيذية أو إعدادات متوافقة فقط مع معمارية x86_64.

ERROR: Module Error (from ./node_modules/sass-loader/dist/cjs.js):
Node Sass does not yet support your current environment: OS X Unsupported architecture (arm64) with Node.js 14.x
For more information on which environments are supported
please see:
https://github.com/sass/node-sass/releases/tag/v4.14.1

تحليل السبب:

بعض حزم npm تتضمن شفرة بلغة ++C أو شيفرة برمجية أصلية تتطلب إعادة البرمجة أو ترجمة (build) خصيصاً لكل معمارية معالج. الحزم أو الإصدارات الأقدم غالباً لا توفر دعم جاهز لمعمارية Arm64 مثل معالجات Apple Silicon.

الحلول الممكنة:

1. استخدام بدائل حديثة تدعم معمارية Arm64 (موصى به بشدة):

   أنسب حل هو استبدال الحزم القديمة ببديل حديث متوافق بشكل كامل مع معمارية Arm64. على سبيل المثال، يمكنك استبدال الحزمة القديمة وغير المدعومة node-sass بالحزمة العصرية والموصى بها حالياً sass، والتي أصبحت معظم أدوات تطوير الويب الحديثة تدعمها بالفعل.

   npm uninstall node-sass
   npm install --save-dev sass

2. تثبيت إصدار Node.js بمعمارية x86_64 عبر ServBay وتشغيله من خلال Rosetta 2 (غير موصى به):

   يتيح ServBay إمكانية تثبيت نسخ من Node.js تعمل بمعمارية x86_64. إذا كنت تستخدم جهاز Mac بمعالج Apple Silicon، يمكنك الاستفادة من طبقة الترجمة Rosetta 2 المدمجة في macOS لتشغيل Node.js والحزم التابعة له التي تتطلب هذه المعمارية. يمكنك تثبيت نسخة x86_64 من Node.js عبر واجهة “الحزم البرمجية” في تطبيق ServBay.

   

   ملاحظة هامة: لا يُوصى بهذا الحل على المدى الطويل، لأنه يعتمد على الترجمة الافتراضية عبر Rosetta 2 مما قد يؤدي إلى انخفاض في الأداء أو مشكلات في التوافق القياسي مقارنة بالتشغيل الأصلي على معمارية Arm64. يُنصح باعتماد الحل رقم 1 كلما كان ذلك ممكناً.

---