استكشاف مشاكل Zinnector® وإصلاحها

الأخطاء التي يواجهها الأشخاص فعلياً مع واجهة أوامر Zinnector والحل الخاص بكل منها: خطأ spawn EINVAL على نظام Windows، وتحذير EBADENGINE الخاص بـ npm، ومطالبة node-gyp بتثبيت Visual Studio على Node 26، وخطأ EPERM أثناء التثبيت، وبيئة تشغيل ترفض الإقلاع، ومنفذ قيد الاستخدام.

الأخطاء التي يواجهها المستخدمون بالفعل مع واجهة سطر الأوامر (CLI) الخاصة بـ Zinnector®، وما يعنيه كل خطأ، وطريقة إصلاحه. تذكر كل فقرة النص الدقيق الذي ستراه، بحيث يمكنك البحث عنه في هذه الصفحة. إذا لم يكن خطأك موجوداً هنا، فشغّل الأمر الذي فشل مع تعيين ZINNECTOR_DEBUG=1 وافتح مشكلة (issue) على الرابط github.com/Zinn-Digital/zinnector/issues متضمنة الناتج، وإصدار Node لديك (node --version) ونظام تشغيلك.

خطأ "spawn EINVAL" مباشرة بعد قبول تثبيت بيئة التشغيل (Windows)

هذا خطأ في إصداري Zinnector® 0.1.0 و0.1.1. على نظام Windows، كان برنامج تثبيت بيئة التشغيل يشغل npm.cmd بالاسم، وقد رفضت Node تشغيل ملف .cmd بدون غلاف (shell) منذ إصلاح ثغرة CVE-2024-27980، لذا توقف التثبيت عن العمل بعد ثانية واحدة من إجابتك بـ Y. تم الإصلاح في الإصدار 0.1.2: يتم الآن تشغيل npm كـ node npm-cli.js، وهو نفس الأمر على كل المنصات ولا يحتاج إلى غلاف. شغّل npm install -g zinnector@latest، ثم شغّل zinnector dev مرة أخرى.

خطأ "npm WARN EBADENGINE" أثناء التثبيت، أو "Zinnector® needs Node 24 or newer"

إصدار Node لديك أقدم من الإصدار 24. تطبع npm هذا التحذير لأن الحزمة تعلن عن المتطلبات engines: >=24.18.1؛ يكتمل التثبيت على أي حال، ولكن zinnector يرفض بعد ذلك البدء (رمز الخروج 78) بدلاً من الفشل في مكان مربك لاحقاً. قم بتثبيت إصدار الدعم طويل الأمد (LTS) الحالي من nodejs.org — استخدم الأمر winget install OpenJS.NodeJS.LTS على Windows، أو brew install node@24 على macOS — وتأكد من أن الأمر node --version يطبع v24 أو أحدث، ثم ثبت Zinnector® مرة أخرى.

أخطاء "gyp ERR!"، أو "Building from source with node-gyp"، أو "You need to install Visual Studio"

تحتوي بيئة تشغيل WordPress على وحدة أصلية تتوفر ثنائياتها المبنية مسبقاً لـ Node 24 و25 فقط. على إصدار أحدث من Node (الإصدار 26 والأحدث، اعتباراً من سبتمبر 2026)، يلجأ المثبت الخاص بها إلى التجميع من المصدر، وهو ما ينتهي على جهاز Windows عادي بطلب تثبيت Visual Studio. تم الإصلاح في الإصدار 0.1.2: يكتشف Zinnector® هذا الأمر قبل تنزيل أي شيء ويجلب Node 24 لبيئة التشغيل وحدها — بحجم يبلغ نحو 30 ميغابايت، وتم التحقق منه مقابل المجموع الاختبارائي (checksum) لموقع nodejs.org — بحيث لا يتم تجميع أي شيء على الإطلاق. إذا كنت لا تزال ترى هذا الخطأ بعد الترقية، فشغّل zinnector dev --reset-runtime بحيث يتم التخلص من التثبيت غير المكتمل السابق أولاً.

تحذيرات "EPERM" الصادرة عن npm أثناء عملية التنظيف (Windows)

يحدث هذا غالباً بسبب برنامج مكافحة الفيروسات أو أداة فهرسة البحث التي تبقي ملفاً مفتوحاً ضمن مجلد node_modules الخاص بيئة التشغيل بينما تحاول npm إزالته. تتم إعادة محاولة التثبيت من مجلد نظيف عند تشغيل الأمر zinnector dev التالي؛ وإذا استمر حدوث المشكلة، سيقوم الأمر zinnector dev --reset-runtime بإزالة مجلد بيئة التشغيل بالكامل أولاً وإعادة التثبيت.

رسالة "the local playground runtime could not be installed"

تتضمن الرسالة الأسطر الأخيرة الخاصة بـ npm والأمر الدقيق الذي قام Zinnector® بتنفيذه، بحيث يمكنك تشغيله بنفسك ومعرفة الناتج الكامل. الأسباب المعتادة هي مشكلة في الشبكة أو الخادم الوسيط (proxy) — حيث يتم جلب بيئة التشغيل باستخدام npm الخاصة بك، لذا يتم تطبيق إعدادات npm config set proxy … والمرآة السجلية (registry mirror) — أو تثبيت سابق غير مكتمل، والذي يقوم --reset-runtime بمحوه.

رسالة "the local playground exited before it was ready"، أو عدم استعداد بيئة التشغيل أبداً

شغّل zinnector dev --verbose للاطلاع على الناتج الخاص بيئة التشغيل نفسها. غالباً ما يكون السبب هو منفذ مستخدم بالفعل: استخدم zinnector dev --port 9401، أو عيّن قيمة port في ملف zinnector.json. أما إذا ثبتت بيئة التشغيل ولكنها ترفض الإقلاع: فشغّل zinnector dev --reset-runtime. يقوم الإقلاع الأول أيضاً بتنزيل WordPress نفسه، لذا امنحه بضع دقائق إذا كان اتصالك بطيئاً؛ حيث تنتظر واجهة سطر الأوامر مدة تصل إلى خمس دقائق قبل الإبلاغ عن تجاوز المهلة بدلاً من التوقف التام.

رسالة "this project is not a git repository" عند محاولة الدفع (push)

تتم عمليات النشر (deploys) انطلاقاً من مستودع، لذا يحتاج الأمر zinnector push إلى مستودع يحتوي على خادم بعيد (remote) يمكن للمنصة الوصول إليه. قم بتنفيذ الأوامر git init && git add -A && git commit -m initial، وأضف خادم GitHub أو GitLab البعيد الخاص بك، ثم استخدم zinnector link لربطه بالموقع.

الموقع يظهر بشاشة بيضاء بعد النشر

شغّل zinnector check. في تسع حالات من كل عشر، تكون المشكلة عبارة عن فجوة في إصدار PHP — حيث قمت بالبناء باستخدام إصدار PHP أحدث من الذي تشغله الفتحة (slot) — ويوضح التقرير الإصدار الذي يجب تحويل الفتحة إليه باستخدام zinnector php <version>، أو الإصدار الذي يجب التطوير اعتماده باستخدام zinnector dev --php <version>. يعرض الأمر zinnector logs --error الخطأ الفادح نفسه.