Sådan løser du npm ERR! code ERESOLVE Peer Dependency-konflikt

Du kører npm install, forventer at npm tilføjer én pakke, og i stedet får du en væg af output, der slutter med npm ERR! code ERESOLVE og “unable to resolve dependency tree.” Det vigtige spørgsmål er ikke “Hvordan får jeg npm til at holde op med at klage?” Det er “Hvilke to versionskrav kan ikke begge være sande?”

Denne distinktion afgør, om du ender med en stabil løsning eller blot tvinger npm til at installere et afhængighedstræ, som en af dine pakker eksplicit siger, at den ikke understøtter.

Versionsnote: Som tjekket den 11. september 2026, betegner npm-dokumentationen npm CLI 12.0.2 som den seneste dokumentationsversion. npm har automatisk installeret peerDependencies som standard siden npm 7, og konfliktende peer-krav kan få installationen til at fejle, når npm ikke kan konstruere et gyldigt træ. Se npm package.json-dokumentation.

Hvad betyder ERESOLVE egentlig?

Direkte svar: npm fandt afhængigheds krav, der ikke kan opfyldes sammen under det nuværende afhængighedstræ.

En peer dependency er en kompatibilitetskontrakt. Et plugin eller en ledsagende pakke kan erklære, at den forventer, at dit projekt leverer en kompatibel version af en anden pakke. For eksempel kan et plugin erklære:

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

Hvis dit projekt kræver React 18, og det plugin kun erklærer kompatibilitet med React 17, har npm bevis for, at den anmodede kombination måske ikke er understøttet. Pakken kan tilfældigvis køre med React 18, men npm kan ikke antage, at pakkeforfatteren havde til hensigt denne kompatibilitet.

npms egen dokumentation råder pakkeforfattere til at holde peer dependency-områder så brede som deres testede kompatibilitet tillader, fordi for snævre peer-områder kan skabe konflikter. Det betyder ikke, at forbrugere blot skal ignorere ethvert område, de ikke kan lide.

Hvilken pakke forårsager faktisk konflikten?

Læs ERESOLVE-rapporten, før du ændrer noget. Kig efter to dele:

• Found: Den version, der allerede er valgt eller anmodet af dit rodprojekt.
• Could not resolve dependency / peer: Pakken, der kræver et andet område.

I et forenklet eksempel kan npm sige, at dit rodprojekt bruger react@18.3.0, mens some-package@2.1.0 kræver react@^16.8.0 || ^17.0.0. Konflikten er ikke “npm versus React.” Det er inkompatibiliteten mellem din valgte React-version og det peer-område, der er erklæret af some-package.

Noter tre værdier, før du redigerer package.json: værts-pakken, den konfliktende pakke og det peer-område, den forventer.

Skal jeg inspicere afhængighedstræet først?

Ja, især når den konfliktende pakke ikke er en direkte afhængighed. npm tilbyder to nyttige kommandoer til forskellige visninger af træet.

npm ls react --all
npm explain some-package

npm ls udskriver det logiske afhængighedstræ og kan identificere ugyldige eller manglende pakker. npm explain, også tilgængelig som npm why, viser kæden af afhængigheder, der fik en pakke til at blive installeret. Se npm ls-dokumentation og npm explain-dokumentation.

Du kan også inspicere registreringsmetadata for en kandidatpakkeversion:

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

Kommandoen npm view læser pakke-metadata fra registreringen, hvilket lader dig sammenligne, om en nyere eller ældre udgivelse understøtter den værtsversion, du allerede bruger. Se npm view-dokumentation.

Kan jeg løse det ved at installere en kompatibel pakkeversion?

Normalt er dette den bedste løsning. Find et skæringspunkt mellem den værtsversion, din applikation har brug for, og det peer-område, der understøttes af pluginet.

Antag at dit projekt indeholder:

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

Hvis en nyere some-package-udgivelse erklærer kompatibilitet med React 18, så opdater den pakke:

npm install some-package@latest

Hvis din applikation ikke har brug for React 18, og pluginet er vigtigt, kan det modsatte valg være sikrere: installer en React-version, der faktisk opfylder pluginets dokumenterede peer-område.

Den rigtige retning afhænger af din applikation. Nedgrader ikke automatisk et framework blot for at bevare et forladt plugin, og opgrader ikke automatisk et plugin på tværs af en hovedversion uden at læse dets migrationsnoter.

Skal jeg redigere package.json først eller slette node_modules først?

Ret versionsbeslutningen først. At slette node_modules ændrer ikke et inkompatibelt peer-område.

Når package.json beskriver et kompatibelt sæt af direkte afhængigheder, skal du køre en normal installation, så npm kan opdatere låsefilen:

npm install

Hvis du bevidst genopbygger en forældet lokal installation efter at have rettet deklarationerne, kan det hjælpe at fjerne node_modules for at sikre, at den næste installation er ren. Men at slette filer uden at ændre de inkompatible krav beder blot npm om at genopdage den samme konflikt.

Ligeledes er at rydde npms cache ikke en normal kur for en semantisk peer dependency-konflikt. En ERESOLVE-rapport, der nævner inkompatible versionsområder, fortæller dig allerede, hvilken kategori af problem du har.

Hvornår skal jeg bruge package.json overrides?

Brug overrides, når du bevidst har brug for at ændre, hvad en eksisterende afhængighedskant løser til, normalt for en transitiv afhængighed. npm dokumenterer overrides som en rodprojekt-mekanisme til at erstatte afhængighedsversioner, begrænse en transitiv pakke eller erstatte en fork.

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

Behandl ikke overrides som en generisk kommando til at erklære, at en inkompatibel peer-kontrakt er magisk gyldig. Hvis det faktiske problem er, at en tredjepartspakke har forkerte eller for snævre afhængigheds-metadata, skal du verificere, at koden er kompatibel, og foretrække en opstrøms rettet udgivelse, når den er tilgængelig.

npm 12-dokumentationen beskriver også packageExtensions, som kan tilføje eller korrigere tredjeparts afhængigheds-metadata – inklusive peer dependency-områder – fra rodprojektet, mens du venter på en opstrøms rettelse. Dette er et avanceret værktøj, fordi du påtager dig ansvaret for de korrigerede metadata. Se npm package.json: overrides og packageExtensions.

Skal jeg bruge --legacy-peer-deps?

Brug det kun, når du bevidst har brug for en midlertidig kompatibilitetsudvej.

npm install --legacy-peer-deps

npm dokumenterer legacy-peer-deps som at få npm til at ignorere peer dependencies under opbygningen af pakke-træet, lignende npm 3 til npm 6-adfærd. npm siger eksplicit, at brugen er ikke anbefalet, fordi den ikke håndhæver peer dependency-kontrakten, som pakker måske er afhængige af. Se npm konfigurationsdokumentation.

Denne flag kan være rimelig, når du uafhængigt har testet kombinationen, er blokeret af et for restriktivt opstrøms peer-område, og har brug for en kortsigtet vej, mens du erstatter eller opdaterer pakken. Det er en dårlig standard for hver mislykket installation.

Er --force det samme?

Nej. --force er bredere og mere aggressiv.

npm install --force

npm angiver, at force fjerner flere beskyttelser og blandt andet tillader konfliktende peer dependencies at blive installeret i rodprojektet. npms dokumentation advarer mod at bruge det, når du ikke tydeligt forstår konsekvensen. Se npm config: force.

Hvis dit eneste mål er midlertidigt at omgå peer dependency-håndhævelse, er --legacy-peer-deps smallere i hensigt. Ingen af flagene beviser, at den resulterende applikation er kompatibel.

Hvorfor fejler npm ci, efter npm install virkede?

Tjek hvordan låsefilen blev oprettet. npm dokumenterer, at npm ci udfører en frossen ren installation: det kræver en eksisterende package-lock.json, nægter at opdatere den og afslutter, hvis låsefilen ikke matcher package.json.

Der er en yderligere peer-dependency-detajle: hvis låsefilen blev oprettet med en træ-formende flag som --legacy-peer-deps, siger npm, at du skal videregive den samme indstilling til npm ci, ellers kan du støde på fejl. npm foreslår at gemme indstillingen i projektets .npmrc, når den adfærd er en bevidst del af repositoryet:

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

Commit derefter projektets .npmrc kun, hvis den bypass er en bevidst teambeslutning – ikke fordi en udvikler havde brug for en engangs-redningskommando. Se npm ci-dokumentation.

Hvad hvis jeg vedligeholder pakken, der erklærer peer dependency?

Test de værtsversioner, du faktisk understøtter, og erklær derefter det bredeste nøjagtige område. npm advarer specifikt pakkeforfattere mod unødigt snævre peer dependency-specifikationer, fordi de øger chancen for, at ellers kompatible plugins ikke kan installeres sammen.

Hvis et plugin virker på tværs af React 18.x, for eksempel, gør et område, der unødigt låser en patch-version, livet sværere for forbrugerne. På den anden side overfører udvidelse af et område uden test blot risikoen fra installationstidspunktet til kørselstidspunktet.

En praktisk reparationsssekvens

1. Læs ERESOLVE-outputtet og skriv den fundne version, den konfliktende pakke og peer-området ned.
2. Kør npm ls <host-package> --all og npm explain <conflicting-package>.
3. Brug npm view til at sammenligne peer-kravene for tilgængelige pakkeversioner.
4. Vælg en versionskombination, hvis erklærede områder faktisk overlapper.
5. Opdater package.json via npm install package@version eller en tilsvarende bevidst redigering efterfulgt af npm install.
6. Brug overrides eller packageExtensions kun, når den transitive afhængighed eller metadata virkelig kræver projekt-niveau indgriben.
7. Brug --legacy-peer-deps kun som en dokumenteret midlertidig undtagelse; reserver --force til tilfælde, hvor du fuldt ud forstår, hvilken beskyttelse du deaktiverer.

Hvordan verificerer jeg, at konflikten virkelig er løst?

Stop ikke, når npm install returnerer exit-kode 0. Verificer afhængighedstræet og applikationen.

npm ls
npm test
npm run build

Brug projektets faktiske test- og byggescripts; ikke alle repositoryer definerer de præcise kommandoer ovenfor. Hvis repositoryet har en låsefil, skal du også teste en frossen ren installation:

npm ci

Et stærkt resultat har fire egenskaber:

• npm install lykkes uden en ERESOLVE-konflikt.
• npm ls rapporterer ikke de relevante pakker som ugyldige eller manglende.
• Dine tests og produktionsbyg passerer med de løste versioner.
• npm ci lykkes i et rent miljø ved hjælp af den committede låsefil og projekt-konfiguration.

Hvis du kun kan opfylde den første betingelse ved at bruge --force, er afhængighedskonflikten ikke virkelig løst – du har instrueret npm i at acceptere den. Det kan være en bevidst kortsigtet beslutning, men det bør registreres som teknisk gæld med den inkompatible pakke og den tilsigtede erstatnings- eller opgraderingssti tydeligt identificeret.