Hvernig á að laga npm ERR! code ERESOLVE Peer Dependency Conflict

Þú keyrir npm install, búist við að npm bæti við einum pakka, og í staðinn færðu vegg af úttaki sem endar á npm ERR! code ERESOLVE og “unable to resolve dependency tree.” Mikilvægasta spurningin er ekki “Hvernig fæ ég npm til að hætta að kvarta?” Heldur er hún “Hverjar eru tvær útgáfukröfur sem geta ekki báðar verið sannar?”

Þessi greinarmunur ákvarðar hvort þú endir með stöðuga lausn eða bara neyðir npm til að setja upp dependency tree sem einn af pökkunum þínum segir skýrt að hann styðji ekki.

Útgáfuathugasemd: eins og staðfest var þann 11. september 2026, merkir npm skjölunin npm CLI 12.0.2 sem nýjustu skjölunarútgáfu. npm hefur sjálfkrafa sett upp peerDependencies sjálfgefið síðan npm 7, og mótsagnakenndar peer kröfur geta valdið því að uppsetning mistekist þegar npm getur ekki byggt upp gilt tree. Sjá npm package.json skjölun.

Hvað þýðir ERESOLVE í raun?

Beint svar: npm fann dependency kröfur sem ekki er hægt að uppfylla saman undir núverandi dependency tree.

Peer dependency er samhæfnissamningur. Viðbót eða fylgipakki getur lýst yfir að hann geri ráð fyrir að verkefnið þitt veiti samhæfða útgáfu af öðrum pakka. Til dæmis gæti viðbót lýst yfir:

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

Ef verkefnið þitt krefst React 18 og viðbótin lýsir yfir aðeins samhæfni við React 17, hefur npm sönnunargögn um að umbeðin samsetning gæti verið óstudd. Pakkinn gæti tilviljunarkennt virkað með React 18, en npm getur ekki gert ráð fyrir að höfundur pakkans hafi ætlast til þessarar samhæfni.

Eigin skjölun npm ráðleggur pakka höfundum að halda peer dependency bilum eins víðum og prófuð samhæfni leyfir, því of þröng peer bil geta skapað mótsagnir. Það þýðir ekki að neytendur ættu einfaldlega að hunsa öll bil sem þeim líkar ekki við.

Hvaða pakki veldur í raun mótsögninni?

Lestu ERESOLVE skýrsluna áður en þú breytir einhverju. Leitaðu að tveimur hlutum:

• Found: útgáfan sem er þegar valin eða óskað eftir af rót verkefnisins þíns.
• Could not resolve dependency / peer: pakkin sem krefst annars bils.

Í einfölduðu dæmi gæti npm sagt að rót verkefnisins þíns noti react@18.3.0, en some-package@2.1.0 krefst react@^16.8.0 || ^17.0.0. Mótsögnin er ekki “npm gegn React.” Hún er ósamhæfnin milli valinnar React útgáfu þinnar og peer bilsins sem some-package lýsir yfir.

Skráðu þrjú gildi áður en þú breytir package.json: hýsingarpakkann, mótsagnakennda pakkann, og peer bilið sem hann gerir ráð fyrir.

Þarf ég að skoða dependency tree-ið fyrst?

Já, sérstaklega þegar mótsagnakenndi pakkin er ekki bein dependency. npm veitir tvö gagnleg skipanir fyrir mismunandi sýn á tree-ið.

npm ls react --all
npm explain some-package

npm ls prentar upp logulega dependency tree-ið og getur auðkennt ógilda eða vantar pakkana. npm explain, einnig í boði sem npm why, sýnir keðju dependencies sem olli því að pakki var settur upp. Sjá npm ls skjölun og npm explain skjölun.

Þú getur einnig skoðað registry metadata fyrir tiltekna pakkaútgáfu:

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

npm view skipunin lesur pakka metadata frá registry, sem gerir þér kleift að bera saman hvort nýrri eða eldri útgáfa styðji hýsingarútgáfuna sem þú notar nú þegar. Sjá npm view skjölun.

Get ég lagað þetta með því að setja upp samhæfða pakkaútgáfu?

Yfirleitt er þetta besta lagfæringin. Finndu skurðpunkt milli hýsingarútgáfunnar sem forritið þitt þarf og peer bilsins sem viðbótin styður.

Gerum ráð fyrir að verkefnið þitt innihaldi:

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

Ef nýrri some-package útgáfa lýsir yfir samhæfni við React 18, uppfærðu þann pakka:

npm install some-package@latest

Ef forritið þitt þarf ekki React 18 og viðbótin er mikilvæg, gæti öfug valkostur verið öruggari: settu upp React útgáfu sem raunverulega uppfyllir skjalfest peer bil viðbótarinnar.

Retta áttin fer eftir forritinu þínu. Ekki niðurfæra ramma (framework) sjálfkrafa bara til að viðhalda yfirgefinni viðbót, og ekki uppfæra viðbót sjálfkrafa yfir stóra útgáfu (major version) án þess að lesa migration notes hennar.

Ætti ég að breyta package.json fyrst eða eyða node_modules fyrst?

Lagaðu útgáfuákvörðunina fyrst. Að eyða node_modules breytir ekki ósamhæfðu peer bili.

Þegar package.json lýsir samhæfðum setti af beinum dependencies, keyrðu venjulega uppsetningu svo npm geti uppfært lockfile-ið:

npm install

Ef þú ert meðvitað að endurbyggja gömul staðbundin uppsetning eftir að hafa lagað lýsingarnar, getur fjarlæging node_modules hjálpað til við að tryggja að næsta uppsetning sé hrein. En að eyða skrám án þess að breyta ósamhæfðum kröfum er einfaldlega að biðja npm um að uppgötva sömu mótsögn aftur.

Eins er að hreinsa npm cache ekki venjuleg lyf við semantic peer dependency mótsögn. ERESOLVE skýrsla sem nefnir ósamhæfð útgáfubil er nú þegar að segja þér hvaða tegund vandamáls þú ert með.

Hvenær ætti ég að nota package.json overrides?

Notaðu overrides þegar þú þarft meðvitað að breyta því hvað núverandi dependency edge leysir í, yfirleitt fyrir transitive dependency. npm skjalleggur overrides sem rót-verkefni vélbúnað til að skipta um dependency útgáfur, takmarka transitive pakka, eða skipta út fork.

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

Ekki meðhöndla overrides sem almenna skipun til að lýsa yfir að ósamhæfður peer samningur sé töfrandi gildur. Ef raunverulega vandamálið er að þriðja aðila pakki hafi rangar eða of þröngar dependency metadata, staðfestu að kóðinn sé samhæfður og forgangsraða upstream fixed release þegar í boði.

npm 12 skjölunin lýsa einnig packageExtensions, sem getur bætt við eða leiðrétt þriðja aðila dependency metadata—including peer dependency bil—frá rót verkefnisins á meðan beðið er eftir upstream lagfæringu. Þetta er háþróaður verkfæri vegna þess að þú tekur á þig ábyrgð á leiðréttu metadata. Sjá npm package.json: overrides og packageExtensions.

Ætti ég að nota --legacy-peer-deps?

Notaðu það aðeins þegar þú þarft meðvitað tímabundna samhæfnis flóttaleið.

npm install --legacy-peer-deps

npm skjalleggur legacy-peer-deps sem að valda því að npm hunsa peer dependencies við byggingu package tree, svipað og npm 3 til npm 6 hegðun. npm segir skýrt að notkun þess sé ekki ráðlagt vegna þess að það framfylgir ekki peer dependency samningnum sem pakkar geta treyst á. Sjá npm configuration skjölun.

Þetta flag getur verið sanngjarnt þegar þú hefur prófað samsetninguna sjálfstætt, ert hindraður af of takmarkandi upstream peer bili, og þarft stutt tíma leið á meðan þú skiptir um eða uppfærir pakkann. Það er slæmt sjálfgefið fyrir hverja mistekna uppsetningu.

Er --force það sama?

Nei. --force er víðtækara og árásargjarnara.

npm install --force

npm segir að force fjarlægi nokkrar verndir og, meðal annarra áhrifa, leyfi mótsagnakenndum peer dependencies að vera sett upp í rót verkefnisins. npm skjölunin vara við notkun þess þegar þú skilur ekki afleiðinguna skýrt. Sjá npm config: force.

Ef eina markmiðið þitt er að hjálfra peer dependency framfylgd tímabundið, er --legacy-peer-deps þrengri í tilgangi. Hvorki flagið sannar að niðurstaðan forritið sé samhæft.

Hvers vegna mistekst npm ci eftir að npm install virkaði?

Athugaðu hvernig lockfile-ið var búið til. npm skjalleggur að npm ci framkvæmi frosna hreina uppsetningu: það krefst til staðar package-lock.json, neitar að uppfæra það, og hættir ef lockfile-ið passar ekki við package.json.

Það er viðbótar peer-dependency smáatriði: ef lockfile-ið var búið til með tree-shaping flag eins og --legacy-peer-deps, segir npm að þú eigir að senda sömu stillingu til npm ci eða þú gætir rekist á villur. npm mælir með því að geyma stillinguna í .npmrc verkefnisins þegar sú hegðun er meðvitað hluti af repository:

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

Commitaðu síðan verkefnis .npmrc aðeins ef sú bypass er meðvitað teymisákvörðun—ekki vegna þess að einn þróunaraðili þurfti einhliða björgunarskipun. Sjá npm ci skjölun.

Hvað ef ég viðhelt pakkanum sem lýsir yfir peer dependency?

Prófaðu hýsingarútgáfurnar sem þú styður í raun, og lýstu síðan yfir víðasta nákvæma bilið. npm varar sérstaklega pakka höfunda við óþarfi þröngum peer dependency tilgreiningum vegna þess að þær auka líkurnar á að annars samhæfðar viðbætur geti ekki verið settar upp saman.

Ef viðbót virkar yfir React 18.x, til dæmis, gerir bil sem óþarfi festir eina patch útgáfu lífið erfiðara fyrir neytendur. Á hinn bóginn, að víkka bil án prófunar flytur einfaldlega áhættuna frá uppsetningartíma til keyrslutíma.

Praktísk lagfæringarröð

1. Lestu ERESOLVE úttakið og skrifaðu niður fundna útgáfu, mótsagnakenndan pakka, og peer bil.
2. Keyrðu npm ls <host-package> --all og npm explain <conflicting-package>.
3. Notaðu npm view til að bera saman peer kröfur tiltækra pakkaútgáfa.
4. Veldu útgáfusamsetningu þar sem lýst bil skarast í raun.
5. Uppfærðu package.json í gegnum npm install package@version eða jafngilda meðvitaða breytingu fylgt eftir með npm install.
6. Notaðu overrides eða packageExtensions aðeins þegar transitive dependency eða metadata krefst raunverulegra verkefnis-stigs inngripa.
7. Notaðu --legacy-peer-deps aðeins sem skjalfesta tímabundna undantekningu; geymdu --force fyrir tilfellum þar sem þú skilur fullkomlega hvaða vernd þú ert að slökkva á.

Hvernig staðfesti ég að mótsögnin sé í raun leyst?

Ekki stoppa þegar npm install skilar exit code 0. Staðfestu dependency tree-ið og forritið.

npm ls
npm test
npm run build

Notaðu raunveruleg test og build scripts verkefnisins; ekki hvert repository skilgreinir nákvæmlega ofangreindar skipanir. Ef repository-ið hefur lockfile, prófaðu frosna hreina uppsetningu líka:

npm ci

Sterk niðurstaða hefur fjóra eiginleika:

• npm install tekst án ERESOLVE mótsagnar.
• npm ls tilkynnir ekki viðkomandi pakka sem ógilda eða vantar.
• Prófanir þínar og production build ganga upp með leystu útgáfum.
• npm ci tekst í hrein umhverfi með því að nota committed lockfile og verkefnis stillingar.

Ef þú getur aðeins uppfyllt fyrsta skilyrðið með því að nota --force, hefur dependency mótsögnin ekki í raun verið leyst—þú hefur skipað npm að samþykkja hana. Það gæti verið meðvitað stutt tíma ákvörðun, en hún ætti að vera skráð sem technical debt með ósamhæfða pakkanum og ætluðum skipti eða uppfærsluleið skýrt auðkenndum.