Så här åtgärdar du npm ERR! code ERESOLVE Peer Dependency-konflikt

Du kör npm install, förväntar dig att npm ska lägga till ett paket, och får istället en vägg av utdata som slutar med npm ERR! code ERESOLVE och “unable to resolve dependency tree.” Den viktiga frågan är inte “Hur får jag npm att sluta klaga?” Det är “Vilka två versionskrav kan inte båda vara sanna?”

Den distinktionen avgör om du får en stabil lösning eller bara tvingar npm att installera ett beroendeträd som ett av dina paket uttryckligen säger att det inte stöder.

Versionsnotering: enligt kontroll den 11 september 2026, märker npm-dokumentationen npm CLI 12.0.2 som den senaste dokumentationsversionen. npm har automatiskt installerat peerDependencies som standard sedan npm 7, och motstridiga peer-krav kan få installationen att misslyckas när npm inte kan konstruera ett giltigt träd. Se npm package.json-dokumentation.

Vad betyder ERESOLVE egentligen?

Direkt svar: npm hittade beroendekrav som inte kan uppfyllas tillsammans under det nuvarande beroendeträdet.

En peer dependency är ett kompatibilitetsavtal. Ett plugin eller ett följpaket kan deklarera att det förväntar sig att ditt projekt tillhandahåller en kompatibel version av ett annat paket. Till exempel kan ett plugin deklarera:

{
  "peerDependencies": {
    "react": "^17.0.0"
  }
}

Om ditt projekt kräver React 18 och det pluginet endast deklarerar kompatibilitet med React 17, har npm bevis för att den begärda kombinationen kan vara osupporterad. Paketet kan råka fungera med React 18, men npm kan inte anta att paketförfattaren avsåg den kompatibiliteten.

npms egen dokumentation råder paketförfattare att hålla peer dependency-intervall så breda som deras testade kompatibilitet tillåter, eftersom alltför smala peer-intervall kan skapa konflikter. Det betyder inte att konsumenter helt enkelt ska ignorera varje intervall de inte gillar.

Vilket paket orsakar egentligen konflikten?

Läs ERESOLVE-rapporten innan du ändrar något. Leta efter två delar:

• Found: den version som redan valts eller begärts av ditt rotprojekt.
• Could not resolve dependency / peer: paketet som kräver ett annat intervall.

I ett förenklat exempel kan npm säga att ditt rotprojekt använder react@18.3.0, medan some-package@2.1.0 kräver react@^16.8.0 || ^17.0.0. Konflikten är inte “npm mot React.” Det är inkompatibiliteten mellan din valda React-version och det peer-intervall som deklareras av some-package.

Anteckna tre värden innan du redigerar package.json: värdpaketet, det konfliktande paketet och det peer-intervall det förväntar sig.

Måste jag inspektera beroendeträdet först?

Ja, särskilt när det konfliktande paketet inte är ett direkt beroende. npm tillhandahåller två användbara kommandon för olika vyer av trädet.

npm ls react --all
npm explain some-package

npm ls skriver ut det logiska beroendeträdet och kan identifiera ogiltiga eller saknade paket. npm explain, även tillgängligt som npm why, visar kedjan av beroenden som fick ett paket att installeras. Se npm ls-dokumentation och npm explain-dokumentation.

Du kan också inspektera registermetadata för en kandidatpaketversion:

npm view some-package@2.1.0 peerDependencies
npm view some-package@latest peerDependencies

Kommandot npm view läser paketmetadata från registret, vilket låter dig jämföra om en nyare eller äldre utgåva stöder den värdversion du redan använder. Se npm view-dokumentation.

Kan jag åtgärda det genom att installera en kompatibel paketversion?

Vanligtvis är detta den bästa lösningen. Hitta en skärningspunkt mellan den värdversion din applikation behöver och det peer-intervall som stöds av pluginet.

Antag att ditt projekt innehåller:

{
  "dependencies": {
    "react": "^18.3.0",
    "some-package": "^2.1.0"
  }
}

Om en nyare some-package-utgåva deklarerar kompatibilitet med React 18, uppdatera det paketet:

npm install some-package@latest

Om din applikation inte behöver React 18 och pluginet är viktigt, kan det motsatta valet vara säkrare: installera en React-version som faktiskt uppfyller pluginets dokumenterade peer-intervall.

Rätt riktning beror på din applikation. Nedgradera inte automatiskt ett ramverk bara för att bevara ett övergivet plugin, och uppgradera inte automatiskt ett plugin över en huvudversion utan att läsa dess migrationsanteckningar.

Ska jag redigera package.json först eller radera node_modules först?

Åtgärda versionsbeslutet först. Att radera node_modules ändrar inte ett inkompatibelt peer-intervall.

När package.json beskriver en kompatibel uppsättning direkta beroenden, kör en normal installation så att npm kan uppdatera låsfilen:

npm install

Om du medvetet bygger om en föråldrad lokal installation efter att ha åtgärdat deklarationerna, kan borttagning av node_modules hjälpa till att säkerställa att nästa installation är ren. Men att radera filer utan att ändra de inkompatibla kraven ber bara npm att återupptäcka samma konflikt.

På samma sätt är att rensa npms cache inte ett normalt botemedel mot en semantisk peer dependency-konflikt. En ERESOLVE-rapport som namnger inkompatibla versionsintervall berättar redan vilken kategori av problem du har.

När ska jag använda package.json overrides?

Använd overrides när du medvetet behöver ändra vad en befintlig beroendekant löser till, vanligtvis för ett transitivt beroende. npm dokumenterar overrides som en rotprojektmekanism för att ersätta beroendeversioner, begränsa ett transitivt paket eller ersätta med en fork.

{
  "overrides": {
    "some-transitive-package": "^4.2.1"
  }
}

Behandla inte overrides som ett generellt kommando för att deklarera att ett inkompatibelt peer-avtal är magiskt giltigt. Om det verkliga problemet är att ett tredjepartspaket har felaktig eller alltför smal beroendemetadata, verifiera att koden är kompatibel och föredra en uppströms åtgärdad utgåva när den finns tillgänglig.

npm 12-dokumentation beskriver också packageExtensions, vilket kan lägga till eller korrigera tredjeparts beroendemetadata – inklusive peer dependency-intervall – från rotprojektet medan du väntar på en uppströmskorrigering. Detta är ett avancerat verktyg eftersom du tar ansvar för den korrigerade metadata. Se npm package.json: overrides och packageExtensions.

Ska jag använda --legacy-peer-deps?

Använd det endast när du medvetet behöver en tillfällig kompatibilitetsutrymning.

npm install --legacy-peer-deps

npm dokumenterar legacy-peer-deps som att få npm att ignorera peer dependencies när paketträdet byggs, liknande npm 3 till npm 6-beteende. npm säger uttryckligen att användningen är inte rekommenderad eftersom den inte upprätthåller peer dependency-avtalet som paket kan förlita sig på. Se npm konfigurationsdokumentation.

Denna flagga kan vara rimlig när du oberoende testat kombinationen, är blockerad av ett alltför restriktivt uppströms peer-intervall och behöver en kortfristig väg medan du ersätter eller uppdaterar paketet. Det är ett dåligt standardval för varje misslyckad installation.

Är --force samma sak?

Nej. --force är bredare och mer aggressivt.

npm install --force

npm anger att force tar bort flera skydd och, bland andra effekter, tillåter motstridiga peer dependencies att installeras i rotprojektet. npms dokumentation varnar mot att använda det när du inte tydligt förstår konsekvensen. Se npm config: force.

Om ditt enda mål är att tillfälligt kringgå peer dependency-upprätthållande, är --legacy-peer-deps smalare i avsikt. Ingen av flaggorna bevisar att den resulterande applikationen är kompatibel.

Varför misslyckas npm ci efter att npm install fungerade?

Kontrollera hur låsfilen skapades. npm dokumenterar att npm ci utför en fryst ren installation: det kräver en befintlig package-lock.json, vägrar uppdatera den och avslutas om låsfilen inte matchar package.json.

Det finns en ytterligare peer-dependency-detalj: om låsfilen skapades med en trädformande flagga som --legacy-peer-deps, säger npm att du bör skicka samma inställning till npm ci eller så kan du stöta på fel. npm föreslår att lagra inställningen i projektets .npmrc när det beteendet är avsiktligt en del av repot:

npm config set legacy-peer-deps=true --location=project

Commita sedan projektets .npmrc endast om den kringgången är ett medvetet teambeslut – inte för att en utvecklare behövde ett engångs räddningskommando. Se npm ci-dokumentation.

Vad gör jag om jag underhåller paketet som deklarerar peer dependency?

Testa värdversionerna du faktiskt stöder, deklarera sedan det bredaste korrekta intervallet. npm varnar specifikt paketförfattare mot onödigt smala peer dependency-specifikationer eftersom de ökar chansen att annars kompatibla plugins inte kan installeras tillsammans.

Om ett plugin fungerar över React 18.x, gör till exempel ett intervall som onödigt låser en patchversion livet svårare för konsumenter. Å andra sidan, att vidga ett intervall utan testning överför helt enkelt risken från installationstid till körningstid.

En praktisk repareringssekvens

1. Läs ERESOLVE-utdatan och skriv ner den hittade versionen, det konfliktande paketet och peer-intervallet.
2. Kör npm ls <host-package> --all och npm explain <conflicting-package>.
3. Använd npm view för att jämföra peer-krav för tillgängliga paketversioner.
4. Välj en versionskombination vars deklarerade intervall faktiskt överlappar.
5. Uppdatera package.json via npm install package@version eller en motsvarande medveten redigering följt av npm install.
6. Använd overrides eller packageExtensions endast när det transitiva beroendet eller metadata verkligen kräver projektlevel intervention.
7. Använd --legacy-peer-deps endast som ett dokumenterat tillfälligt undantag; reservera --force för fall där du fullt ut förstår vilket skydd du inaktiverar.

Hur verifierar jag att konflikten verkligen är åtgärdad?

Stanna inte när npm install returnerar exit code 0. Verifiera beroendeträdet och applikationen.

npm ls
npm test
npm run build

Använd projektets faktiska test- och byggs scripts; inte varje repo definierar exakt ovanstående kommandon. Om repot har en låsfil, testa också en fryst ren installation:

npm ci

Ett starkt resultat har fyra egenskaper:

• npm install lyckas utan en ERESOLVE-konflikt.
• npm ls rapporterar inte de relevanta paketen som ogiltiga eller saknade.
• Dina tester och produktionsbygget godkänns med de lösta versionerna.
• npm ci lyckas i en ren miljö med den commitade låsfilen och projektkonfigurationen.

Om du bara kan uppfylla det första villkoret genom att använda --force, har beroendekonflikten inte verkligen lösts – du har instruerat npm att acceptera den. Det kan vara ett medvetet kortfristigt beslut, men det bör registreras som teknisk skuld med det inkompatibla paketet och den avsedda ersättnings- eller uppgraderingsvägen tydligt identifierad.