كيفية إصلاح خطأ npm! ERESOLVE غير قادر على حل شجرة التبعية

خطأ npm! ERESOLVE غير قادر على حل شجرة التبعية الخطأ يعني أن npm عثر على متطلبات تبعية نظير متعارضة بين الحزم في مشروعك. npm 7+ جعل حل تبعية الأقران أكثر صرامة – الحزم التي تم تثبيتها بهدوء جنبًا إلى جنب في npm 6 تفشل الآن. إليك شرح كل إصلاح.فهم الخطأ

قراءة هذا الخطأ:

npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR!
npm ERR! While resolving: my-app@1.0.0
npm ERR! Found: react@18.3.1
npm ERR! node_modules/react
npm ERR! react@"^18.0.0" from the root project
npm ERR!
npm ERR! Could not resolve dependency:
npm ERR! peer react@"^16.8.0 || ^17.0.0" from some-old-package@2.1.0
npm ERR! node_modules/some-old-package

يستخدم مشروعك React 18. يتطلب React 16 أو 17 كتبعية نظير. يرفض npm التثبيت لأنه يرى أن هذا تعارض.some-old-packageالإصلاح 1: –legacy-peer-deps (الإصلاح السريع الأكثر أمانًا)

يؤدي هذا إلى إرجاع سلوك npm إلى الإصدار 6 – تثبيت الحزم دون فرض تعارضات التبعية بين الأقران. قد تعمل الحزمة بشكل جيد مع الإصدار النظير الأحدث على الرغم من أنها تعلن عن نطاق أقدم.

npm install --legacy-peer-deps

متى تستخدم:

عندما تختبر عمل المجموعة، لم يتم تحديث الحزمة للإعلان عن إصدارات نظيرة React/Vue/Angular جديدة، وأنت تثق في أن التبعية لن تنقطع فعليًا.استمر لجميع عمليات التثبيت المستقبلية:

الإصلاح 2: –force (الملاذ الأخير)

# .npmrc file (commit this to repo)
legacy-peer-deps=true

ماذا يفعل:

npm install --force

يفرض التثبيت حتى مع الإصدارات المتعارضة، مما قد يؤدي إلى تثبيت إصدارات متعددة من نفس الحزمة. أكثر عدوانية منمتى تستخدم:--legacy-peer-deps.

فقط عندما لا يعمل وتأكدت من أن المجموعة آمنة. --legacy-peer-deps يمكن إنشاء أخطاء دقيقة في وقت التشغيل من الإصدارات غير المتطابقة.--forceالإصلاح 3: ترقية الحزمة المتعارضة

هذا هو الحل الصحيح

# Check if a newer version supports your React/Node version
npm info some-old-package peerDependencies

# Try installing a specific version
npm install some-old-package@latest

# Or check if there's an RC/beta with support
npm install some-old-package@next

عندما يتم تحديث الحزمة. تحقق دائمًا من وجود إصدار أحدث قبل الوصول إلى تطبيقات النظير القديمة.الإصلاح 4: تجاوز الحقل (npm 8.3+، النهج الأكثر صحة)

يخبر الحقل npm بفرض إصدار معين من التبعية المتداخلة. هذا هو الحل الصحيح — فأنت تقول صراحةً “استخدم React 18 لهذه الحزمة أيضًا” بدلاً من تجاهل التعارض بصمت.

// package.json
{
 "dependencies": {
 "some-old-package": "2.1.0",
 "react": "^18.0.0"
 },
 "overrides": {
 "some-old-package": {
 "react": "^18.0.0"
 }
 }
}

بالنسبة للغزل (حقل الدقة):overridesالإصلاح 5: البحث عن حزمة بديلة

إذا لم تتم صيانة الحزمة ولا تدعم الإصدارات النظيرة الحالية، فغالبًا ما تكون هذه إشارة للعثور على بديل يتم صيانته بشكل أفضل:

// package.json
{
 "resolutions": {
 "some-old-package/react": "^18.0.0"
 }
}

من المحتمل أن يتم التخلي عن الحزمة التي تم نشرها آخر مرة منذ أكثر من عامين والتي تحتوي على مشكلات مفتوحة حول توافق React 18. ابحث في npm عن البدائل الحديثة ذات الصيانة النشطة.

شجرة القرار

# Check last publish date
npm info some-old-package

# Check GitHub for issues/PRs about the newer React version
# Look for: forks, alternatives, or community maintained versions

السيناريوهات والإصلاحات الشائعة

الأسئلة المتداولة

ERESOLVE error
 ↓
Is there a newer version of the conflicting package?
 YES → npm install package@latest
 NO ↓
Does the package actually work with your version (test it)?
 YES → Use --legacy-peer-deps or overrides in package.json
 NO ↓
Is there an actively maintained alternative?
 YES → Switch packages
 NO → Use --legacy-peer-deps and monitor for issues

س: هل –legacy-peer-deps آمن؟

# Scenario: Create React App with React 18
npx create-react-app my-app # old CRA doesn't support React 18
# Fix: Use Vite instead
npm create vite@latest my-app -- --template react-ts

# Scenario: Storybook + React 18
npx sb init # older Storybook versions conflict
# Fix: Use current Storybook
npx storybook@latest init

# Scenario: Old Redux package conflicts
# Fix: upgrade to Redux Toolkit (official recommendation)
npm install @reduxjs/toolkit react-redux

# Scenario: Next.js conflicting peer deps
# Fix: usually just --legacy-peer-deps works; Next.js team is aware

ج: عادةً نعم، خاصة عندما يكون الصراع حول كون نطاقات إصدار النظير محافظة (على سبيل المثال، يقول النظير React 16-17 ولكنه يعمل بشكل جيد مع 18). اختبره دائمًا بعد استخدامه. يكمن الخطر في حالات عدم التوافق الدقيقة في وقت التشغيل والتي تظهر فقط في حالات الحافة.

س: لماذا قام npm بتغيير سلوك التبعية للأقران؟
ج: npm 7+ جعل دقة تبعية الأقران صارمة لمنع تعارضات الإصدار الصامت التي تسببت في أخطاء وقت التشغيل التي يصعب تصحيحها. إنه سلوك أكثر صحة – والمقايضة تتطلب حلًا أكثر وضوحًا.

س: هل يجب أن أستخدم تجاوزات npm أو –legacy-peer-deps؟
في package.json أكثر وضوحًا ويوثق القرار.

أسرع ولكنه ضمني. لمشاريع الإنتاج تفضل
A: overrides لذلك يكون التجاوز مرئيًا في مراجعة الكود.--legacy-peer-depsس: ظهر هذا الخطأ بعد ترقية Node.js — هل له علاقة بذلك؟overridesج: غالبًا ما تجلب ترقيات Node.js إصدارات npm أحدث بدقة أكثر صرامة. إن خفض مستوى العقدة ليس هو الحل – استخدم

وقم بتحديث تبعياتك إلى الإصدارات المتوافقة مع الإصدار الأحدث من Node/npm.
س: كيف يمكنني منع ذلك في المشاريع الجديدة؟overrides or --legacy-peer-depsج: ابدأ بالأدوات الحديثة (Vite، Next.js 14+، أحدث بدائل CRA) التي تحتوي على إعلانات نظيرة محدثة. تجنب الحزم ذات تاريخ الصيانة السيئ. استخدم

ربع سنوي للبقاء على اطلاع.
الخلاصةnpm outdatedعادةً ما يتم حل أخطاء npm ERESOLVE عن طريق:

(1) ترقية الحزمة المتعارضة إلى إصدار يدعم إصدار إطار العمل الخاص بك، (2) باستخدام

في package.json لإصلاح موثق، أو (3) كحل مؤقت سريعoverrides. تجنب--legacy-peer-deps ما لم ينجح أي شيء آخر – فقد يؤدي ذلك إلى إنشاء تعارضات في إصدار وقت التشغيل. أفضل حل على المدى الطويل هو تحديث التبعيات حتى لا تتراكم تعارضات الإصدارات. ما لم ينجح أي شيء آخر – فقد يؤدي ذلك إلى إنشاء تعارضات في إصدار وقت التشغيل. أفضل حل على المدى الطويل هو تحديث التبعيات حتى لا تتراكم تعارضات الإصدارات.--force ما لم ينجح أي شيء آخر – فقد يؤدي ذلك إلى إنشاء تعارضات في إصدار وقت التشغيل. أفضل حل على المدى الطويل هو تحديث التبعيات حتى لا تتراكم تعارضات الإصدارات.