Slik løser du npm ERR! code ERESOLVE Peer Dependency-konflikt

Du kjører npm install, forventer at npm skal legge til én pakke, og får i stedet en vegg av utdata som slutter med npm ERR! code ERESOLVE og “unable to resolve dependency tree.” Det viktige spørsmålet er ikke “Hvordan får jeg npm til å slutte å klage?” Det er “Hvilke to versjonskrav kan ikke begge være sanne?”

Denne distinksjonen avgjør om du ender opp med en stabil løsning, eller om du bare tvinger npm til å installere et avhengighets-tre som en av pakkene dine uttrykkelig sier at den ikke støtter.

Versjonsnotat: slik det ble kontrollert den 11. september 2026, merker npm-dokumentasjonen npm CLI 12.0.2 som den nyeste dokumentasjonsversjonen. npm har automatisk installert peerDependencies som standard siden npm 7, og motstridende peer-krav kan føre til at installasjonen feiler når npm ikke klarer å konstruere et gyldig tre. Se npm package.json-dokumentasjonen.

Hva betyr egentlig ERESOLVE?

Direkte svar: npm fant avhengighetskrav som ikke kan oppfylles samtidig under det gjeldende avhengighetstreet.

En peer dependency er en kompatibilitetskontrakt. En plugin eller ledsagerpakke kan erklære at den forventer at prosjektet ditt leverer en kompatibel versjon av en annen pakke. For eksempel kan en plugin erklære:

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

Hvis prosjektet ditt krever React 18 og den pluginen bare erklærer kompatibilitet med React 17, har npm bevis for at den forespurte kombinasjonen kanskje ikke støttes. Pakken kan tilfeldigvis kjøre med React 18, men npm kan ikke anta at pakkeforfatteren hadde til hensikt å støtte den kompatibiliteten.

npms egen dokumentasjon anbefaler at pakkeforfattere holder peer dependency-områdene så brede som deres testede kompatibilitet tillater, fordi for smale peer-områder kan skape konflikter. Det betyr ikke at forbrukere bare skal ignorere hvert eneste område de ikke liker.

Hvilken pakke forårsaker egentlig konflikten?

Les ERESOLVE-rapporten før du endrer noe. Se etter to deler:

• Found: versjonen som allerede er valgt eller forespurt av rotprosjektet ditt.
• Could not resolve dependency / peer: pakken som krever et annet område.

I et forenklet eksempel kan npm si at rotprosjektet ditt bruker react@18.3.0, mens some-package@2.1.0 krever react@^16.8.0 || ^17.0.0. Konflikten er ikke “npm mot React.” Det er inkompatibiliteten mellom den valgte React-versjonen og peer-området erklært av some-package.

Noter tre verdier før du redigerer package.json: vertspakken, den konfliktende pakken, og peer-området den forventer.

Må jeg inspisere avhengighetstreet først?

Ja, spesielt når den konfliktende pakken ikke er en direkte avhengighet. npm gir to nyttige kommandoer for ulike visninger av treet.

npm ls react --all
npm explain some-package

npm ls skriver ut det logiske avhengighetstreet og kan identifisere ugyldige eller manglende pakker. npm explain, også tilgjengelig som npm why, viser kjeden av avhengigheter som førte til at en pakke ble installert. Se npm ls-dokumentasjonen og npm explain-dokumentasjonen.

Du kan også inspisere registermetadataene for en kandidatpakkeversjon:

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

npm view-kommandoen leser pakkemetadata fra registeret, noe som lar deg sammenligne om en nyere eller eldre utgivelse støtter vertsversionen du allerede bruker. Se npm view-dokumentasjonen.

Kan jeg løse det ved å installere en kompatibel pakkeversjon?

Vanligvis er dette den beste løsningen. Finn et skjæringspunkt mellom vertsversionen applikasjonen din trenger og peer-området som støttes av pluginen.

Anta at prosjektet ditt inneholder:

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

Hvis en nyere some-package-utgivelse erklærer kompatibilitet med React 18, oppdater den pakken:

npm install some-package@latest

Hvis applikasjonen din ikke trenger React 18 og pluginen er viktig, kan det motsatte valget være tryggere: installer en React-versjon som faktisk tilfredsstiller pluginens dokumenterte peer-område.

Den rette retningen avhenger av applikasjonen din. Ikke nedgrader automatisk et rammeverk bare for å bevare en forlatt plugin, og ikke oppgrader automatisk en plugin over en hovedversjon uten å lese migrasjonsnotatene dens.

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

Fiks versjonsbeslutningen først. Å slette node_modules endrer ikke et inkompatibelt peer-område.

Når package.json beskriver et kompatibelt sett med direkte avhengigheter, kjør en normal installasjon slik at npm kan oppdatere låsefilen:

npm install

Hvis du bevisst gjenoppbygger en utdatert lokal installasjon etter å ha fikset erklæringene, kan fjerning av node_modules hjelpe med å sikre at neste installasjon er ren. Men å slette filer uten å endre de inkompatible kravene ber bare npm om å gjenoppdage den samme konflikten.

På samme måte er å tømme npms cache ikke et vanlig middel mot en semantisk peer dependency-konflikt. En ERESOLVE-rapport som navngir inkompatible versjonsområder forteller deg allerede hvilken kategori problem du har.

Når bør jeg bruke package.json overrides?

Bruk overrides når du bevisst trenger å endre hva en eksisterende avhengighetskant løser til, vanligvis for en transitiv avhengighet. npm dokumenterer overrides som en rotprosjekt-mekanisme for å erstatte avhengighetsversjoner, begrense en transitiv pakke, eller erstatte med en fork.

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

Behandle ikke overrides som en generell kommando for å erklære at en inkompatibel peer-kontrakt er magisk gyldig. Hvis det faktiske problemet er at en tredjepartspakke har feilaktig eller for smale avhengighetsmetadata, verifiser at koden er kompatibel og foretrekk en oppstrøms fikset utgivelse når den er tilgjengelig.

npm 12-dokumentasjonen beskriver også packageExtensions, som kan legge til eller korrigere tredjeparts avhengighetsmetadata – inkludert peer dependency-områder – fra rotprosjektet mens du venter på en oppstrømsfiks. Dette er et avansert verktøy fordi du tar ansvar for de korrigerte metadataene. Se npm package.json: overrides og packageExtensions.

Bør jeg bruke --legacy-peer-deps?

Bruk det kun når du bevisst trenger en midlertidig kompatibilitetsutvei.

npm install --legacy-peer-deps

npm dokumenterer legacy-peer-deps som noe som får npm til å ignorere peer dependencies under bygging av pakketreet, lignende oppførsel som npm 3 til npm 6. npm sier uttrykkelig at bruken er anbefales ikke fordi den ikke håndhever peer dependency-kontrakten som pakker kan stole på. Se npm konfigurasjonsdokumentasjonen.

Denne flagget kan være rimelig når du har uavhengig testet kombinasjonen, er blokkert av et for restriktivt oppstrøms peer-område, og trenger en kortsiktig vei mens du erstatter eller oppdaterer pakken. Det er en dårlig standard for hver eneste feilet installasjon.

Er --force det samme?

Nei. --force er bredere og mer aggressiv.

npm install --force

npm sier at force fjerner flere beskyttelser og, blant andre effekter, tillater at motstridende peer dependencies installeres i rotprosjektet. npms dokumentasjon advarer mot å bruke det når du ikke tydelig forstår konsekvensen. Se npm config: force.

Hvis det eneste målet ditt er å omgå peer dependency-håndheving midlertidig, er --legacy-peer-deps smalere i intensjon. Ingen av flaggene beviser at den resulterende applikasjonen er kompatibel.

Hvorfor feiler npm ci etter at npm install fungerte?

Sjekk hvordan låsefilen ble opprettet. npm dokumenterer at npm ci utfører en frossen ren installasjon: den krever en eksisterende package-lock.json, nekter å oppdatere den, og avslutter hvis låsefilen ikke samsvarer med package.json.

Det er en ytterligere peer-dependency-detalj: hvis låsefilen ble opprettet med et tre-formende flagg som --legacy-peer-deps, sier npm at du bør sende den samme innstillingen til npm ci, ellers kan du oppleve feil. npm foreslår å lagre innstillingen i prosjektets .npmrc når den oppførselen er bevisst en del av repositoriet:

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

Deretter committer du prosjektets .npmrc kun hvis den omgåelsen er en bevisst teambeslutning – ikke fordi en utvikler trengte en engangs redningskommando. Se npm ci-dokumentasjonen.

Hva om jeg vedlikeholder pakken som erklærer peer dependency?

Test vertsversionene du faktisk støtter, og erklær deretter det bredeste nøyaktige området. npm advarer spesifikt pakkeforfattere mot unødvendig smale peer dependency-spesifikasjoner fordi de øker sjansen for at ellers kompatible plugins ikke kan installeres sammen.

Hvis en plugin fungerer på tvers av React 18.x, for eksempel, gjør et område som unødvendig låser én patch-versjon livet vanskeligere for forbrukere. På den annen side overfører bare å utvide et område uten testing risikoen fra installasjonstidspunktet til kjøretidspunktet.

En praktisk reparasjonssekvens

1. Les ERESOLVE-utdataene og skriv ned den funnet versjonen, den konfliktende pakken, og peer-området.
2. Kjør npm ls <host-package> --all og npm explain <conflicting-package>.
3. Bruk npm view til å sammenligne peer-kravene til tilgjengelige pakkeversjoner.
4. Velg en versjonskombinasjon der de erklærte områdene faktisk overlapper.
5. Oppdater package.json gjennom npm install package@version eller en tilsvarende bevisst redigering etterfulgt av npm install.
6. Bruk overrides eller packageExtensions kun når den transitive avhengigheten eller metadataene virkelig krever prosjektnivå-inngrep.
7. Bruk --legacy-peer-deps kun som en dokumentert midlertidig unntak; reserver --force for tilfeller der du fullt ut forstår hvilken beskyttelse du slår av.

Hvordan verifiserer jeg at konflikten faktisk er løst?

Ikke stopp når npm install returnerer exit-kode 0. Verifiser avhengighetstreet og applikasjonen.

npm ls
npm test
npm run build

Bruk prosjektets faktiske test- og byggeskript; ikke alle repositorier definerer de nøyaktige kommandoene ovenfor. Hvis repositoriet har en låsefil, test også en frossen ren installasjon:

npm ci

Et sterkt resultat har fire egenskaper:

• npm install lykkes uten en ERESOLVE-konflikt.
• npm ls rapporterer ikke de relevante pakkene som ugyldige eller manglende.
• Testene dine og produksjonsbygget består med de løste versjonene.
• npm ci lykkes i et rent miljø ved hjelp av den committede låsefilen og prosjektkonfigurasjonen.

Hvis du bare kan tilfredsstille den første betingelsen ved å bruke --force, er avhengighetskonflikten ikke egentlig løst – du har instruert npm til å akseptere den. Det kan være en bevisst kortsiktig beslutning, men det bør registreres som teknisk gjeld der den inkompatible pakken og den tiltenkte erstatnings- eller oppgraderingsveien er tydelig identifisert.