Miten korjata npm ERR! code ERESOLVE -vertaisriippuvuusriski

Suoritat komennon npm install, odotat npm:n lisäävän yhden paketin, mutta saatkin tulosteen, joka päättyy virheeseen npm ERR! code ERESOLVE ja viestiin “unable to resolve dependency tree”. Tärkeä kysymys ei ole “Miten saan npm:n lopettamaan valituksen?”, vaan “Mitkä kaksi versiovaatimusta eivät voi toteutua yhtä aikaa?”

Tämä ero ratkaisee, päädytkö vakaaseen korjaukseen vai pakotatko npm:n asentamaan riippuvuuspuun, jota jokin paketeistasi nimenomaisesti sanoo ei tukevansa.

Versiotieto: Tarkistettu 11. syyskuuta 2026. npm-dokumentaatio merkitsee npm CLI:n version 12.0.2 uusimmaksi dokumentaatioversioksi. npm on asentanut peerDependencies-riippuvuudet oletuksena automaattisesti npm 7:stä lähtien, ja ristiriitaiset vertaisriippuvuusvaatimukset voivat aiheuttaa asennuksen epäonnistumisen, kun npm ei pysty rakentamaan kelvollista puuta. Katso npm package.json -dokumentaatio.

Mitä ERESOLVE oikeasti tarkoittaa?

Suora vastaus: npm löysi riippuvuusvaatimuksia, joita ei voida täyttää yhtä aikaa nykyisessä riippuvuuspuussa.

Vertaisriippuvuus on yhteensopivuussopimus. Lisäosa tai kumppanipaketti voi ilmoittaa odottavansa projektin tarjoavan yhteensopivan version toisesta paketista. Esimerkiksi lisäosa voi ilmoittaa:

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

Jos projektisi vaatii React 18:aa ja kyseinen lisäosa ilmoittaa tukevansa vain React 17:ää, npm:llä on näyttöä siitä, että pyydetty yhdistelmä voi olla tukematon. Paketti saattaa sattumalta toimia React 18:n kanssa, mutta npm ei voi olettaa paketin tekijän tarkoittaneen tätä yhteensopivuutta.

npm:n oma dokumentaatio neuvoo pakettien tekijöitä pitämään vertaisriippuvuusvälit niin leveinä kuin testattu yhteensopivuus sallii, koska liian kapeat vertaisvälit voivat aiheuttaa ristiriitoja. Tämä ei tarkoita, että käyttäjien tulisi yksinkertaisesti sivuuttaa kaikki väli, joista eivät pidä.

Mikä paketti oikeasti aiheuttaa ristiriidan?

Lue ERESOLVE-raportti ennen minkään muuttamista. Etsi kaksi osaa:

• Found: versio, joka on jo valittu tai jota juuriprojektisi pyytää.
• Could not resolve dependency / peer: paketti, joka vaatii eri välin.

Yksinkertaistetussa esimerkissä npm saattaa ilmoittaa, että juuriprojektisi käyttää versiota react@18.3.0, kun taas some-package@2.1.0 vaatii välin react@^16.8.0 || ^17.0.0. Ristiriita ei ole “npm vastaan React”, vaan se on yhteensopimattomuus valitsemasi React-version ja paketin some-package ilmoittaman vertaisvälin välillä.

Tallenna kolme arvoa ennen kuin muokkaat tiedostoa package.json: isäntäpaketti, ristiriitainen paketti ja sen odottama vertaisväli.

Tarvitseeko riippuvuuspuuta tarkastella ensin?

Kyllä, erityisesti kun ristiriitainen paketti ei ole suora riippuvuus. npm tarjoaa kaksi hyödyllistä komentoa eri näkymille puusta.

npm ls react --all
npm explain some-package

npm ls tulostaa loogisen riippuvuuspuun ja voi tunnistaa virheelliset tai puuttuvat paketit. npm explain, joka on saatavilla myös nimellä npm why, näyttää riippuvuusketjun, joka aiheutti paketin asentumisen. Katso npm ls -dokumentaatio ja npm explain -dokumentaatio.

Voit myös tarkastella rekisterin metadataa ehdokkaana olevalle paketille:

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

npm view -komento lukee paketin metadataa rekisteristä, mikä mahdollistaa vertailun siitä, tukeeko uudempi tai vanhempi julkaisu jo käyttämääsi isäntäversiota. Katso npm view -dokumentaatio.

Voinko korjata tämän asentamalla yhteensopivan paketin version?

Yleensä tämä on paras korjaus. Etsi leikkauskohta sovelluksesi tarvitseman isäntäversion ja lisäosan tukeman vertaisvälin välillä.

Oletetaan, että projektissasi on:

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

Jos uudempi some-package-julkaisu ilmoittaa tukevansa React 18:aa, päivitä kyseinen paketti:

npm install some-package@latest

Jos sovelluksesi ei tarvitse React 18:aa ja lisäosa on tärkeä, päinvastainen valinta voi olla turvallisempi: asenna React-versio, joka todella täyttää lisäosan dokumentoidun vertaisvälin.

Oikea suunta riippuu sovelluksestasi. Älä automaattisesti alenna kehysversiota vain hylätyn lisäosan säilyttämiseksi, äläkä automaattisesti päivitä lisäosaa pääversion yli lukematta sen migraatiohuomioita.

Pitääkö muokata package.json-tiedostoa ensin vai poistaa node_modules ensin?

Korjaa versiovalinta ensin. node_modules-kansion poistaminen ei muuta yhteensopimatonta vertaisväliä.

Kun package.json kuvaa yhteensopivan joukon suoria riippuvuuksia, suorita normaali asennus, jotta npm voi päivittää lukitustiedoston:

npm install

Jos rakennat tarkoituksellisesti vanhentuneen paikallisen asennuksen uudelleen ilmoitusten korjaamisen jälkeen, node_modules-kansion poistaminen voi varmistaa, että seuraava asennus on puhdas. Mutta tiedostojen poistaminen muuttamatta yhteensopimattomia vaatimuksia pyytää vain npm:tä löytämään saman ristiriidan uudelleen.

Samoin npm:n välimuistin tyhjentäminen ei ole normaali korjaus semanttiseen vertaisriippuvuusriskiin. ERESOLVE-raportti, jossa nimetään yhteensopimattomat versiovälit, kertoo jo, minkä tyyppisestä ongelmasta on kyse.

Milloin minun tulisi käyttää package.json overrides-asetusta?

Käytä overrides-asetusta, kun tarvitset tarkoituksellisesti muuttaa sitä, mihin olemassa oleva riippuvuusside ratkeaa, yleensä transitiiviselle riippuvuudelle. npm dokumentoi overrides-asetuksen juuriprojektin mekanismiksi riippuvuusversioiden korvaamiselle, transitiivisen paketin rajoittamiselle tai haarautetun version korvaamiselle.

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

Älä käsittele overrides-asetusta yleiskäyttöisenä komentona ilmoittaa, että yhteensopimaton vertaissopimus on taianomaisesti kelvollinen. Jos todellinen ongelma on se, että kolmannen osapuolen paketilla on virheelliset tai liian kapeat riippuvuusmetadata, varmista, että koodi on yhteensopiva, ja suosii ylävirran korjattua julkaisua, kun sellainen on saatavilla.

npm 12 -dokumentaatio kuvaa myös packageExtensions-asetusta, joka voi lisätä tai korjata kolmannen osapuolen riippuvuusmetadataa – mukaan lukien vertaisriippuvuusvälit – juuriprojektista käsin odotettaessa ylävirran korjausta. Tämä on edistynyt työkalu, koska otat vastuun korjatusta metadatasta. Katso npm package.json: overrides ja packageExtensions.

Pitääkö minun käyttää --legacy-peer-deps-asetusta?

Käytä sitä vain, kun tarvitset tietoisesti tilapäisen yhteensopivuuden pakoreitin.

npm install --legacy-peer-deps

npm dokumentoi legacy-peer-deps-asetuksen aiheuttavan sen, että npm sivuuttaa vertaisriippuvuudet rakentaessaan pakettipuu, vastaavasti kuin npm 3:n ja npm 6:n käyttäytyminen. npm sanoo nimenomaisesti, että sen käyttöä ei suositella, koska se ei pakota vertaisriippuvuussopimusta, johon paketit voivat luottaa. Katso npm-asetusten dokumentaatio.

Tämä lippu voi olla järkevä, kun olet itsenäisesti testannut yhdistelmän, olet estetty liian rajoittavan ylävirran vertaisvälin vuoksi ja tarvitset lyhyen aikavälin polun paketin korvaamiseen tai päivittämiseen. Se on huono oletusarvo jokaiselle epäonnistuneelle asennukselle.

Onko --force sama asia?

Ei. --force on laajempi ja aggressiivisempi.

npm install --force

npm ilmoittaa, että force poistaa useita suojauksia ja muun muassa sallii ristiriitaisten vertaisriippuvuuksien asentamisen juuriprojektiin. npm:n dokumentaatio varoittaa käyttämästä sitä, kun et selvästi ymmärrä seurauksia. Katso npm config: force.

Jos ainoana tavoitteenasi on ohittaa vertaisriippuvuuksien pakotus tilapäisesti, --legacy-peer-deps on tarkoitukseltaan kapeampi. Kumpikaan lippu ei todista, että tuloksena oleva sovellus on yhteensopiva.

Miksi npm ci epäonnistuu, kun npm install onnistui?

Tarkista, miten lukitustiedosto luotiin. npm dokumentoi, että npm ci suorittaa jäädytetyn puhtaan asennuksen: se vaatii olemassa olevan package-lock.json-tiedoston, kieltäytyy päivittämästä sitä ja lopettaa, jos lukitustiedosto ei vastaa package.json-tiedostoa.

On olemassa ylimääräinen vertaisriippuvuustieto: jos lukitustiedosto luotiin puun muokkauslipulla, kuten --legacy-peer-deps, npm sanoo, että sinun tulisi siirtää sama asetus npm ci:lle, tai saatat kohdata virheitä. npm ehdottaa asetuksen tallentamista projektin .npmrc-tiedostoon, kun tämä käyttäytyminen on tarkoituksellisesti osa repositoriota:

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

Commitoi projektin .npmrc vain, jos tämä ohitus on tietoinen tiimipäätös – ei siksi, että yksi kehittäjä tarvitsi kertaluonteisen pelastuskomennon. Katso npm ci -dokumentaatio.

Mitä jos ylläpidän pakettia, joka ilmoittaa vertaisriippuvuuden?

Testaa isäntäversiot, joita todella tuet, ja ilmoita sitten levein tarkka väli. npm varoittaa nimenomaisesti pakettien tekijöitä tarpeettoman kapeista vertaisriippuvuusmäärityksistä, koska ne lisäävät todennäköisyyttä, ettei muuten yhteensopivia lisäosia voida asentaa yhtä aikaa.

Jos lisäosa toimii React 18.x:n yli, esimerkiksi väli, joka turhaan kiinnittää yhden korjausversion, vaikeuttaa käyttäjien elämää. Toisaalta välin levennittäminen testaamatta siirtää riskin asennusajasta suoritusajalle.

Käytännön korjaussekvenssi

1. Lue ERESOLVE-tuloste ja kirjoita ylös löydetty versio, ristiriitainen paketti ja vertaisväli.
2. Suorita npm ls <host-package> --all ja npm explain <conflicting-package>.
3. Käytä npm view -komentoa vertaamaan saatavilla olevien paketiversioiden vertaisvaatimuksia.
4. Valitse versioyhdistelmä, jonka ilmoitetut välit todella leikkaavat.
5. Päivitä package.json käyttämällä npm install package@version tai vastaavaa tarkoituksellista muokkausta, jota seuraa npm install.
6. Käytä overrides tai packageExtensions vain, kun transitiivinen riippuvuus tai metadata todella vaatii projektin tason väliintulon.
7. Käytä --legacy-peer-deps vain dokumentoituna tilapäisenä poikkeuksena; säilytä --force tapauksiin, joissa ymmärrät täysin, mitä suojaa poistat käytöstä.

Miten varmistan, että ristiriita on todella korjattu?

Älä lopeta, kun npm install palauttaa poistumiskoodin 0. Varmista riippuvuuspuu ja sovellus.

npm ls
npm test
npm run build

Käytä projektin todellisia testaus- ja build-skriptejä; ei jokainen repositorio määrittele yllä olevia tarkkoja komentoja. Jos repositoriossa on lukitustiedosto, testaa myös jäädytetty puhdas asennus:

npm ci

Vahva tulos sisältää neljä ominaisuutta:

• npm install onnistuu ilman ERESOLVE-ristiriitaa.
• npm ls ei ilmoita relevantteja paketteja virheellisiksi tai puuttuviksi.
• Testisi ja tuotantobuildisi menevät läpi ratkaistuilla versioilla.
• npm ci onnistuu puhtaassa ympäristössä käyttäen commitoitua lukitustiedostoa ja projektin konfiguraatiota.

Jos voit täyttää vain ensimmäisen ehdon käyttämällä --force, riippuvuusriskiä ei ole todellisuudessa ratkaistu – olet ohjeistanut npm:n hyväksymään sen. Se voi olla tietoinen lyhyen aikavälin päätös, mutta se tulisi kirjata tekniseksi velaksi, jossa yhteensopimaton paketti ja suunniteltu korvaus- tai päivityspolku on selvästi tunnistettu.