الحل النهائي لخطأ “npm install failed; cleaning up and retrying”؟

26views

أنت تحاول تثبيت OpenClow (أو حزمة مشابهة كبيرة الحجم)، والطرفية (Terminal) لديك عالقة في حلقة مفرغة. تقوم بالتحميل، ثم تفشل، ثم تقول cleaning up and retrying (جاري التنظيف وإعادة المحاولة)، وفي النهاية تتعطل تماماً مع سجل أخطاء ضخم.

نادراً ما يكون هذا الخطأ متعلقاً بالكود البرمجي للحزمة نفسها. إنه غالباً يتعلق بمدير الحزم “NPM” الذي يواجه صعوبة بسبب اتصال شبكة ضعيف أو ملف تخزين مؤقت (Cache) تالف.

إليك الطريقة “الصحيحة” خطوة بخطوة لحل هذه المشكلة بشكل دائم.

---

المرحلة الأولى: التنظيف الجذري (ابدأ من هنا)

قبل أن نحاول التثبيت مرة أخرى، يجب علينا إزالة “بقايا” محاولة التثبيت الفاشلة. إذا لم تفعل ذلك، فإن التثبيت الجديد سيتعثر ببساطة في الملفات القديمة التالفة.

1. افتح الطرفية (Terminal) لديك. 2. انتقل إلى مجلد المشروع الخاص بك:

Bash

cd /path/to/openclow

3. قم بتشغيل تسلسل الأوامر هذا لمسح كل شيء: (ملاحظة: إذا كنت تستخدم Windows ولا تعمل أوامر rm، استخدم PowerShell أو قم بحذف المجلدات يدوياً من مستكشف الملفات).

Bash

rm -rf node_modules
rm package-lock.json
npm cache clean --force

• rm -rf node_modules: يحذف المجلد الذي يتم تخزين الحزم فيه.
• rm package-lock.json: يحذف “الإيصال” الذي يحدد النسخ التي تم تثبيتها بالضبط. نريد إنشاء واحد جديد.
• npm cache clean --force: هذا أمر بالغ الأهمية. إنه يمسح ذاكرة التخزين المؤقت المحلية لـ NPM على جهازك، والتي غالباً ما تحتوي على الملف التالف الذي يسبب حلقة “إعادة المحاولة”.

---

المرحلة الثانية: إصلاح الإعدادات (الخلطة السرية)

غالباً ما يتم تشغيل خطأ cleaning up and retrying لأن NPM يستسلم ويتوقف عن التحميل بسرعة كبيرة. نحتاج إلى إخبار NPM بأن يخفف من حدود وقت الانتظار (Timeout limits).

1. زيادة وقت انتظار الشبكة: قم بتشغيل هذه الأوامر لإخبار NPM بالانتظار لفترة أطول قبل الفشل:

Bash

npm config set fetch-retry-maxtimeout 120000
npm config set fetch-retry-mintimeout 20000

2. إيقاف تشغيل SSL الصارم (اختياري ولكنه مفيد): إذا كنت على شبكة شركة أو مزود خدمة إنترنت مقيد، فقد تتسبب شهادات SSL أحياناً في توقف التحميل.

Bash

npm config set strict-ssl false

---

المرحلة الثالثة: التثبيت القوي (Robust Install)

الآن بعد أن أصبحت البيئة نظيفة وتم تحسين الإعدادات، سنقوم بتشغيل أمر التثبيت. لكننا لن نستخدم npm install العادي فقط. سنستخدم “إشارات” (Flags) لمنع التعارضات.

قم بتشغيل هذا الأمر بالضبط:

Bash

npm install --no-audit --legacy-peer-deps

• --no-audit: يتخطى خطوة تدقيق الأمان أثناء التثبيت، مما يوفر الوقت وعرض النطاق الترددي للشبكة.
• --legacy-peer-deps: هذه هي الإشارة السحرية. إذا كان لدى OpenClow اعتماديات أقدم قليلاً مما يتوقعه إصدار Node الخاص بك، فإن هذه الإشارة تخبر NPM بأن “يتجاهل التعارض ويقوم بتثبيتها على أي حال”.

إذا استمر الفشل: حاول استخدام مرآة تسجيل مختلفة (أحياناً يكون سجل NPM الرئيسي معطلاً أو بطيئاً في منطقتك):

Bash

npm config set registry https://registry.npmjs.org/
npm install

---

ملخص الأوامر (لنسخ ولصق سريع)

إذا كنت تريد القيام بكل شيء دفعة واحدة، انسخ والصق هذه الكتلة الكاملة في الطرفية الخاصة بك (على أنظمة Linux/macOS):

Bash

# 1. تنظيف البيئة
rm -rf node_modules
rm package-lock.json
npm cache clean --force

# 2. تكوين إعدادات الشبكة لمنع انقطاع الاتصال
npm config set fetch-retry-maxtimeout 600000
npm config set fetch-timeout 600000

# 3. التثبيت مع حل التعارضات
npm install --legacy-peer-deps

---

المراجع وقراءات إضافية

إذا كنت ترغب في فهم التفاصيل الفنية وراء سبب عمل هذه الأوامر، فإليك روابط الوثائق الرسمية:

• وثائق تنظيف ذاكرة التخزين المؤقت لـ NPM: تشرح سبب ضرورة فرض تنظيف ذاكرة التخزين المؤقت للملفات المضغوطة التالفة.
  • https://docs.npmjs.com/cli/v8/commands/npm-cache
• شرح Legacy Peer Deps: مناقشة مفصلة على StackOverflow حول سبب إصلاح هذه الإشارة لـ 90% من أخطاء التثبيت الحديثة.
  • https://stackoverflow.com/questions/66239691/what-does-npm-install-legacy-peer-deps-do-exactly
• إعدادات تكوين NPM: القائمة الرسمية لجميع إعدادات التكوين بما في ذلك أوقات الانتظار (timeouts).
  • https://docs.npmjs.com/cli/v8/using-npm/config