Jak opravit chybu npm ERR! code ERESOLVE: Konflikt peer dependencies

Spustíte npm install, očekáváte, že npm přidá jeden balíček, a místo toho dostanete stěnu výstupu končící hláškou npm ERR! code ERESOLVE a „unable to resolve dependency tree“. Důležitá otázka nezní „Jak přimět npm, aby přestal stěžovat?“. Zní „Které dvě požadavky na verzi nemohou být splněny současně?“

Tento rozdíl určuje, zda skončíte se stabilním řešením, nebo pouze donutíte npm nainstalovat strom závislostí, který jeden z vašich balíčků výslovně označuje za nepodporovaný.

Poznámka k verzi: podle ověření ze dne 11. září 2026 dokumentace npm uvádí npm CLI 12.0.2 jako nejnovější verzi dokumentace. npm automaticky instaluje peerDependencies ve výchozím nastavení od verze npm 7 a konfliktní požadavky peer dependencies mohou způsobit selhání instalace, pokud npm nedokáže sestavit platný strom závislostí. Viz dokumentace npm package.json.

Co přesně znamená ERESOLVE?

Přímá odpověď: npm našel požadavky na závislosti, které nelze současně splnit v rámci aktuálního stromu závislostí.

Peer dependency je smlouva o kompatibilitě. Plugin nebo doprovodný balíček může deklarovat, že očekává, že váš projekt poskytne kompatibilní verzi jiného balíčku. Například plugin může deklarovat:

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

Pokud váš projekt vyžaduje React 18 a tento plugin deklaruje kompatibilitu pouze s React 17, npm má důkaz, že požadovaná kombinace nemusí být podporována. Balíček může náhodou fungovat s React 18, ale npm nemůže předpokládat, že autor balíčku tuto kompatibilitu zamýšlel.

Vlastní dokumentace npm doporučuje autorům balíčků udržovat rozsahy peer dependencies tak široké, jak dovoluje jejich testovaná kompatibilita, protože příliš úzké rozsahy peer dependencies mohou vytvářet konflikty. To neznamená, že by uživatelé měli jednoduše ignorovat každý rozsah, který se jim nelíbí.

Který balíček ve skutečnosti způsobuje konflikt?

Před změnou čehokoli si přečtěte zprávu ERESOLVE. Hledejte dvě části:

• Found: verze, která byla již vybrána nebo vyžádána vaším kořenovým projektem.
• Could not resolve dependency / peer: balíček, který vyžaduje jiný rozsah.

V zjednodušeném příkladu může npm uvést, že váš kořenový projekt používá react@18.3.0, zatímco some-package@2.1.0 vyžaduje react@^16.8.0 || ^17.0.0. Konflikt není „npm versus React“. Jde o nekompatibilitu mezi vámi vybranou verzí React a rozsahem peer dependencies deklarovaným balíčkem some-package.

Před úpravou package.json si zapište tři hodnoty: hostitelský balíček, konfliktní balíček a rozsah peer dependencies, který očekává.

Musím nejprve prozkoumat strom závislostí?

Ano, zejména pokud konfliktní balíček není přímou závislostí. npm poskytuje dva užitečné příkazy pro různé pohledy na strom závislostí.

npm ls react --all
npm explain some-package

npm ls vypíše logický strom závislostí a může identifikovat neplatné nebo chybějící balíčky. npm explain, dostupný také jako npm why, zobrazuje řetězec závislostí, který způsobil instalaci balíčku. Viz dokumentace npm ls a dokumentace npm explain.

Můžete také prozkoumat metadata registru pro kandidátskou verzi balíčku:

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

Příkaz npm view čte metadata balíčku z registru, což vám umožňuje porovnat, zda novější nebo starší vydání podporuje verzi hostitelského balíčku, kterou již používáte. Viz dokumentace npm view.

Mohu to opravit instalací kompatibilní verze balíčku?

Obvykle je toto nejlepší řešení. Najděte průnik mezi verzí hostitelského balíčku, kterou vaše aplikace potřebuje, a rozsahem peer dependencies podporovaným pluginem.

Předpokládejme, že váš projekt obsahuje:

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

Pokud novější vydání some-package deklaruje kompatibilitu s React 18, aktualizujte tento balíček:

npm install some-package@latest

Pokud vaše aplikace nepotřebuje React 18 a plugin je důležitý, může být bezpečnější opačná volba: nainstalujte verzi React, která skutečně splňuje deklarovaný rozsah peer dependencies pluginu.

Mám nejprve upravit package.json, nebo smazat node_modules?

Nejprve opravte rozhodnutí o verzi. Smazání node_modules nezmění nekompatibilní rozsah peer dependencies.

Jakmile package.json popisuje kompatibilní sadu přímých závislostí, spusťte normální instalaci, aby npm mohl aktualizovat soubor lockfile:

npm install

Pokud záměrně znovu budujete zastaralou lokální instalaci po opravě deklarací, odstranění node_modules může pomoci zajistit, že další instalace bude čistá. Ale mazání souborů bez změny nekompatibilních požadavků pouze žádá npm, aby znovu objevil stejný konflikt.

Stejně tak vymazání cache npm není běžným řešením pro sémantický konflikt peer dependencies. Zpráva ERESOLVE, která uvádí nekompatibilní rozsahy verzí, vám již říká, o jakou kategorii problému jde.

Kdy bych měl použít overrides v package.json?

Použijte overrides, když záměrně potřebujete změnit, na co se existující hrana závislosti vyhodnocuje, obvykle u transitivní závislosti. npm dokumentuje overrides jako mechanismus kořenového projektu pro nahrazení verzí závislostí, omezení transitivního balíčku nebo nahrazení forku.

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

Nepovažujte overrides za obecný příkaz pro deklaraci, že nekompatibilní smlouva peer dependencies je zázračně platná. Pokud je skutečným problémem to, že balíček třetí strany má nesprávná nebo příliš úzká metadata závislostí, ověřte, že je kód kompatibilní, a preferujte upstream opravené vydání, pokud je k dispozici.

Dokumentace npm 12 také popisuje packageExtensions, které mohou přidat nebo opravit metadata závislostí třetích stran – včetně rozsahů peer dependencies – z kořenového projektu, zatímco čekáte na upstream opravu. Toto je pokročilý nástroj, protože přebíráte odpovědnost za opravená metadata. Viz npm package.json: overrides a packageExtensions.

Měl bych použít --legacy-peer-deps?

Použijte ji pouze tehdy, když záměrně potřebujete dočasný únikový východ pro kompatibilitu.

npm install --legacy-peer-deps

npm dokumentuje legacy-peer-deps jako příznak, který způsobuje, že npm ignoruje peer dependencies při sestavování stromu balíčků, podobně jako chování npm 3 až npm 6. npm výslovně uvádí, že jeho použití není doporučeno, protože nevynucuje smlouvu peer dependencies, na kterou mohou balíčky spoléhat. Viz dokumentace konfigurace npm.

Tento příznak může být rozumný, když jste kombinaci nezávisle otestovali, jste blokováni příliš restriktivním upstream rozsahem peer dependencies a potřebujete krátkodobou cestu, zatímco balíček nahrazujete nebo aktualizujete. Je to špatná výchozí volba pro každou neúspěšnou instalaci.

Je --force totéž?

Ne. --force je širší a agresivnější.

npm install --force

npm uvádí, že force odstraňuje několik ochranných mechanismů a mimo jiné umožňuje instalaci konfliktních peer dependencies v kořenovém projektu. Dokumentace npm varuje před jeho použitím, pokud jasně nerozumíte důsledkům. Viz npm config: force.

Pokud je vaším jediným cílem dočasně obejít vynucování peer dependencies, --legacy-peer-deps je užší ve svém záměru. Žádný z těchto příznaků nedokazuje, že výsledná aplikace je kompatibilní.

Proč npm ci selže poté, co npm install fungoval?

Zkontrolujte, jak byl vytvořen soubor lockfile. npm dokumentuje, že npm ci provádí zmrazenou čistou instalaci: vyžaduje existující package-lock.json, odmítá jej aktualizovat a ukončí se, pokud soubor lockfile neodpovídá package.json.

Existuje další detail týkající se peer dependencies: pokud byl soubor lockfile vytvořen s příznakem pro tvarování stromu, jako je --legacy-peer-deps, npm uvádí, že byste měli předat stejné nastavení příkazu npm ci, jinak můžete narazit na chyby. npm navrhuje uložit nastavení do souboru .npmrc projektu, pokud je toto chování záměrnou součástí repozitáře:

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

Poté commitněte projektový .npmrc pouze tehdy, pokud je toto obejití záměrným týmovým rozhodnutím – ne proto, že jeden vývojář potřeboval jednorázový záchranný příkaz. Viz dokumentace npm ci.

Co když udržuji balíček, který deklaruje peer dependency?

Otestujte verze hostitelského balíčku, které skutečně podporujete, a poté deklarujte nejširší přesný rozsah. npm konkrétně varuje autory balíčků před zbytečně úzkými specifikacemi peer dependencies, protože zvyšují šanci, že jinak kompatibilní pluginy nelze nainstalovat současně.

Pokud plugin funguje napříč React 18.x, například rozsah, který zbytečně fixuje jednu patch verzi, ztěžuje život uživatelům. Na druhou stranu, rozšíření rozsahu bez testování pouze přenáší riziko z času instalace na čas běhu.

Praktická postupnost oprav

1. Přečtěte si výstup ERESOLVE a zapište si nalezenou verzi, konfliktní balíček a rozsah peer dependencies.
2. Spusťte npm ls <host-package> --all a npm explain <conflicting-package>.
3. Použijte npm view k porovnání požadavků peer dependencies dostupných verzí balíčků.
4. Vyberte kombinaci verzí, jejichž deklarované rozsahy se skutečně překrývají.
5. Aktualizujte package.json prostřednictvím npm install package@version nebo ekvivalentní záměrné úpravy následované npm install.
6. Použijte overrides nebo packageExtensions pouze tehdy, pokud transitivní závislost nebo metadata skutečně vyžadují zásah na úrovni projektu.
7. Použijte --legacy-peer-deps pouze jako zdokumentovanou dočasnou výjimku; vyhraďte --force pro případy, kdy plně rozumíte tomu, jakou ochranu vypínáte.

Jak ověřím, že je konflikt skutečně vyřešen?

Nezastavujte se, když npm install vrátí návratový kód 0. Ověřte strom závislostí a aplikaci.

npm ls
npm test
npm run build

Použijte skutečné testovací a build skripty projektu; ne každý repozitář definuje přesně výše uvedené příkazy. Pokud repozitář obsahuje soubor lockfile, otestujte také zmrazenou čistou instalaci:

npm ci

Silný výsledek má čtyři vlastnosti:

• npm install proběhne úspěšně bez konfliktu ERESOLVE.
• npm ls nehlásí příslušné balíčky jako neplatné nebo chybějící.
• Vaše testy a produkční build procházejí s vyřešenými verzemi.
• npm ci proběhne úspěšně v čistém prostředí s použitím commitnutého souboru lockfile a konfigurace projektu.

Pokud můžete splnit první podmínku pouze použitím --force, konflikt závislostí nebyl skutečně vyřešen – pouze jste npm instruovali, aby jej přijal. To může být vědomé krátkodobé rozhodnutí, ale mělo by být zaznamenáno jako technický dluh s jasně identifikovaným nekompatibilním balíčkem a zamýšlenou cestou nahrazení nebo aktualizace.