Kako riješiti npm ERR! code ERESOLVE sukob peer ovisnosti

Pokrenete npm install, očekujete da će npm dodati jedan paket, a umjesto toga dobijete zid izlaza koji završava s npm ERR! code ERESOLVE i porukom “unable to resolve dependency tree”. Važno pitanje nije “Kako natjerati npm da prestane prigovarati?” Već je “Koje se dvije verzije zahtjeva ne mogu istovremeno zadovoljiti?”

Ta razlika određuje hoćete li na kraju imati stabilno rješenje ili ćete samo prisiliti npm da instalira stablo ovisnosti koje jedan od vaših paketa izričito navodi kao nepodržan.

Napomena o verziji: prema provjeri od 11. rujna 2026., npm dokumentacija označava npm CLI 12.0.2 kao najnoviju verziju dokumentacije. npm automatski instalira peerDependencies kao zadano ponašanje od npm 7, a sukobljeni peer zahtjevi mogu uzrokovati neuspjeh instalacije kada npm ne može konstruirati valjano stablo. Pogledajte npm package.json dokumentaciju.

Što ERESOLVE zapravo znači?

Izravan odgovor: npm je pronašao zahtjeve ovisnosti koji se ne mogu zadovoljiti zajedno pod trenutnim stablom ovisnosti.

Peer ovisnost je ugovor o kompatibilnosti. Dodatak ili prateći paket može deklarirati da očekuje da vaš projekt osigura kompatibilnu verziju drugog paketa. Na primjer, dodatak može deklarirati:

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

Ako vaš projekt zahtijeva React 18, a taj dodatak deklarira kompatibilnost samo s React 17, npm ima dokaz da tražena kombinacija možda nije podržana. Paket se možda slučajno pokreće s React 18, ali npm ne može pretpostaviti da je autor paketa namjeravao tu kompatibilnost.

Npmova vlastita dokumentacija savjetuje autorima paketa da rasponi peer ovisnosti budu što širi koliko to dopušta njihova testirana kompatibilnost jer preuski peer rasponi mogu stvoriti sukobe. To ne znači da bi korisnici trebali jednostavno ignorirati svaki raspon koji im se ne sviđa.

Koji paket zapravo uzrokuje sukob?

Pročitajte ERESOLVE izvještaj prije nego što išta promijenite. Potražite dva dijela:

• Found: verzija koja je već odabrana ili zatražena od strane vašeg korijenskog projekta.
• Could not resolve dependency / peer: paket koji zahtijeva drugačiji raspon.

U pojednostavljenom primjeru, npm bi mogao reći da vaš korijenski projekt koristi react@18.3.0, dok some-package@2.1.0 zahtijeva react@^16.8.0 || ^17.0.0. Sukob nije “npm protiv Reacta”. Radi se o nekompatibilnosti između vaše odabrane React verzije i peer raspona deklariranog od strane some-package.

Zabilježite tri vrijednosti prije uređivanja package.json: host paket, sukobljeni paket i peer raspon koji on očekuje.

Trebam li prvo pregledati stablo ovisnosti?

Da, posebno kada sukobljeni paket nije izravna ovisnost. npm pruža dvije korisne naredbe za različite prikaze stabla.

npm ls react --all
npm explain some-package

npm ls ispisuje logičko stablo ovisnosti i može identificirati nevaljane ili nedostajuće pakete. npm explain, dostupan i kao npm why, prikazuje lanac ovisnosti koji je uzrokovao instalaciju paketa. Pogledajte npm ls dokumentaciju i npm explain dokumentaciju.

Također možete pregledati metapodatke registra za verziju kandidata:

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

Naredba npm view čita metapodatke paketa iz registra, što vam omogućuje usporedbu podržava li novije ili starije izdanje host verziju koju već koristite. Pogledajte npm view dokumentaciju.

Mogu li to popraviti instaliranjem kompatibilne verzije paketa?

Obično je ovo najbolje rješenje. Pronađite presjek između host verzije koju vaša aplikacija treba i peer raspona koji dodatak podržava.

Pretpostavimo da vaš projekt sadrži:

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

Ako novije some-package izdanje deklarira kompatibilnost s React 18, ažurirajte taj paket:

npm install some-package@latest

Ako vaša aplikacija ne treba React 18, a dodatak je važan, suprotan izbor može biti sigurniji: instalirajte React verziju koja stvarno zadovoljava dokumentirani peer raspon dodatka.

Pravi smjer ovisi o vašoj aplikaciji. Nemojte automatski snižavati okvir samo da biste sačuvali napušteni dodatak i nemojte automatski nadograđivati dodatak kroz glavnu verziju bez čitanja njegovih bilješki o migraciji.

Trebam li prvo urediti package.json ili prvo obrisati node_modules?

Prvo riješite odluku o verziji. Brisanje node_modules ne mijenja nekompatibilni peer raspon.

Kada package.json opisuje kompatibilan skup izravnih ovisnosti, pokrenite normalnu instalaciju kako bi npm mogao ažurirati lockfile:

npm install

Ako namjerno ponovno gradite zastarjelu lokalnu instalaciju nakon ispravljanja deklaracija, uklanjanje node_modules može pomoći osigurati da je sljedeća instalacija čista. Ali brisanje datoteka bez promjene nekompatibilnih zahtjeva jednostavno traži od npm-a da ponovno otkrije isti sukob.

Također, čišćenje npm predmemorije nije normalan lijek za semantički sukob peer ovisnosti. ERESOLVE izvještaj koji imenuje nekompatibilne raspone verzija već vam govori koju vrstu problema imate.

Kada trebam koristiti overrides u package.json?

Koristite overrides kada namjerno trebate promijeniti na što se postojeća grana ovisnosti rješava, obično za tranzitivnu ovisnost. npm dokumentira overrides kao mehanizam korijenskog projekta za zamjenu verzija ovisnosti, ograničavanje tranzitivnog paketa ili zamjenu forka.

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

Nemojte tretirati overrides kao generičku naredbu za deklariranje da je nekompatibilni peer ugovor čarobno valjan. Ako je stvarni problem da treći paket ima netočne ili preuske metapodatke ovisnosti, provjerite je li koda kompatibilna i preferirajte gornje ispravljeno izdanje kada je dostupno.

Npm 12 dokumentacija također opisuje packageExtensions, koji može dodati ili ispraviti metapodatke ovisnosti trećih strana—uključujući raspone peer ovisnosti—iz korijenskog projekta dok čekate gornju ispravku. Ovo je napredni alat jer preuzimate odgovornost za ispravljene metapodatke. Pogledajte npm package.json: overrides i packageExtensions.

Trebam li koristiti --legacy-peer-deps?

Koristite ga samo kada svjesno trebate privremeni izlaz za kompatibilnost.

npm install --legacy-peer-deps

npm dokumentira legacy-peer-deps kao opciju koja uzrokuje da npm ignorira peer ovisnosti tijekom izgradnje stabla paketa, slično ponašanju npm 3 do npm 6. npm izričito kaže da je njegova upotreba ne preporučljiva jer ne provodi ugovor o peer ovisnostima na koji paketi mogu računati. Pogledajte npm konfiguracijsku dokumentaciju.

Ova zastavica može biti razumna kada ste neovisno testirali kombinaciju, blokirani ste preograničenim gornjim peer rasponom i trebate kratkoročno rješenje dok zamjenjujete ili ažurirate paket. To je loša zadana opcija za svaku neuspjelu instalaciju.

Je li --force isto što i to?

Ne. --force je širi i agresivniji.

npm install --force

npm navodi da force uklanja nekoliko zaštita i, između ostalih učinaka, dopušta instalaciju sukobljenih peer ovisnosti u korijenskom projektu. npmova dokumentacija upozorava protiv korištenja kada jasno ne razumijete posljedicu. Pogledajte npm config: force.

Ako je vaš jedini cilj privremeno zaobići provedbu peer ovisnosti, --legacy-peer-deps je uži po namjeri. Nijedna zastavica ne dokazuje da je rezultirajuća aplikacija kompatibilna.

Zašto npm ci ne uspijeva nakon što je npm install uspio?

Provjerite kako je lockfile stvoren. npm dokumentira da npm ci izvodi zamrznutu čistu instalaciju: zahtijeva postojeći package-lock.json, odbija ga ažurirati i izlazi ako lockfile ne odgovara package.json.

Postoji dodatni detalj o peer ovisnostima: ako je lockfile stvoren s zastavicom za oblikovanje stabla kao što je --legacy-peer-deps, npm kaže da biste trebali proslijediti istu postavku na npm ci ili možete naići na pogreške. npm predlaže pohranjivanje postavke u projektni .npmrc kada je to ponašanje namjerno dio repozitorija:

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

Zatim commitajte projektni .npmrc samo ako je to zaobilaženje namjerna odluka tima—ne zato što je jedan developer trebao jednokratnu spašavajuću naredbu. Pogledajte npm ci dokumentaciju.

Što ako održavam paket koji deklarira peer ovisnost?

Testirajte host verzije koje stvarno podržavate, a zatim deklarirajte najširi točan raspon. npm posebno upozorava autore paketa protiv nepotrebno uskih specifikacija peer ovisnosti jer one povećavaju šansu da se inače kompatibilni dodaci ne mogu instalirati zajedno.

Ako dodatak radi kroz React 18.x, na primjer, raspon koji nepotrebno fiksira jednu zakrpa verziju otežava život korisnicima. S druge strane, proširivanje raspona bez testiranja jednostavno prenosi rizik s vremena instalacije na vrijeme izvršavanja.

Praktičan slijed popravka

1. Pročitajte ERESOLVE izlaz i zapišite pronađenu verziju, sukobljeni paket i peer raspon.
2. Pokrenite npm ls <host-package> --all i npm explain <conflicting-package>.
3. Koristite npm view za usporedbu peer zahtjeva dostupnih verzija paketa.
4. Odaberite kombinaciju verzija čiji deklarirani rasponi stvarno preklapaju.
5. Ažurirajte package.json putem npm install package@version ili ekvivalentnog namjernog uređivanja praćenog s npm install.
6. Koristite overrides ili packageExtensions samo kada tranzitivna ovisnost ili metapodaci stvarno zahtijevaju intervenciju na razini projekta.
7. Koristite --legacy-peer-deps samo kao dokumentiranu privremenu iznimku; rezervirajte --force za slučajeve kada u potpunosti razumijete koju zaštitu onemogućujete.

Kako provjeriti je li sukob stvarno riješen?

Nemojte prestati kada npm install vrati izlazni kod 0. Provjerite stablo ovisnosti i aplikaciju.

npm ls
npm test
npm run build

Koristite stvarne testne i build skripte projekta; ne definira svaki repozitorij točno gore navedene naredbe. Ako repozitorij ima lockfile, testirajte i zamrznutu čistu instalaciju:

npm ci

Jak rezultat ima četiri svojstva:

• npm install uspijeva bez ERESOLVE sukoba.
• npm ls ne prijavljuje relevantne pakete kao nevaljane ili nedostajuće.
• Testovi i produkcijski build prolaze s riješenim verzijama.
• npm ci uspijeva u čistom okruženju koristeći commitani lockfile i konfiguraciju projekta.

Ako možete zadovoljiti samo prvi uvjet korištenjem --force, sukob ovisnosti nije stvarno riješen—you ste naveli npm da ga prihvati. To može biti svjesna kratkoročna odluka, ali treba je zabilježiti kao tehnički dug s jasno identificiranim nekompatibilnim paketom i namijenjenim putem zamjene ili nadogradnje.