على نظام macOS، حدد أولاً ما إذا كان npm يُبلغ عن تعارض دمج في Git، أو عدم تطابق بين package.json وpackage-lock.json، أو خطأ في حل تبعيات الأقران (peer dependency). تحقق من ملفات المشروع، وحالة Git، وإصدارات npm في Terminal قبل تغيير أي شيء. إذا كان ملف القفل وحده يحتاج إلى تسوية، فإن خيار --package-lock-only في npm يمكنه تحديثه دون إعادة تثبيت الحزم في node_modules.

ابدأ من مجلد المشروع واحتفظ بالحالة الحالية

افتح Terminal، وانتقل إلى مجلد المشروع، وتأكد من أنك في المجلد الجذري الصحيح للمشروع. في Finder، يمكنك تحديد موقع المجلد، ثم استخدام أمر cd في Terminal؛ إذا كان المسار يحتوي على مسافات، فضع المسار بين علامتي اقتباس، على سبيل المثال cd "$HOME/Projects/My App". شغّل:

pwd
git status --short
node --version
npm --version

يوضح أمر git status --short ما إذا كان أي من ملفي البيان (manifest) يحتوي على تعديلات لم يتم الالتزام بها (uncommitted). إذا كانت هناك تغييرات تحتاج إلى الاحتفاظ بها، فاحفظها أو قم بعمل commit لها قبل المتابعة؛ لا تستبدل الملفات أثناء اتخاذك لقرار بشأن أيٍّ من تغييرات التبعيات يجب اعتماده. سجّل إصدارات Node.js وnpm حتى تتمكن من مقارنتها مع إعدادات المشروع الموثقة أو تكوين التكامل المستمر (CI). لقد تغيرت تنسيقات ملف npm lockfile عبر إصدارات npm الرئيسية، لذا فإن الاختلاف في التنسيق قد يفسر التغييرات غير المتوقعة دون أن يعني بالضرورة وجود خلل في التبعيات نفسها. توثيق package-lock الخاص بـ npm

حدد نوع التعارض الذي تواجهه

إذا كان package-lock.json يحتوي على علامات Git مثل <<<<<<< أو ======= أو >>>>>>>، فهذا تعارض دمج في نظام التحكم بالإصدارات. افحص الأقسام المتأثرة بالكامل وقارن التغييرات بين كلا الفرعين. قم بحل تعريفات التبعيات في package.json أولاً: تشير إرشادات npm السابقة حول تعارضات ملفات القفل صراحةً إلى ضرورة حل تعارضات ملفات البيان يدويًا قبل إعادة إنشاء ملف القفل. لا تحتفظ بجانب واحد فقط من ملف القفل بدافع التعود؛ فقد يكون كل فرع قد أضاف تبعيات أو عدّلها. إرشادات تعارض package-lock من npm

إذا لم تكن هناك علامات Git، فقارن أسماء التبعيات ونطاقاتها في package.json مع ملف القفل. يحدد package.json النطاقات المقبولة، بينما يسجل ملف القفل شجرة تبعيات تم حلها بدقة. يوضح توثيق npm الحالي أن أمر npm install العادي يستخدم الإصدارات المقفلة عندما تتوافق مع نطاقات ملف البيان، ويقوم بتحديث ملف القفل عندما لا تتوافق. كيف يستخدم npm install ملف القفل

إذا فشل الأمر مع ظهور رسالة peer dependency، فركز على الحزم المذكورة في هذا الخطأ ومتطلبات الأقران الخاصة بها. قد يكون هذا تعارضًا حقيقيًا غير متوافق بين نطاقات الحزم المعلنة، وليس تثبيتًا تالفًا. لا تستخدم خياري --force أو --legacy-peer-deps كحل تشخيصي سريع ومختصر: فتغيير سلوك حل التبعيات قد ينتج شجرة تختلف عن الإعداد المخصص للمشروع.

افحص التغيير قبل أن تطلب من npm إجراء التسوية

راجع سجل المشروع والفروقات الحالية:

git diff -- package.json package-lock.json
git log -5 --oneline -- package.json package-lock.json

ابحث عن الـ commit أو الفرع الذي قام بتغيير إعلان التبعية، أو إصدار ملف القفل، أو إعدادات npm. تحقق أيضًا مما إذا كان المشروع يحتوي على ملف .npmrc؛ حيث يوضح توثيق npm أن الخيارات التي تؤثر في بنية شجرة التبعيات مثل legacy-peer-deps أو install-links قد تؤثر على مدى توافق ملف القفل مع التثبيت النظيف لاحقًا. استخدم نفس الإعدادات المخصصة للمشروع والمعتمدة بالفعل في المستودع بدلاً من إضافة معاملات (flags) جديدة عشوائيًا. توثيق npm ci

تساعد قيمة lockfileVersion في تحديد تنسيق الملف، ولكن تجنب التعامل معها كتشخيص مستقل بحد ذاته. يوثق npm إصدارات التنسيق 1 و2 و3، ويشير إلى أن إصدارات npm الأحدث يمكنها تحديث ملفات القفل الأقدم. قد يعكس الإصدار المتغير سلوك توافق npm؛ افحص الفروقات الفعلية للتبعيات قبل قبول إعادة كتابة شاملة للملف. تنسيق ملف القفل والملفات الأقدم

قم بتسوية ملف القفل دون إعادة تثبيت التبعيات

بعد حل أي علامات تعارض والتأكد من صحة package.json، اطلب من npm تحديث ملف القفل فقط:

npm install --package-lock-only

يوثق npm هذا الخيار بأنه يقوم بتحديث package-lock.json دون فحص مجلد node_modules أو تنزيل التبعيات. إنها خطوة تسوية موجهة؛ ولا تضمن أن مجموعة التبعيات الناتجة هي التي قصدتها تمامًا، لذا افحص الفروقات (diff) بعد ذلك. خيارات npm install

git diff --check
git diff -- package.json package-lock.json
git status --short

يساعد أمر git diff --check في رصد أخطاء المسافات البيضاء، بينما يوضح الـ diff نفسه ما قام npm بتغييره. تأكد من أن ملف البيان لم يتلقَ أي تعديلات غير مقصودة، وافحص أي تغييرات غير متوقعة في الإصدارات أو إعادة كتابة واسعة لملف القفل، وتأكد من زوال علامات التعارض. إذا كانت التغييرات المقترحة غير منطقية، فاسترجع الملفات من حالتك المحفوظة أو من نظام التحكم بالإصدارات وأعد النظر في السبب، بدلاً من حذف node_modules أو إعادة إنشاء كل شيء من الصفر.

اعرف متى يكون التثبيت النظيف مناسبًا

استخدم npm ci فقط بعد محاذاة ملف البيان وملف القفل عن قصد وعندما ترغب في إعادة إنتاج شجرة التبعيات المقفلة بدقة. يتطلب هذا الأمر وجود ملف قفل، ويفشل بدلاً من تحديث أي عدم تطابق، كما أنه يحذف مجلد node_modules الحالي قبل التثبيت. وهذا يجعله مفيدًا لتأكيد حالة تم حلها مسبقًا، ولكنه ليس أمرًا لفحص المشكلات دون آثار جانبية. سلوك npm ci

إذا لم يتمكن npm install --package-lock-only من حل التعارض، فسجّل رسالة الخطأ بدقة، وراجع نطاقات الحزم المذكورة وإعدادات npm الخاصة بالمشروع، وقارنها بالفرع أو بيئة الـ CI التي أنتجت ملف القفل. السؤال الحاسم هو: ما هي إعلانات التبعيات التي يجب أن يحتفظ بها المشروع؟ لا يمكن لعملية تنظيف التثبيت الإجابة عن ذلك نيابةً عنك. وبمجرد أن ينعكس هذا القرار في package.json، أعد إنشاء ملف القفل فقط، وافحص التغيير المقترح، ثم حدد ما إذا كان التثبيت النظيف ضروريًا.

المصادر