تحاول تثبّت حزمة جديدة، أو تنشر على Vercel أو Netlify، والعملية تقف بسطر يبدأ بـ npm ERR! code ERESOLVE (أو npm error code ERESOLVE في الإصدارات الأحدث)، وتحته ERESOLVE unable to resolve dependency tree. المعنى: فيه حزمتين في منتجك يطلبون نسختين مختلفتين من نفس الشيء، و npm رفض يختار عنك.
إيش يعني بالضبط
منتجك مبني من حزم (packages) كتبها ناس ثانيين: React، ومكتبة الجداول، ومكتبة التقويم، وغيرها. بعض الحزم تشترط نسخة معيّنة من حزمة ثانية عشان تشتغل معها، وهذا اسمه peer dependency. مثلًا مكتبة تقويم تقول: «أشتغل مع React 18 فقط»، ومنتجك على React 19. هنا npm يوقف ويقول لك: ما أقدر أرضي الاثنين.
الرسالة نفسها تقول لك وين التعارض، لو قرأتها من فوق:
- سطر
Found:يقول النسخة الموجودة عندك، مثلreact@19.0.0. - سطر
Could not resolve dependency:وتحته شيء مثلpeer react@"^18.0.0" from some-calendar@2.1.0: يعني الحزمةsome-calendarتبي React 18.
ليش يصير كثير مع أدوات الذكاء الاصطناعي
- الأداة تضيف حزمة تتذكرها من بيانات تدريبها، بنسخة قديمة ما تدعم نسخة React أو Next.js اللي في منتجك.
- القوالب الجاهزة في Bolt و Lovable و v0 تبدأ بنسخ حديثة من React (و Next.js في v0)، وبعض المكتبات المشهورة تتأخر شهور حتى تدعمها.
- لما يطلع الخطأ، الأداة تحاول تتجاوزه بدل ما تحله، فتتراكم حزم بنسخ متعارضة.
- أحيانًا يمشي التثبيت عندك لأن عندك ملف
package-lock.jsonقديم، ويفشل على منصة النشر لأنها تثبّت من جديد.
كيف تتأكد بنفسك
- افتح سجل البناء في منصة النشر، أو نافذة الأوامر، وانزل لأول
ERESOLVE. - اكتب اسم الحزمة اللي في سطر
peer ... from، واسم الحزمة اللي تطلبها، وغالبًا تكونreactأوnext. - افتح صفحة الحزمة على npmjs.com أو GitHub، وشوف آخر نسخة منها: هل تدعم نسختك؟
- اسأل: هل منتجك يستخدم هالحزمة فعلًا؟ كثير من الحزم يضيفها الذكاء الاصطناعي لميزة جرّبتها ثم تركتها.
الحل الصح
واحد من ثلاثة، بالترتيب:
- حدّث الحزمة لنسخة تدعم نسختك من React أو Next.js، إذا موجودة.
- استبدلها بحزمة ثانية تسوي نفس الشغل ومحدّثة، أو احذفها إذا ما تستخدمها.
- ثبّت نسخة متوافقة من React أو Next.js نفسها، إذا منتجك صغير وما يحتاج آخر نسخة.
بعدها احفظ ملف package-lock.json في المستودع مع الكود، عشان منصة النشر تثبّت نفس النسخ اللي عندك بالضبط.
ليش يمشي عندك ويفشل في النشر
هذي أكثر حالة تحيّر: عندك كل شيء مثبّت ويشتغل، والنشر يفشل بنفس الخطأ. الأسباب الأشهر:
- ملف
package-lock.jsonمو موجود في المستودع، فمنصة النشر تحسب النسخ من جديد وتطلع بنتيجة غير اللي عندك. - نسخة npm أو Node عندك غير نسختها على منصة النشر، وكل نسخة تتعامل مع الشروط بشكل مختلف شوي.
- ثبّتت عندك مرة بـ
--forceونسيت، فجهازك فيه حزم ما كان المفروض تتثبّت.
الحل هنا: ملف القفل في المستودع، ونفس نسخة Node في الجهتين، وتثبيت نظيف عندك (npm ci) يطلع لك نفس الخطأ اللي يشوفه النشر قبل ما ترفع.
الحل اللي لا تسويه
أداة الذكاء الاصطناعي غالبًا تقترح npm install --force أو --legacy-peer-deps، أو تضيفها لإعدادات البناء عشان «يمشي». الخيارين يخلّون npm يتجاوز الشرط: --legacy-peer-deps يتجاهل كل شروط peer dependencies في المنتج كله، مو فقط هذا التعارض، و --force يثبّت النسخة المتعارضة على كل حال، ويشيل معها حمايات ثانية في npm. البناء ينجح، لكن الحزمة ممكن تتعطّل وقت التشغيل، في صفحة معيّنة، عند مستخدم معيّن، بخطأ ما له علاقة واضحة بالتثبيت. وفوق كذا، أي تعارض جديد بعدين ما راح تشوفه، لأنك سكّتت التحذير.
فيه حالات قليلة يكون فيها --legacy-peer-deps قرار مقبول: حزمة شرطها قديم، ومجرّبة مع نسختك وتشتغل. لكن هذا قرار يتخذه مهندس بعد ما يجرّب، ويكتبه، مو حل افتراضي لكل خطأ.
ونفس الشي حذف package-lock.json و node_modules كل مرة يطلع الخطأ: أحيانًا يمشي، لكنه يغيّر نسخ عشرات الحزم مرة وحدة بدون ما تدري.
إذا تكرر الخطأ
إذا الخطأ يرجع مع كل حزمة جديدة، أو منتجك مليان حزم ما تدري إيش تسوي، هذا علامة إن الأساس محتاج ترتيب. احجز مكالمة استشارية لتعارض واحد، أو خلّنا نرتّبها كلها في الإصلاح المباشر. وإذا البناء يفشل لسبب ثاني، اقرأ Command "npm run build" exited with 1. ولو منتجك على Bolt، شوف مشاكل Bolt الأشهر.