Kako odpraviti napako npm ERR! code ERESOLVE zaradi konflikta odvisnosti vrstnikov

Zaženete npm install, pričakujete, da bo npm dodal en paket, namesto tega pa prejmete steno izpisa, ki se konča z npm ERR! code ERESOLVE in sporočilom “unable to resolve dependency tree”. Pomembno vprašanje ni “Kako naj npm neha opozarjati?”, temveč “Katera dva zahtevana pogoja različic ne moreta biti hkrati izpolnjena?”

Ta razlika določa, ali boste dosegli stabilno popravilo ali pa boste npm le prisilili, da namesti drevo odvisnosti, ki ga eden od vaših paketov izrecno ne podpira.

Opomba o različici: po preverjanju 11. septembra 2026 dokumentacija npm označuje npm CLI 12.0.2 kot najnovejšo različico dokumentacije. npm samodejno namešča peerDependencies kot privzeto nastavenost od različice npm 7 naprej, konfliktne zahteve vrstnikov pa lahko povzročijo napako pri namestitvi, če npm ne more zgraditi veljavnega drevesa. Glejte dokumentacijo npm package.json.

Kaj dejansko pomeni ERESOLVE?

Neposreden odgovor: npm je našel zahteve odvisnosti, ki jih ni mogoče hkrati izpolniti v trenutnem drevesu odvisnosti.

Odvisnost vrstnika je pogodba o združljivosti. Vtičnik ali spremljevalni paket lahko razglasi, da pričakuje, da bo vaš projekt zagotovil združljivo različico drugega paketa. Na primer, vtičnik lahko razglasi:

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

Če vaš projekt zahteva React 18 in ta vtičnik razglasi združljivost le z React 17, ima npm dokaz, da zahtevana kombinacija morda ni podprta. Paket se morda slučajno izvaja z React 18, vendar npm ne more predpostavljati, da je avtor paketa nameraval to združljivost.

Npmova lastna dokumentacija avtorjem paketov svetuje, naj ohranjajo razpone odvisnosti vrstnikov čim širše, kot to dopušča njihova testirana združljivost, ker preozki razponi vrstnikov lahko ustvarijo konflikte. To ne pomeni, da bi uporabniki morali preprosto ignorirati vsak razpon, ki jim ni všeč.

Kateri paket dejansko povzroča konflikt?

Preden karkoli spremenite, preberite poročilo ERESOLVE. Poiščite dva dela:

• Found: različica, ki je že izbrana ali zahtevana v vašem korenskem projektu.
• Could not resolve dependency / peer: paket, ki zahteva drugačen razpon.

V poenostavljenem primeru bi npm lahko rekel, da vaš korenski projekt uporablja react@18.3.0, medtem ko some-package@2.1.0 zahteva react@^16.8.0 || ^17.0.0. Konflikt ni “npm proti Reactu”. Gre za nezdružljivost med izbrano različico Reacta in razponom vrstnikov, ki ga razglasi some-package.

Preden uredite package.json, zabeležite tri vrednosti: gostiteljski paket, konfliktni paket in razpon vrstnikov, ki ga ta pričakuje.

Ali moram najprej pregledati drevo odvisnosti?

Da, zlasti kadar konfliktni paket ni neposredna odvisnost. npm zagotavlja dva uporabna ukaza za različne poglede na drevo.

npm ls react --all
npm explain some-package

npm ls izpiše logično drevo odvisnosti in lahko identificira neveljavne ali manjkajoče pakete. npm explain, znan tudi kot npm why, prikaže verigo odvisnosti, ki je povzročila namestitev paketa. Glejte dokumentacijo npm ls in dokumentacijo npm explain.

Lahko tudi pregledate metapodatke registra za kandidatsko različico paketa:

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

Ukaz npm view bere metapodatke paketa iz registra, kar vam omogoča primerjavo, ali novejša ali starejša izdaja podpira različico gostitelja, ki jo že uporabljate. Glejte dokumentacijo npm view.

Ali lahko to popravim z namestitvijo združljive različice paketa?

Običajno je to najboljša rešitev. Poiščite presek med različico gostitelja, ki jo potrebuje vaša aplikacija, in razponom vrstnikov, ki ga podpira vtičnik.

Recimo, da vaš projekt vsebuje:

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

Če novejša izdaja some-package razglasi združljivost z React 18, posodobite ta paket:

npm install some-package@latest

Če vaša aplikacija ne potrebuje React 18 in je vtičnik pomemben, je morda varnejša nasprotna izbira: namestite različico Reacta, ki dejansko zadošča dokumentiranemu razponu vrstnikov vtičnika.

Prava smer je odvisna od vaše aplikacije. Ne samodejno znižujte različice ogrodja samo zato, da bi ohranili zapuščen vtičnik, in ne samodejno nadgrajujte vtičnika čez glavno različico, ne da bi prebrali njegova opomba o migraciji.

Ali moram najprej urediti package.json ali izbrisati node_modules?

Najprej popravite odločitev o različici. Brisanje node_modules ne spremeni nezdružljivega razpona vrstnikov.

Ko package.json opisuje združljiv nabor neposrednih odvisnosti, zaženite običajno namestitev, da lahko npm posodobi zaklepno datoteko:

npm install

Če po popravku deklaracij namerno ponovno gradite zastarelo lokalno namestitev, lahko odstranitev node_modules pomaga zagotoviti čisto naslednjo namestitev. Vendar pa brisanje datotek brez spremembe nezdružljivih zahtev npm le prosi, da znova odkrije isti konflikt.

Prav tako čiščenje npm predpomnilnika ni običajno zdravilo za semantični konflikt odvisnosti vrstnikov. Poročilo ERESOLVE, ki navaja nezdružljive razpone različic, vam že pove, za katero vrsto težave gre.

Kdaj naj uporabim overrides v package.json?

Uporabite overrides, kadar namerno potrebujete spremembo, na kaj se razreši obstoječa povezava odvisnosti, običajno za prehodno odvisnost. npm dokumentira overrides kot mehanizem korenskega projekta za zamenjavo različic odvisnosti, omejevanje prehodnega paketa ali substitucijo forka.

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

Ne obravnavajte overrides kot splošnega ukaza za razglasitev, da je nezdružljiva pogodba vrstnikov čudežno veljavna. Če je dejanska težava v tem, da ima tretji paket napačne ali preozke metapodatke odvisnosti, preverite združljivost kode in po možnosti uporabite popravljeno izdajo navzgor, če je na voljo.

Dokumentacija npm 12 opisuje tudi packageExtensions, ki lahko iz korenskega projekta doda ali popravi metapodatke odvisnosti tretjih oseb – vključno z razponi odvisnosti vrstnikov – med čakanjem na popravilo navzgor. To je napredno orodje, ker prevzemate odgovornost za popravljene metapodatke. Glejte npm package.json: overrides in packageExtensions.

Ali naj uporabim --legacy-peer-deps?

Uporabite ga le, kadar vedno potrebujete začasno izhodno vrata za združljivost.

npm install --legacy-peer-deps

npm dokumentira legacy-peer-deps kot nastavitev, ki povzroči, da npm pri gradnji drevesa paketov ignorira odvisnosti vrstnikov, podobno kot obnašanje npm 3 do npm 6. npm izrecno navaja, da je njegova uporaba odsvetovana, ker ne uveljavlja pogodbe o odvisnostih vrstnikov, na katero se paketi lahko zanašajo. Glejte dokumentacijo konfiguracije npm.

Ta zastavica je lahko smiselna, kadar ste kombinacijo neodvisno testirali, vas blokira preveč omejujoč razpon vrstnikov navzgor in potrebujete kratkoročno pot, medtem ko paket zamenjate ali posodobite. Slaba je privzeta izbira za vsako neuspešno namestitev.

Ali je --force enako?

Ne. --force je širši in bolj agresiven.

npm install --force

npm navaja, da force odstrani več zaščit in med drugim omogoča namestitev konfliktnih odvisnosti vrstnikov v korenskem projektu. Npmova dokumentacija opozarja proti uporabi, če ne razumete jasno posledic. Glejte npm config: force.

Če je vaš edini cilj začasno zaobiti uveljavljanje odvisnosti vrstnikov, je --legacy-peer-deps bolj ozko namenjen. Nobena zastavica ne dokazuje, da je nastala aplikacija združljiva.

Zakaj npm ci ne uspe, potem ko je npm install deloval?

Preverite, kako je bila ustvarjena zaklepna datoteka. npm dokumentira, da npm ci izvede zamrznjeno čisto namestitev: zahteva obstoječo package-lock.json, zavrne njeno posodabljanje in konča, če zaklepna datoteka ne ustreza package.json.

Obstaja dodatna podrobnost glede odvisnosti vrstnikov: če je bila zaklepna datoteka ustvarjena z zastavico za oblikovanje drevesa, kot je --legacy-peer-deps, npm pravi, da morate isto nastavitev posredovati tudi npm ci, sicer lahko naletite na napake. npm predlaga shranjevanje nastavitve v .npmrc projekta, kadar je to obnašanje namerno del repozitorija:

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

Nato potrdite .npmrc projekta le, če je ta obvoz namerna odločitev ekipe – ne zato, ker je en razvijalec potreboval enkratno rešilno ukazno vrstico. Glejte dokumentacijo npm ci.

Kaj pa, če vzdržujem paket, ki razglasi odvisnost vrstnika?

Testirajte različice gostiteljev, ki jih dejansko podpirate, nato razglasite najširši natančen razpon. npm posebej opozarja avtorje paketov proti nepotrebno ozkim specifikacijam odvisnosti vrstnikov, ker povečujejo verjetnost, da sicer združljivi vtičniki ne morejo biti nameščeni skupaj.

Če vtičnik deluje čez React 18.x, na primer, razpon, ki nepotrebno pripne eno popravljeno različico, oteži življenje uporabnikom. Po drugi strani pa razširitev razpona brez testiranja preprosto prenese tveganje iz časa namestitve v čas izvajanja.

Praktično zaporedje popravila

1. Preberite izpis ERESOLVE in zapišite najdeno različico, konfliktni paket in razpon vrstnikov.
2. Zaženite npm ls <host-package> --all in npm explain <conflicting-package>.
3. Uporabite npm view za primerjavo zahtev vrstnikov razpoložljivih različic paketa.
4. Izberite kombinacijo različic, katerih razglaseni razponi se dejansko prekrivajo.
5. Posodobite package.json prek npm install package@version ali enakovrednega namernega urejanja, ki mu sledi npm install.
6. Uporabite overrides ali packageExtensions le, kadar prehodna odvisnost ali metapodatki res zahtevajo poseg na ravni projekta.
7. Uporabite --legacy-peer-deps le kot dokumentirano začasno izjemo; --force rezervirajte za primere, ko popolnoma razumete, katero zaščito onemogočate.

Kako preverim, ali je konflikt res odpravljen?

Ne ustavite se, ko npm install vrne izhodno kodo 0. Preverite drevo odvisnosti in aplikacijo.

npm ls
npm test
npm run build

Uporabite dejanske skripte za testiranje in gradnjo projekta; ne vsak repozitorij definira zgornje natančne ukaze. Če ima repozitorij zaklepno datoteko, preizkusite tudi zamrznjeno čisto namestitev:

npm ci

Močan rezultat ima štiri lastnosti:

• npm install uspe brez konflikta ERESOLVE.
• npm ls ne poroča o relevantnih paketih kot neveljavnih ali manjkajočih.
• Vaši testi in produkcijska gradnja uspejo z razrešenimi različicami.
• npm ci uspe v čistem okolju z uporabo potrjene zaklepne datoteke in konfiguracije projekta.

Če lahko prvi pogoj izpolnite le z uporabo --force, konflikt odvisnosti ni bil res rešen – npm ste le navodili, naj ga sprejme. To je lahko zavestna kratkoročna odločitev, vendar jo je treba zabeležiti kot tehnični dolg z jasno identificiranim nezdružljivim paketom in načrtovano potjo zamenjave ali nadgradnje.