Kā novērst npm ERR! code ERESOLVE peer dependency konfliktu

Jūs palaižat npm install, sagaidāt, ka npm pievienos vienu pakotni, bet tā vietā saņemat izvades sienu, kas beidzas ar npm ERR! code ERESOLVE un “unable to resolve dependency tree.” Svarīgākais jautājums nav “Kā likt npm pārstāt sūdzēties?” Tas ir “Kuras divas versiju prasības nevar būt patiesas vienlaikus?”

Šī atšķirība nosaka, vai jūs nonāksit pie stabilas kļūdas novēršanas, vai tikai piespiessit npm instalēt atkarību koku, kuru viena no jūsu pakotnēm skaidri norāda, ka neatbalsta.

Piezīme par versiju: pārbaudīts 2026. gada 11. septembrī, npm dokumentācija apzīmē npm CLI 12.0.2 kā jaunāko dokumentācijas versiju. npm automātiski instalē peerDependencies pēc noklusējuma kopš npm 7, un konfliktējošas peer prasības var izraisīt instalācijas kļūmi, ja npm nevar izveidot derīgu koku. Skatiet npm package.json dokumentāciju.

Ko patiesībā nozīmē ERESOLVE?

Tiešā atbilde: npm atrada atkarību prasības, kuras nevar izpildīt vienlaikus pašreizējā atkarību kokā.

Peer dependency ir saderības līgums. Spraudnis vai pavadošā pakotne var deklarēt, ka tā sagaida, ka jūsu projekts nodrošinās citas pakotnes saderīgu versiju. Piemēram, spraudnis var deklarēt:

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

Ja jūsu projekts pieprasa React 18 un šis spraudnis deklarē saderību tikai ar React 17, npm ir pierādījumi, ka pieprasītā kombinācija var nebūt atbalstīta. Pakotne var nejauši darboties ar React 18, bet npm nevar pieņemt, ka pakotnes autors ir paredzējis šo saderību.

npm paša dokumentācija iesaka pakotņu autoriem saglabāt peer dependency diapazonus tik plašus, cik ļauj pārbaudītā saderība, jo pārāk šauri peer diapazoni var radīt konfliktus. Tas nenozīmē, ka lietotājiem vienkārši jāignorē katrs diapazons, kas tiem nepatīk.

Kura pakotne patiesībā izraisa konfliktu?

Izlasiet ERESOLVE atskaiti, pirms kaut ko maināt. Meklējiet divas daļas:

• Found: versija, kas jau ir atlasīta vai pieprasīta jūsu saknes projektā.
• Could not resolve dependency / peer: pakotne, kas pieprasa citu diapazonu.

Vienkāršotā piemērā npm varētu teikt, ka jūsu saknes projekts izmanto react@18.3.0, bet some-package@2.1.0 pieprasa react@^16.8.0 || ^17.0.0. Konflikts nav “npm pret React”. Tas ir nesaderība starp jūsu atlasīto React versiju un peer diapazonu, ko deklarē some-package.

Pirms rediģējat package.json, ierakstiet trīs vērtības: saimniekprogrammas pakotni, konfliktējošo pakotni un tās sagaidāmo peer diapazonu.

Vai man vispirms jāpārbauda atkarību koks?

Jā, īpaši, ja konfliktējošā pakotne nav tieša atkarība. npm nodrošina divas noderīgas komandas dažādiem koka skatiem.

npm ls react --all
npm explain some-package

npm ls izdrukā loģisko atkarību koku un var identificēt nederīgas vai trūkstošas pakotnes. npm explain, kas pieejams arī kā npm why, parāda atkarību ķēdi, kuras dēļ pakotne tika instalēta. Skatiet npm ls dokumentāciju un npm explain dokumentāciju.

Jūs varat arī pārbaudīt reģistra metadatus kandidāta pakotnes versijai:

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

Komanda npm view nolasīja pakotnes metadatus no reģistra, ļaujot salīdzināt, vai jaunāka vai vecāka izlaiduma versija atbalsta jau izmantoto saimniekprogrammas versiju. Skatiet npm view dokumentāciju.

Vai es varu to novērst, instalējot saderīgu pakotnes versiju?

Parasti tas ir labākais risinājums. Atrodiet šķērsgriezumu starp saimniekprogrammas versiju, kas nepieciešama jūsu lietojumprogrammai, un peer diapazonu, ko atbalsta spraudnis.

Pieņemsim, ka jūsu projektā ir:

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

Ja jaunāka some-package izlaiduma versija deklarē saderību ar React 18, atjauniniet šo pakotni:

npm install some-package@latest

Ja jūsu lietojumprogrammai nav nepieciešams React 18 un spraudnis ir svarīgs, pretējā izvēle var būt drošāka: instalējiet React versiju, kas patiešām atbilst spraudņa dokumentētajam peer diapazonam.

Pareizais virziens ir atkarīgs no jūsu lietojumprogrammas. Neautomātiski pazeminiet ietvara versiju tikai tāpēc, lai saglabātu pamestu spraudni, un neautomātiski paaugstiniet spraudni cauri galvenajai versijai, neizlasot tā migrācijas piezīmes.

Vai man vispirms jārediģē package.json vai jādzēš node_modules?

Vispirms izlemiet par versiju. node_modules dzēšana nemaina nesaderīgo peer diapazonu.

Kad package.json apraksta saderīgu tiešo atkarību kopu, palaidiet parasto instalāciju, lai npm varētu atjaunināt lockfailu:

npm install

Ja jūs apzināti pārbūvējat novecojušu lokālo instalāciju pēc deklarāciju labošanas, node_modules noņemšana var palīdzēt nodrošināt, ka nākamā instalācija ir tīra. Bet failu dzēšana, nemainot nesaderīgās prasības, vienkārši liek npm atkārtoti atklāt to pašu konfliktu.

Tāpat npm kešatmiņas attīrīšana nav parasts līdzeklis semantiskam peer dependency konfliktam. ERESOLVE atskaite, kurā nosaukti nesaderīgi versiju diapazoni, jau norāda, kāda veida problēma jums ir.

Kad man jāizmanto package.json overrides?

Izmantojiet overrides, kad jums apzināti jāmaina, uz ko atrisina esošā atkarības mala, parasti transīvai atkarībai. npm dokumentē overrides kā saknes projekta mehānismu atkarību versiju aizstāšanai, transīvas pakotnes ierobežošanai vai forka aizstāšanai.

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

Neklasificējiet overrides kā vispārīgu komandu, lai deklarētu, ka nesaderīgs peer līgums ir maģiski derīgs. Ja patiesā problēma ir tā, ka trešās puses pakotnei ir nepareizi vai pārāk šauri atkarību metadati, pārliecinieties, ka kods ir saderīgs, un, ja pieejams, dodiet priekšroku augšupējai labotajai izlaiduma versijai.

npm 12 dokumentācija apraksta arī packageExtensions, kas var pievienot vai labot trešās puses atkarību metadatus—including peer dependency diapazonus—no saknes projekta, gaidot augšupējo labojumu. Tas ir augsta līmeņa rīks, jo jūs uzņematies atbildību par labotajiem metadatiem. Skatiet npm package.json: overrides un packageExtensions.

Vai man jāizmanto --legacy-peer-deps?

Izmantojiet to tikai tad, kad apzināti nepieciešama pagaidu saderības izeja.

npm install --legacy-peer-deps

npm dokumentē legacy-peer-deps kā tādu, kas liek npm ignorēt peer dependencies, veidojot pakotņu koku, līdzīgi kā npm 3 līdz npm 6 uzvedība. npm skaidri norāda, ka tā lietošana nav ieteicama, jo tā nepiespiež peer dependency līgumu, uz kuru pakotnes var paļauties. Skatiet npm konfigurācijas dokumentāciju.

Šis karodziņš var būt pamatots, ja esat neatkarīgi pārbaudījis kombināciju, esat bloķēts ar pārāk ierobežojošu augšupēju peer diapazonu un jums nepieciešams īstermiņa ceļš, kamēr nomaināt vai atjaunināt pakotni. Tas ir slikts noklusējums katrai neveiksmīgai instalācijai.

Vai --force ir tas pats?

Nē. --force ir plašāks un agresīvāks.

npm install --force

npm norāda, ka force noņem vairākas aizsardzības un, cita starpā, ļauj instalēt konfliktējošas peer dependencies saknes projektā. npm dokumentācija brīdina nelietot to, ja jūs skaidri nesaprotat sekas. Skatiet npm config: force.

Ja jūsu vienīgais mērķis ir īslaicīgi apiet peer dependency piespiešanu, --legacy-peer-deps ir šaurāks pēc būtības. Neviens no karodziņiem nepierāda, ka iegūtā lietojumprogramma ir saderīga.

Kāpēc npm ci neizdodas pēc tam, kad npm install strādāja?

Pārbaudiet, kā tika izveidots lockfails. npm dokumentē, ka npm ci veic sasaldētu tīru instalāciju: tas pieprasa esošu package-lock.json, atsakās to atjaunināt un izbeidzas, ja lockfails neatbilst package.json.

Ir papildu peer-dependency detaļa: ja lockfails tika izveidots ar koka veidošanas karodziņu, piemēram, --legacy-peer-deps, npm saka, ka jums jānodod tā pati iestatījuma vērtība npm ci, vai arī jūs varat saskarties ar kļūdām. npm ierosina saglabāt iestatījumu projekta .npmrc, kad šī uzvedība ir apzināta daļa no repozitorija:

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

Tad izpildiet projekta .npmrc tikai tad, ja šis apbraukšanas risinājums ir apzināts komandas lēmums—nevis tāpēc, ka vienam izstrādātājam bija nepieciešama vienreizēja glābšanas komanda. Skatiet npm ci dokumentāciju.

Ko darīt, ja es uzturu pakotni, kas deklarē peer dependency?

Pārbaudiet saimniekprogrammas versijas, kuras patiešām atbalstāt, un pēc tam deklarējiet visplašāko precīzo diapazonu. npm īpaši brīdina pakotņu autorus pret nevajadzīgi šaurām peer dependency specifikācijām, jo tās palielina iespēju, ka citādi saderīgus spraudņus nevarēs instalēt kopā.

Ja spraudnis darbojas visās React 18.x versijās, piemēram, diapazons, kas nevajadzīgi piesien vienu ielāpa versiju, apgrūtina lietotāju dzīvi. No otras puses, diapazona paplašināšana bez testēšanas vienkārši pārceļ risku no instalācijas laika uz izpildes laiku.

Praktiska kļūdu novēršanas secība

1. Izlasiet ERESOLVE izvadi un pierakstiet atrasto versiju, konfliktējošo pakotni un peer diapazonu.
2. Palaidiet npm ls <host-package> --all un npm explain <conflicting-package>.
3. Izmantojiet npm view, lai salīdzinātu pieejamo pakotņu versiju peer prasības.
4. Izvēlieties versiju kombināciju, kuru deklarētie diapazoni patiešām pārklājas.
5. Atjauniniet package.json, izmantojot npm install package@version vai līdzvērtīgu apzinātu rediģēšanu, kam seko npm install.
6. Izmantojiet overrides vai packageExtensions tikai tad, ja transīvai atkarībai vai metadatiem tiešām ir nepieciešama projekta līmeņa iejaukšanās.
7. Izmantojiet --legacy-peer-deps tikai kā dokumentētu pagaidu izņēmumu; rezervējiet --force gadījumiem, kad jūs pilnībā saprotat, kādu aizsardzību atspējojat.

Kā es varu pārliecināties, ka konflikts ir patiešām novērsts?

Nepārtrauciet, kad npm install atgriež izejas kodu 0. Pārbaudiet atkarību koku un lietojumprogrammu.

npm ls
npm test
npm run build

Izmantojiet projekta faktiskos testu un būvēšanas skriptus; ne katrs repozitorijs definē tieši iepriekš minētās komandas. Ja repozitorijā ir lockfails, pārbaudiet arī sasaldētu tīru instalāciju:

npm ci

Spēcīgam rezultātam ir četras īpašības:

• npm install izdodas bez ERESOLVE konflikta.
• npm ls neziņo par attiecīgajām pakotnēm kā nederīgām vai trūkstošām.
• Jūsu testi un ražošanas būvēšana izdodas ar atrisinātajām versijām.
• npm ci izdodas tīrā vidē, izmantojot izpildīto lockfailu un projekta konfigurāciju.

Ja jūs varat izpildīt tikai pirmo nosacījumu, izmantojot --force, atkarību konflikts nav patiešām atrisināts—jūs esat pavēlējis npm to pieņemt. Tas var būt apzināts īstermiņa lēmums, bet tam jābūt reģistrētam kā tehniskajam parādam, skaidri norādot nesaderīgo pakotni un paredzēto nomaiņas vai atjaunināšanas ceļu.