Hogyan javítsd meg az npm ERR! code ERESOLVE peer dependency ütközést

Futtatod az npm install parancsot, azt várod, hogy az npm hozzáad egy csomagot, ehelyett pedig egy kimeneti falat kapsz, amely az npm ERR! code ERESOLVE és az „unable to resolve dependency tree” üzenettel végződik. A fontos kérdés nem az, hogy „Hogyan állítsam meg az npm panaszkodását?”, hanem az, hogy „Melyik két verziókövetelmény nem teljesülhet egyszerre?”

Ez a különbség határozza meg, hogy stabil megoldást kapsz-e, vagy csupán arra kényszeríted az npm-et, hogy egy olyan függőségi fát telepítsen, amelyet az egyik csomagod kifejezetten nem támogat.

Verzió megjegyzés: 2026. szeptember 11-i ellenőrzéskor az npm dokumentációja az npm CLI 12.0.2 verzióját jelöli meg a legfrissebb dokumentációs verzióként. Az npm az npm 7 óta alapértelmezetten automatikusan telepíti a peerDependencies elemeket, és az ütköző peer követelmények telepítési hibát okozhatnak, amikor az npm nem tud érvényes fát felépíteni. Lásd: npm package.json dokumentáció.

Mit jelent valójában az ERESOLVE?

Közvetlen válasz: Az npm olyan függőségi követelményeket talált, amelyek a jelenlegi függőségi fa mellett nem teljesíthetők egyszerre.

Egy peer dependency (társszerzői függőség) egy kompatibilitási szerződés. Egy plugin vagy kísérő csomag deklarálhatja, hogy a projektnek kompatibilis verziót kell biztosítania egy másik csomagból. Például egy plugin deklarálhatja:

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

Ha a projekt React 18-at igényel, és az a plugin csak a React 17 kompatibilitását deklarálja, az npm bizonyítékot lát arra, hogy a kért kombináció nem támogatott lehet. A csomag előfordulhat, hogy működik React 18-cal, de az npm nem feltételezheti, hogy a csomag szerzője ezt a kompatibilitást szándékozta.

Az npm saját dokumentációja azt tanácsolja a csomagszerzőknek, hogy tartsák a peer dependency tartományokat olyan szélesre, amennyire a tesztelt kompatibilitásuk lehetővé teszi, mert a túl szűk peer tartományok ütközéseket okozhatnak. Ez nem jelenti azt, hogy a felhasználóknak egyszerűen figyelmen kívül kell hagyniuk minden olyan tartományt, amely nem tetszik nekik.

Melyik csomag okozza valójában az ütközést?

Olvassd el az ERESOLVE jelentést, mielőtt bármit megváltoztatnál. Keress két részt:

• Found: a már kiválasztott vagy a gyökérprojekt által kért verzió.
• Could not resolve dependency / peer: az a csomag, amely eltérő tartományt igényel.

Egy egyszerűsített példában az npm azt mondhatja, hogy a gyökérprojekt react@18.3.0 verziót használ, míg a some-package@2.1.0 a react@^16.8.0 || ^17.0.0 verziót igényli. Az ütközés nem „npm versus React”. Az ütközés a kiválasztott React verzió és a some-package által deklarált peer tartomány közötti inkompatibilitás.

Jegyezz fel három értéket, mielőtt szerkesztenéd a package.json fájlt: a gazda csomagot, az ütköző csomagot, és a várt peer tartományt.

Meg kell vizsgálnom a függőségi fát először?

Igen, különösen akkor, ha az ütköző csomag nem közvetlen függőség. Az npm két hasznos parancsot biztosít a fa különböző nézeteihez.

npm ls react --all
npm explain some-package

Az npm ls kiírja a logikai függőségi fát, és azonosíthatja az érvénytelen vagy hiányzó csomagokat. Az npm explain, amely npm why néven is elérhető, megmutatja azt a függőségi láncot, amely miatt egy csomag telepítésre került. Lásd: npm ls dokumentáció és npm explain dokumentáció.

Megvizsgálhatod a jelölt csomagverzió registry metaadatait is:

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

Az npm view parancs a csomag metaadatait olvassa ki a registryből, ami lehetővé teszi, hogy összehasonlítsd, egy újabb vagy régebbi kiadás támogatja-e a már használt gazda verziót. Lásd: npm view dokumentáció.

Megjavíthatom egy kompatibilis csomagverzió telepítésével?

Általában ez a legjobb megoldás. Keress egy metszetet az alkalmazásod által igényelt gazda verzió és a plugin által támogatott peer tartomány között.

Tegyük fel, hogy a projekt tartalmazza:

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

Ha egy újabb some-package kiadás deklarálja a kompatibilitást a React 18-cal, frissítsd azt a csomagot:

npm install some-package@latest

Ha az alkalmazásodnak nem kell a React 18, és a plugin fontos, az ellentétes választás lehet biztonságosabb: telepíts egy olyan React verziót, amely valóban kielégíti a plugin dokumentált peer tartományát.

A helyes irány az alkalmazásodtól függ. Ne automatikusan lefokozz egy keretrendszert csak azért, hogy megőrizz egy elhagyott plugint, és ne automatikusan frissíts egy plugint egy főverziós ugrással anélkül, hogy elolvasnád a migrációs jegyzeteit.

Először a package.json-t szerkesszem, vagy először töröljem a node_modules-t?

Először javítsd meg a verzió döntést. A node_modules törlése nem változtat egy inkompatibilis peer tartományon.

Amint a package.json egy kompatibilis készletet ír le a közvetlen függőségekről, futtass egy normál telepítést, hogy az npm frissíthesse a lockfájlt:

npm install

Ha szándékosan újjáépítesz egy elavult helyi telepítést a deklarációk javítása után, a node_modules eltávolítása segíthet biztosítani, hogy a következő telepítés tiszta legyen. De a fájlok törlése az inkompatibilis követelmények megváltoztatása nélkül egyszerűen arra kéri az npm-et, hogy fedezze fel újra ugyanazt az ütközést.

Hasonlóképpen, az npm gyorsítótárának törlése nem normál orvosság egy szemantikai peer dependency ütközésre. Egy ERESOLVE jelentés, amely inkompatibilis verziótartományokat nevez meg, már elmondja, milyen kategóriájú problémád van.

Mikor kell használnom a package.json overrides opciót?

Használd az overrides opciót, amikor szándékosan meg kell változtatnod, hogy egy meglévő függőségi él mire oldódik fel, általában egy átmeneti függőség esetén. Az npm dokumentációja az overrides opciót egy gyökérprojekt mechanizmusként írja le a függőségverziók helyettesítésére, egy átmeneti csomag korlátozására, vagy egy fork behelyettesítésére.

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

Ne kezeld az overrides opciót általános parancsként annak kijelentésére, hogy egy inkompatibilis peer szerződés varázslatosan érvényes. Ha a tényleges probléma az, hogy egy harmadik féltől származó csomag hibás vagy túl szűk függőségi metaadatokkal rendelkezik, ellenőrizd, hogy a kód kompatibilis-e, és részesítsd előnyben a javított upstream kiadást, ha elérhető.

Az npm 12 dokumentációja leírja a packageExtensions opciót is, amely hozzáadhat vagy javíthat harmadik féltől származó függőségi metaadatokat – beleértve a peer dependency tartományokat – a gyökérprojektből, amíg egy upstream javításra vársz. Ez egy haladó eszköz, mert a javított metaadatokért te vállalsz felelősséget. Lásd: npm package.json: overrides és packageExtensions.

Használjam a --legacy-peer-deps kapcsolót?

Csak akkor használd, amikor tudatosan szükséged van egy ideiglenes kompatibilitási menekülési útvonalra.

npm install --legacy-peer-deps

Az npm dokumentációja a legacy-peer-deps opciót úgy írja le, hogy az arra kényszeríti az npm-et, hogy figyelmen kívül hagyja a peer dependencyket a csomagfa felépítésekor, hasonlóan az npm 3 és npm 6 viselkedéséhez. Az npm kifejezetten azt mondja, hogy a használata nem ajánlott, mert nem kényszeríti ki azt a peer dependency szerződést, amelyre a csomagok támaszkodhatnak. Lásd: npm konfigurációs dokumentáció.

Ez a kapcsoló indokolt lehet, amikor függetlenül tesztelted a kombinációt, egy túl szigorú upstream peer tartomány blokkol, és rövid távú útvonalra van szükséged, amíg lecseréled vagy frissíted a csomagot. Rossz alapértelmezés minden sikertelen telepítéshez.

Ugyanaz a --force?

Nem. A --force szélesebb körű és agresszívebb.

npm install --force

Az npm azt állítja, hogy a force eltávolít több védelmet, és többek között lehetővé teszi az ütköző peer dependencyk telepítését a gyökérprojektben. Az npm dokumentációja figyelmeztet a használat ellen, amikor nem érted egyértelműen a következményeket. Lásd: npm config: force.

Ha az egyetlen célod a peer dependency kikényszerítésének ideiglenes megkerülése, a --legacy-peer-deps szándéka szűkebb. Egyik kapcsoló sem bizonyítja, hogy az eredményül kapott alkalmazás kompatibilis.

Miért sikertelen az npm ci, miután az npm install működött?

Ellenőrizd, hogyan készült a lockfájl. Az npm dokumentációja szerint az npm ci egy fagyasztott tiszta telepítést hajt végre: megkövetel egy meglévő package-lock.json fájlt, megtagadja a frissítését, és kilép, ha a lockfájl nem egyezik a package.json fájllal.

Van egy további peer-dependency részlet: ha a lockfájlt egy fa-alakító kapcsolóval, például --legacy-peer-deps készítették, az npm azt mondja, hogy ugyanazt a beállítást kell átadnod az npm ci parancsnak, vagy hibákba ütközhetsz. Az npm azt javasolja, hogy tárold a beállítást a projekt .npmrc fájljában, ha ez a viselkedés szándékos része a repónak:

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

Azután csak akkor kötelezd el a projekt .npmrc fájlját, ha ez a megkerülés egy szándékos csapatdöntés – nem azért, mert egy fejlesztőnek egy egyszeri mentőparancsra volt szüksége. Lásd: npm ci dokumentáció.

Mi van, ha én karbantartom azt a csomagot, amely deklarálja a peer dependencyt?

Teszteld le a ténylegesen támogatott gazda verziókat, majd deklaráld a legszélesebb pontos tartományt. Az npm kifejezetten figyelmezteti a csomagszerzőket a szükségtelenül szűk peer dependency specifikációk ellen, mert ezek növelik annak esélyét, hogy egyébként kompatibilis pluginok nem telepíthetők együtt.

Ha egy plugin működik a React 18.x verziókkal, például, egy tartomány, amely szükségtelenül rögzít egy javítási verziót, megnehezíti a felhasználók életét. Másrészt egy tartomány szélesítése tesztelés nélkül egyszerűen átviszi a kockázatot a telepítési időről a futásidejű időre.

Egy gyakorlati javítási sorrend

1. Olvassd el az ERESOLVE kimenetet, és írd le a talált verziót, az ütköző csomagot és a peer tartományt.
2. Futtasd az npm ls <host-package> --all és az npm explain <conflicting-package> parancsokat.
3. Használd az npm view parancsot az elérhető csomagverziók peer követelményeinek összehasonlításához.
4. Válassz egy olyan verzió kombinációt, amelynek deklarált tartományai valóban átfedik egymást.
5. Frissítsd a package.json fájlt az npm install package@version paranccsal vagy egy egyenértékű szándékos szerkesztéssel, amelyet npm install követ.
6. Használd az overrides vagy packageExtensions opciót csak akkor, ha az átmeneti függőség vagy a metaadatok valóban projekt szintű beavatkozást igényelnek.
7. Használd a --legacy-peer-deps kapcsolót csak dokumentált ideiglenes kivételként; tartsd fenn a --force kapcsolót olyan esetekre, amikor teljesen érted, milyen védelmet tiltasz le.

Hogyan ellenőrizhetem, hogy az ütközés valóban megjavult?

Ne állj meg, amikor az npm install 0 kilépési kódot ad vissza. Ellenőrizd a függőségi fát és az alkalmazást.

npm ls
npm test
npm run build

Használd a projekt tényleges teszt és build szkriptjeit; nem minden repo definiálja a fenti pontos parancsokat. Ha a repónak van lockfájlja, teszteld a fagyasztott tiszta telepítést is:

npm ci

Egy erős eredménynek négy tulajdonsága van:

• Az npm install ERESOLVE ütközés nélkül sikerül.
• Az npm ls nem jelenti a releváns csomagokat érvénytelennek vagy hiányzónak.
• A tesztjeid és a produkciós build sikeresek a feloldott verziókkal.
• Az npm ci sikerül egy tiszta környezetben a kötelezett lockfájl és projekt konfiguráció használatával.

Ha csak az első feltételt tudod kielégíteni a --force használatával, a függőségi ütközés nem lett valóban megoldva – arra utasítottad az npm-et, hogy fogadja el. Ez lehet egy tudatos rövid távú döntés, de technikai adósságként kell rögzíteni, egyértelműen azonosítva az inkompatibilis csomagot és a szándékolt csere- vagy frissítési útvonalat.