Ako opraviť konflikt peer dependency npm ERR! code ERESOLVE

Spustíte npm install, očakávate, že npm pridá jeden balík, a namiesto toho dostanete stenu výstupu končiacu npm ERR! code ERESOLVE a „unable to resolve dependency tree“. Dôležitá otázka neznie „Ako donútim npm prestať sťažovať sa?“. Znie „Ktoré dve požiadavky na verzie nemôžu byť splnené súčasne?“

Tento rozdiel určuje, či skončíte so stabilným riešením, alebo len donútite npm nainštalovať strom závislostí, ktorý jeden z vašich balíkov výslovne uvádza, že nepodporuje.

Poznámka k verzii: podľa overenia z 11. septembra 2026 dokumentácia npm označuje npm CLI 12.0.2 za najnovšiu verziu dokumentácie. npm automaticky inštaluje peerDependencies ako predvolené od verzie npm 7 a konfliktné požiadavky peer dependency môžu spôsobiť zlyhanie inštalácie, ak npm nedokáže zostaviť platný strom. Pozri dokumentáciu npm package.json.

Čo vlastne znamená ERESOLVE?

Priama odpoveď: npm našiel požiadavky na závislosti, ktoré nemôžu byť splnené súčasne v rámci aktuálneho stromu závislostí.

Peer dependency je zmluva o kompatibilite. Plugin alebo sprievodný balík môže deklarovat, že očakáva, že váš projekt poskytne kompatibilnú verziu iného balíka. Napríklad plugin môže deklarovat:

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

Ak váš projekt vyžaduje React 18 a tento plugin deklaruje kompatibilitu len s React 17, npm má dôkaz, že požadovaná kombinácia nemusí byť podporovaná. Balík môže náhodou fungovať s React 18, ale npm nemôže predpokladať, že autor balíka zamýšľal túto kompatibilitu.

Vlastná dokumentácia npm odporúča autorom balíkov udržiavať rozsahy peer dependency tak široké, ako to dovoľuje ich testovaná kompatibilita, pretože príliš úzke rozsahy peer dependency môžu vytvárať konflikty. To neznamená, že by spotrebitelia mali jednoducho ignorovať každý rozsah, ktorý sa im nepáči.

Ktorý balík skutočne spôsobuje konflikt?

Pred zmenou čohokoľvek si prečítajte report ERESOLVE. Hľadajte dve časti:

• Found: verzia, ktorá bola už vybraná alebo požadovaná vaším koreňovým projektom.
• Could not resolve dependency / peer: balík, ktorý vyžaduje iný rozsah.

V zjednodušenom príklade môže npm uviesť, že váš koreňový projekt používa react@18.3.0, zatiaľ čo some-package@2.1.0 vyžaduje react@^16.8.0 || ^17.0.0. Konflikt nie je „npm proti React“. Ide o nekompatibilitu medzi vami vybranou verziou React a rozsahom peer dependency deklarovaným balíkom some-package.

Pred úpravou package.json si zaznamenajte tri hodnoty: hostiteľský balík, konfliktný balík a rozsah peer dependency, ktorý očakáva.

Potrebujem najprv preskúmať strom závislostí?

Áno, najmä ak konfliktný balík nie je priamou závislosťou. npm poskytuje dva užitočné príkazy pre rôzne pohľady na strom.

npm ls react --all
npm explain some-package

npm ls vypíše logický strom závislostí a môže identifikovať neplatné alebo chýbajúce balíky. npm explain, dostupný aj ako npm why, zobrazuje reťazec závislostí, ktorý spôsobil inštaláciu balíka. Pozri dokumentáciu npm ls a dokumentáciu npm explain.

Môžete tiež preskúmať metadáta registru pre kandidátsku verziu balíka:

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

Príkaz npm view číta metadáta balíka z registru, čo vám umožňuje porovnať, či novšia alebo staršia verzia podporuje verziu hostiteľa, ktorú už používate. Pozri dokumentáciu npm view.

Môžem to opraviť inštaláciou kompatibilnej verzie balíka?

Zvyčajne je to najlepšie riešenie. Nájdite prienik medzi verziou hostiteľa, ktorú vaša aplikácia potrebuje, a rozsahom peer dependency podporovaným pluginom.

Predpokladajme, že váš projekt obsahuje:

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

Ak novšia verzia some-package deklaruje kompatibilitu s React 18, aktualizujte tento balík:

npm install some-package@latest

Ak vaša aplikácia nepotrebuje React 18 a plugin je dôležitý, opačná voľba môže byť bezpečnejšia: nainštalujte verziu React, ktorá skutočne spĺňa dokumentovaný rozsah peer dependency pluginu.

Správny smer závisí od vašej aplikácie. Neautomaticky neznižujte verziu frameworku len preto, aby ste zachovali opustený plugin, a neautomaticky neaktualizujte plugin cez hlavnú verziu bez prečítania jeho poznámok k migrácii.

Mám najprv upraviť package.json alebo vymazať node_modules?

Najprv opravte rozhodnutie o verzii. Vymazanie node_modules nezmení nekompatibilný rozsah peer dependency.

Akonáhle package.json opisuje kompatibilnú sadu priamych závislostí, spustite normálnu inštaláciu, aby npm mohol aktualizovať lockfile:

npm install

Ak zámerne rebuildujete zastaralú lokálnu inštaláciu po oprave deklarácií, odstránenie node_modules môže pomôcť zabezpečiť čistú ďalšiu inštaláciu. Ale mazanie súborov bez zmeny nekompatibilných požiadaviek len žiada npm, aby znovu objavil ten istý konflikt.

Rovnako tak vymazanie cache npm nie je bežným liekom na sémantický konflikt peer dependency. Report ERESOLVE, ktorý menuje nekompatibilné rozsahy verzií, vám už hovorí, o akú kategóriu problému ide.

Kedy by som mal použiť overrides v package.json?

Použite overrides, keď zámerne potrebujete zmeniť, na čo sa existujúca hrana závislosti vyhodnocuje, zvyčajne pre tranzitívnu závislosť. npm dokumentuje overrides ako mechanizmus koreňového projektu na nahradenie verzií závislostí, obmedzenie tranzitívneho balíka alebo nahradenie forku.

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

Nepoužívajte overrides ako všeobecný príkaz na deklarovanie, že nekompatibilná zmluva peer dependency je magicky platná. Ak je skutočným problémom to, že tretí balík má nesprávne alebo príliš úzke metadáta závislostí, overte kompatibilitu kódu a uprednostnite upstream opravu, ak je k dispozícii.

Dokumentácia npm 12 tiež opisuje packageExtensions, ktoré môže pridať alebo opraviť metadáta závislostí tretích strán – vrátane rozsahov peer dependency – z koreňového projektu, kým čakáte na upstream opravu. Toto je pokročilý nástroj, pretože preberáte zodpovednosť za opravené metadáta. Pozri npm package.json: overrides a packageExtensions.

Mal by som použiť --legacy-peer-deps?

Použite ho len vtedy, keď vedome potrebujete dočasný únikový východ pre kompatibilitu.

npm install --legacy-peer-deps

npm dokumentuje legacy-peer-deps ako spôsob, ktorý spôsobuje, že npm ignoruje peer dependencies pri zostavovaní stromu balíkov, podobne ako správanie npm 3 až npm 6. npm výslovne uvádza, že jeho použitie nie je odporúčané, pretože nevynucuje zmluvu peer dependency, na ktorú sa balíky môžu spoliehať. Pozri dokumentáciu konfigurácie npm.

Tento príznak môže byť rozumný, keď ste kombináciu nezávisle otestovali, ste blokovaní príliš reštriktívnym upstream rozsahom peer dependency a potrebujete krátkodobú cestu, kým balík nahradíte alebo aktualizujete. Je to zlý predvolený postup pre každú neúspešnú inštaláciu.

Je --force to isté?

Nie. --force je širšie a agresívnejšie.

npm install --force

npm uvádza, že force odstraňuje niekoľko ochranných mechanizmov a okrem iného umožňuje inštaláciu konfliktných peer dependencies v koreňovom projekte. Dokumentácia npm varuje pred používaním, keď jasne nerozumiete následkom. Pozri npm config: force.

Ak je vaším jediným cieľom dočasne obísť vynucovanie peer dependency, --legacy-peer-deps je užšie zamerané. Ani jeden z týchto príznakov nedokazuje, že výsledná aplikácia je kompatibilná.

Prečo npm ci zlyhá po tom, čo npm install fungoval?

Skontrolujte, ako bol vytvorený lockfile. npm dokumentuje, že npm ci vykonáva zmrazenú čistú inštaláciu: vyžaduje existujúci package-lock.json, odmieta ho aktualizovať a ukončí sa, ak lockfile nezodpovedá package.json.

Existuje ďalší detail týkajúci sa peer dependency: ak bol lockfile vytvorený s príznakom tvarovania stromu, ako je --legacy-peer-deps, npm hovorí, že by ste mali odovzdať rovnaké nastavenie príkazu npm ci, inak môžete naraziť na chyby. npm navrhuje uložiť nastavenie do súboru .npmrc projektu, keď je toto správanie zámerne súčasťou repozitára:

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

Potom commitnite projektový .npmrc len vtedy, ak je toto obídenie zámerne tímové rozhodnutie – nie preto, že jeden vývojár potreboval jednorazovú záchrannú príkazovú riadku. Pozri dokumentáciu npm ci.

Čo ak udržiavam balík, ktorý deklaruje peer dependency?

Otestujte verzie hostiteľa, ktoré skutočne podporujete, a potom deklarujte najširší presný rozsah. npm konkrétne varuje autorov balíkov pred zbytočne úzkymi špecifikáciami peer dependency, pretože zvyšujú šancu, že inak kompatibilné pluginy nebudú môcť byť nainštalované spolu.

Ak plugin funguje naprieč React 18.x, napríklad, rozsah, ktorý zbytočne pripúta jednu patch verziu, sťažuje život spotrebiteľom. Na druhej strane, rozšírenie rozsahu bez testovania jednoducho prenáša riziko z času inštalácie na čas behu.

Praktická postupnosť opravy

1. Prečítajte výstup ERESOLVE a zapíšte si nájdenú verziu, konfliktný balík a rozsah peer dependency.
2. Spustite npm ls <host-package> --all a npm explain <conflicting-package>.
3. Použite npm view na porovnanie požiadaviek peer dependency dostupných verzií balíka.
4. Vyberte kombináciu verzií, ktorých deklarované rozsahy sa skutočne prekrývajú.
5. Aktualizujte package.json pomocou npm install package@version alebo ekvivalentnej zámernej úpravy nasledovanej npm install.
6. Použite overrides alebo packageExtensions len vtedy, keď tranzitívna závislosť alebo metadáta skutočne vyžadujú zásah na úrovni projektu.
7. Použite --legacy-peer-deps len ako zdokumentovanú dočasnú výnimku; vyhraďte --force pre prípady, keď plne chápete, akú ochranu vypínate.

Ako overím, že je konflikt skutočne vyriešený?

Nestávajte, keď npm install vráti ukončovací kód 0. Overte strom závislostí a aplikáciu.

npm ls
npm test
npm run build

Použite skutočné testovacie a build skripty projektu; nie každý repozitár definuje presne vyššie uvedené príkazy. Ak má repozitár lockfile, otestujte aj zmrazenú čistú inštaláciu:

npm ci

Silný výsledok má štyri vlastnosti:

• npm install prebehne úspešne bez konfliktu ERESOLVE.
• npm ls nehlási relevantné balíky ako neplatné alebo chýbajúce.
• Vaše testy a produkčný build prejdú s vyriešenými verziami.
• npm ci prebehne úspešne v čistom prostredí s použitím commitnutého lockfile a konfigurácie projektu.

Ak môžete splniť prvú podmienku len použitím --force, konflikt závislostí nebol skutočne vyriešený – len ste npm instruovali, aby ho prijal. To môže byť vedomé krátkodobé rozhodnutie, ale malo by byť zaznamenané ako technický dlh s jasne identifikovaným nekompatibilným balíkom a zamýšľanou cestou náhrady alebo aktualizácie.