Kaip išspręsti npm ERR! code ERESOLVE peer dependency konfliktą

Paleidžiate npm install, tikimės, kad npm pridės vieną paketą, bet vietoj to gaunate ištisą eilutę išvesties, besibaigiančią npm ERR! code ERESOLVE ir „unable to resolve dependency tree“. Svarbus klausimas nėra „Kaip priversti npm nustoti skųstis?“ Jis yra „Kurios dvi versijos reikalavimai negali būti tenkinami kartu?“

Šis skirtumas lemia, ar galiausiai turėsite stabilų pataisymą, ar tiesiog priversite npm įdiegti priklausomybių medį, kurio vienas iš jūsų paketų aiškiai nurodo nepalaikantis.

Pastaba apie versiją: patikrinta 2026 m. rugsėjo 11 d., npm dokumentacija žymi npm CLI 12.0.2 kaip naujausią dokumentacijos versiją. npm automatiškai įdiegia peerDependencies pagal numatytuosius nustatymus nuo npm 7 versijos, o konfliktuojantys peer reikalavimai gali sukelti diegimo nesėkmę, kai npm negali sukonstruoti galiojančio medžio. Žr. npm package.json dokumentaciją.

Ką iš tikrųjų reiškia ERESOLVE?

Tiesioginis atsakymas: npm rado priklausomybių reikalavimus, kurių negalima patenkinti kartu esant dabartiniam priklausomybių medžiui.

Peer dependency yra suderinamumo sutartis. Įskiepis ar palydovinis paketas gali deklaruoti, kad jis tikisi, jog jūsų projektas pateiks suderinamą kito paketo versiją. Pavyzdžiui, įskiepis gali deklaruoti:

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

Jei jūsų projektui reikia React 18, o tas įskiepis deklaruoja suderinamumą tik su React 17, npm turi įrodymų, kad prašoma kombinacija gali būti nepalaikoma. Paketas gali atsitiktinai veikti su React 18, bet npm negali daryti prielaidos, kad paketo autorius numatė tokį suderinamumą.

Npm dokumentacija pataria paketų autoriams laikyti peer dependency diapazonus tokiais plačiais, kiek leidžia jų išbandytas suderinamumas, nes per siauri peer diapazonai gali sukelti konfliktus. Tai nereiškia, kad vartotojai turėtų tiesiog ignoruoti visus diapazonus, kurie jiems nepatinka.

Kuris paketas iš tikrųjų sukelia konfliktą?

Prieš keisdami bet ką, perskaitykite ERESOLVE ataskaitą. Ieškokite dviejų dalių:

• Found: versija, kurią jau pasirinko arba prašo jūsų šakninis projektas.
• Could not resolve dependency / peer: paketas, kuris reikalauja kito diapazono.

Paprastintame pavyzdyje npm gali nurodyti, kad jūsų šakninis projektas naudoja react@18.3.0, o some-package@2.1.0 reikalauja react@^16.8.0 || ^17.0.0. Konfliktas nėra „npm prieš React“. Tai nesuderinamumas tarp jūsų pasirinktos React versijos ir some-package deklaruoto peer diapazono.

Prieš redaguodami package.json, užfiksuokite tris reikšmes: pagrindinį paketą, konfliktuojantį paketą ir jo tikėtiną peer diapazoną.

Ar man reikia pirmiausia patikrinti priklausomybių medį?

Taip, ypač kai konfliktuojantis paketas nėra tiesioginė priklausomybė. npm pateikia dvi naudingas komandas skirtingiems medžio vaizdams.

npm ls react --all
npm explain some-package

npm ls atspausdina loginį priklausomybių medį ir gali identifikuoti netinkamus arba trūkstamus paketus. npm explain, taip pat prieinama kaip npm why, rodo priklausomybių grandinę, dėl kurios paketas buvo įdiegtas. Žr. npm ls dokumentaciją ir npm explain dokumentaciją.

Taip pat galite patikrinti kandidato paketo versijos registro metaduomenis:

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

Komanda npm view skaito paketo metaduomenis iš registro, todėl galite palyginti, ar naujesnė, ar senesnė laida palaiko jau naudojamą pagrindinę versiją. Žr. npm view dokumentaciją.

Ar galiu tai ištaisyti įdiegdamas suderinamą paketo versiją?

Paprastai tai yra geriausias sprendimas. Raskite sankirtą tarp pagrindinės versijos, kurios reikia jūsų programai, ir peer diapazono, kurį palaiko įskiepis.

Tarkime, jūsų projekte yra:

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

Jei naujesnė some-package laida deklaruoja suderinamumą su React 18, atnaujinkite tą paketą:

npm install some-package@latest

Jei jūsų programai nereikia React 18, o įskiepis yra svarbus, priešingas pasirinkimas gali būti saugesnis: įdiekite React versiją, kuri iš tikrųjų atitinka dokumentuotą įskiepio peer diapazoną.

Teisinga kryptis priklauso nuo jūsų programos. Automatiškai neatnaujinkite žemyn frameworko tik tam, kad išlaikytumėte apleistą įskiepį, ir automatiškai neatnaujinkite įskiepio per pagrindinę versiją neperskaitę jo migracijos pastabų.

Ar pirmiausia turėčiau redaguoti package.json, ar ištrinti node_modules?

Pirmiausia išspręskite versijos sprendimą. node_modules ištrynimas nepakeičia nesuderinamo peer diapazono.

Kai package.json aprašo suderinamą tiesioginių priklausomybių rinkinį, paleiskite įprastą diegimą, kad npm galėtų atnaujinti lockfailą:

npm install

Jei sąmoningai perstatote atsilikusį vietinį diegimą po deklaracijų pataisymo, node_modules pašalinimas gali padėti užtikrinti, kad kitas diegimas būtų švarus. Tačiau failų trynimas nekeičiant nesuderinamų reikalavimų tiesiog prašo npm iš naujo atrasti tą patį konfliktą.

Taip pat npm talpyklos valymas nėra įprasta semantinio peer dependency konflikto priemonė. ERESOLVE ataskaita, kurioje įvardijami nesuderinami versijų diapazonai, jau sako, kokios kategorijos problemą turite.

Kada turėčiau naudoti package.json overrides?

Naudokite overrides, kai sąmoningai norite pakeisti tai, į ką išsprendžia esama priklausomybės briauna, paprastai dėl netiesioginės priklausomybės. npm dokumentuoja overrides kaip šakninio projekto mechanizmą priklausomybių versijoms pakeisti, netiesioginiam paketui apriboti arba šakutei pakeisti.

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

Nelaikykite overrides bendros komandos deklaruoti, kad nesuderinama peer sutartis yra stebuklingai galiojanti. Jei tikroji problema yra ta, kad trečiosios šalies paketas turi neteisingus arba per siaurus priklausomybių metaduomenis, patikrinkite, ar kodas yra suderinamas, ir, jei įmanoma, pirmenybę teikite iš anksto pataisytai laidai.

Npm 12 dokumentacija taip pat aprašo packageExtensions, kuris gali pridėti arba pataisyti trečiosios šalies priklausomybių metaduomenis, įskaitant peer dependency diapazonus, iš šakninio projekto, kol laukiama išankstinio pataisymo. Tai pažangus įrankis, nes prisiimate atsakomybę už pataisytus metaduomenis. Žr. npm package.json: overrides ir packageExtensions.

Ar turėčiau naudoti --legacy-peer-deps?

Naudokite jį tik tada, kai sąmoningai reikia laikino suderinamumo išėjimo.

npm install --legacy-peer-deps

npm dokumentuoja legacy-peer-deps kaip priverčiantį npm ignoruoti peer dependencies kuriant paketo medį, panašiai kaip npm 3–6 elgsena. npm aiškiai teigia, kad jo naudojimas nerekomenduojamas, nes jis nevykdo peer dependency sutarties, kuria gali remtis paketai. Žr. npm konfigūracijos dokumentaciją.

Ši vėliava gali būti pagrįsta, kai nepriklausomai išbandėte kombinaciją, esate užblokuotas per griežto išankstinio peer diapazono ir jums reikia trumpalaikio kelio, kol pakeisite arba atnaujinsite paketą. Tai prastas numatytasis variantas kiekvienam nesėkmingam diegimui.

Ar --force yra tas pats?

Ne. --force yra platesnis ir agresyvesnis.

npm install --force

npm teigia, kad force pašalina keletą apsaugų ir, be kitų poveikių, leidžia įdiegti konfliktuojančias peer dependencies šakniniame projekte. npm dokumentacija įspėja nenaudoti jo, jei aiškiai nesuprantate pasekmės. Žr. npm config: force.

Jei vienintelis tikslas yra laikinai apeiti peer dependency vykdymą, --legacy-peer-deps yra siauresnis pagal intenciją. Nei viena vėliava neįrodo, kad galutinė programa yra suderinama.

Kodėl npm ci nepavyksta po to, kai npm install pavyko?

Patikrinkite, kaip buvo sukurtas lockfailas. npm dokumentuoja, kad npm ci atlieka užšaldytą švarų diegimą: jam reikia esamo package-lock.json, jis atsisako jį atnaujinti ir baigia darbą, jei lockfailas neatitinka package.json.

Yra papildoma peer-dependency detalė: jei lockfailas buvo sukurtas su medžio formavimo vėliava, tokia kaip --legacy-peer-deps, npm teigia, kad turėtumėte perduoti tą patį nustatymą npm ci, arba galite susidurti su klaidomis. npm siūlo saugoti nustatymą projekto .npmrc, kai toks elgesys yra sąmoninga dalis repo:

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

Tada fiksuokite projekto .npmrc tik jei tas apėjimas yra sąmoningas komandos sprendimas, o ne todėl, kad vienam kūrėjui reikėjo vienkartinės gelbėjimo komandos. Žr. npm ci dokumentaciją.

Ką daryti, jei palaikau paketą, kuris deklaruoja peer dependency?

Išbandykite pagrindines versijas, kurias iš tikrųjų palaikote, tada deklaruokite plačiausią tikslią diapazoną. npm konkrečiai įspėja paketų autorius dėl nereikalingai siaurų peer dependency specifikacijų, nes jos padidina tikimybę, kad kitaip suderinami įskiepiai negalės būti įdiegti kartu.

Jei įskiepis veikia per React 18.x, pavyzdžiui, diapazonas, kuris nereikalingai fiksuoją vieną pataisos versiją, apsunkina vartotojų gyvenimą. Kita vertus, diapazono platinimas be bandymo tiesiog perkelia riziką nuo diegimo laiko iki vykdymo laiko.

Praktinė remonto seka

1. Perskaitykite ERESOLVE išvestį ir užsirašykite rastą versiją, konfliktuojantį paketą ir peer diapazoną.
2. Paleiskite npm ls <host-package> --all ir npm explain <conflicting-package>.
3. Naudokite npm view, kad palygintumėte prieinamų paketo versijų peer reikalavimus.
4. Pasirinkite versijų kombinaciją, kurios deklaruoti diapazonai iš tikrųjų persidengia.
5. Atnaujinkite package.json per npm install package@version arba atitinkamą sąmoningą redagavimą, po kurio seka npm install.
6. Naudokite overrides arba packageExtensions tik tada, kai netiesioginė priklausomybė arba metaduomenys iš tikrųjų reikalauja projekto lygmens intervencijos.
7. Naudokite --legacy-peer-deps tik kaip dokumentuotą laikiną išimtį; rezervuokite --force atvejams, kai visiškai suprantate, kokią apsaugą išjungiate.

Kaip patikrinti, ar konfliktas iš tikrųjų išspręstas?

Nesustokite, kai npm install grąžina išėjimo kodą 0. Patikrinkite priklausomybių medį ir programą.

npm ls
npm test
npm run build

Naudokite faktinius projekto testų ir kūrimo skriptus; ne kiekvienas repo apibrėžia tikslias aukščiau pateiktas komandas. Jei repo turi lockfailą, taip pat išbandykite užšaldytą švarų diegimą:

npm ci

Stiprus rezultatas turi keturias savybes:

• npm install pavyksta be ERESOLVE konflikto.
• npm ls nepraneša apie atitinkamus paketus kaip netinkamus arba trūkstamus.
• Jūsų testai ir gamybos kūrimas pavyksta su išspręstomis versijomis.
• npm ci pavyksta švarioje aplinkoje naudojant fiksuotą lockfailą ir projekto konfigūraciją.

Jei galite patenkinti tik pirmąją sąlygą naudodami --force, priklausomybių konfliktas nėra iš tikrųjų išspręstas – jūs nurodėte npm jį priimti. Tai gali būti sąmoningas trumpalaikis sprendimas, tačiau tai turėtų būti užfiksuota kaip techninė skola, aiškiai nurodant nesuderinamą paketą ir numatytą pakeitimo arba atnaujinimo kelią.