Как да поправите npm ERR! code ERESOLVE конфликт на peer зависимости

Стартирате npm install, очаквате npm да добави един пакет, но вместо това получавате стена от изходен текст, завършващ с npm ERR! code ERESOLVE и „unable to resolve dependency tree“. Важният въпрос не е „Как да накарам npm да спре да се оплаква?“. Той е „Кои две изисквания за версия не могат да бъдат изпълнени едновременно?“

Тази разлика определя дали ще стигнете до стабилно решение, или просто ще принудите npm да инсталира дърво от зависимости, което един от вашите пакети изрично заявява, че не поддържа.

Забележка за версията: към 11 септември 2026 г. документацията на npm маркира npm CLI 12.0.2 като последната версия на документацията. npm автоматично инсталира peerDependencies по подразбиране от npm 7 насам, а конфликтни peer изисквания могат да доведат до неуспех при инсталацията, когато npm не може да конструира валидно дърво. Вижте документацията за npm package.json.

Какво всъщност означава ERESOLVE?

Директен отговор: npm е открил изисквания за зависимости, които не могат да бъдат удовлетворени заедно в текущото дърво от зависимости.

Peer зависимостта е договор за съвместимост. Един плъгин или придружаващ пакет може да декларира, че очаква вашият проект да осигури съвместима версия на друг пакет. Например, един плъгин може да декларира:

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

Ако вашият проект изисква React 18, а този плъгин декларира съвместимост само с React 17, npm има доказателство, че поисканата комбинация може да не се поддържа. Пакетът може да работи случайно с React 18, но npm не може да предполага, че авторът на пакета е предвидил тази съвместимост.

Собствената документация на npm съветва авторите на пакети да поддържат диапазоните на peer зависимостите толкова широки, колкото позволява тестваната им съвместимост, тъй като прекалено тесните peer диапазони могат да създадат конфликти. Това не означава, че потребителите трябва просто да игнорират всеки диапазон, който не им харесва.

Кой пакет всъщност причинява конфликта?

Прочетете отчета ERESOLVE, преди да промените каквото и да е. Търсете две части:

• Found: версията, която вече е избрана или изискана от кореновия ви проект.
• Could not resolve dependency / peer: пакетът, който изисква различен диапазон.

В опростен пример npm може да каже, че кореновият ви проект използва react@18.3.0, докато some-package@2.1.0 изисква react@^16.8.0 || ^17.0.0. Конфликтът не е „npm срещу React“. Той е несъвместимостта между избраната от вас версия на React и peer диапазона, деклариран от some-package.

Запишете три стойности, преди да редактирате package.json: хост пакета, конфликтния пакет и peer диапазона, който той очаква.

Трябва ли да инспектирам дървото от зависимости първо?

Да, особено когато конфликтният пакет не е директна зависимост. npm предоставя две полезни команди за различни изгледи на дървото.

npm ls react --all
npm explain some-package

npm ls извежда логическото дърво от зависимости и може да идентифицира невалидни или липсващи пакети. npm explain, достъпен и като npm why, показва веригата от зависимости, която е довела до инсталирането на пакет. Вижте документацията за npm ls и документацията за npm explain.

Можете също да инспектирате метаданните на регистъра за кандидатна версия на пакета:

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

Командата npm view чете метаданните на пакета от регистъра, което ви позволява да сравните дали по-нова или по-стара версия поддържа версията на хоста, която вече използвате. Вижте документацията за npm view.

Мога ли да го поправя, като инсталирам съвместима версия на пакета?

Обикновено това е най-доброто решение. Намерете сечение между версията на хоста, от която се нуждае вашето приложение, и peer диапазона, поддържан от плъгина.

Да предположим, че вашият проект съдържа:

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

Ако по-ново издание на some-package декларира съвместимост с React 18, актуализирайте този пакет:

npm install some-package@latest

Ако вашето приложение не се нуждае от React 18 и плъгинът е важен, обратният избор може да е по-безопасен: инсталирайте версия на React, която всъщност удовлетворява документирания peer диапазон на плъгина.

Правилната посока зависи от вашето приложение. Не автоматично деградирайте рамка само за да запазите изоставен плъгин, и не автоматично надграждайте плъгин през основна версия, без да прочетете бележките за миграция.

Трябва ли да редактирам package.json първо или да изтрия node_modules първо?

Поправете решението за версията първо. Изтриването на node_modules не променя несъвместимия peer диапазон.

След като package.json описва съвместим набор от директни зависимости, стартирайте нормална инсталация, за да може npm да актуализира lockfile-а:

npm install

Ако съзнателно преизграждате остаряла локална инсталация след поправяне на декларациите, премахването на node_modules може да помогне да се гарантира, че следващата инсталация е чиста. Но изтриването на файлове без промяна на несъвместимите изисквания просто моли npm да открие отново същия конфликт.

По същия начин, изчистването на кеша на npm не е нормално средство за семантичен конфликт на peer зависимости. Отчетът ERESOLVE, който посочва несъвместими диапазони на версии, вече ви казва какъв вид проблем имате.

Кога трябва да използвам overrides в package.json?

Използвайте overrides, когато съзнателно трябва да промените към какво се разрешава съществуващ ръб на зависимост, обикновено за транзитивна зависимост. npm документира overrides като механизъм на кореновия проект за заместване на версии на зависимости, ограничаване на транзитивен пакет или заместване с форк.

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

Не третирайте overrides като обща команда за деклариране, че несъвместим peer договор е магически валиден. Ако истинският проблем е, че пакет на трета страна има неправилни или прекалено тесни метаданни за зависимости, проверете дали кодът е съвместим и предпочетете коригирано издание нагоре по веригата, когато е налично.

Документацията на npm 12 описва и packageExtensions, която може да добави или коригира метаданните за зависимости на трети страни – включително диапазони на peer зависимости – от кореновия проект, докато чакате корекция нагоре по веригата. Това е разширен инструмент, защото поемате отговорност за коригираните метаданни. Вижте npm package.json: overrides и packageExtensions.

Трябва ли да използвам --legacy-peer-deps?

Използвайте го само когато съзнателно имате нужда от временен изход за съвместимост.

npm install --legacy-peer-deps

npm документира legacy-peer-deps като причиняващ npm да игнорира peer зависимостите при изграждането на дървото от пакети, подобно на поведението от npm 3 до npm 6. npm изрично казва, че използването му е непрепоръчително, защото не налага договора за peer зависимости, на който пакетите може да разчитат. Вижте документацията за конфигурация на npm.

Този флаг може да е разумен, когато сте тествали независимо комбинацията, блокирани сте от прекалено ограничителен upstream peer диапазон и имате нужда от краткосрочен път, докато замените или актуализирате пакета. Той е лош вариант по подразбиране за всяка неуспешна инсталация.

Дали --force е същото нещо?

Не. --force е по-широк и по-агресивен.

npm install --force

npm посочва, че force премахва няколко предпазни мерки и, между други ефекти, позволява конфликтни peer зависимости да бъдат инсталирани в кореновия проект. Документацията на npm предупреждава срещу използването му, когато не разбирате ясно последиците. Вижте npm config: force.

Ако единствената ви цел е временно да заобиколите налагането на peer зависимости, --legacy-peer-deps е по-тесен по намерение. Нито един от двата флага не доказва, че полученото приложение е съвместимо.

Защо npm ci се проваля, след като npm install е работил?

Проверете как е създаден lockfile-ът. npm документира, че npm ci извършва замразена чиста инсталация: той изисква съществуващ package-lock.json, отказва да го актуализира и излиза, ако lockfile-ът не съвпада с package.json.

Има допълнителен детайл за peer зависимостите: ако lockfile-ът е създаден с флаг за оформяне на дървото, като --legacy-peer-deps, npm казва, че трябва да предадете същата настройка на npm ci, или може да срещнете грешки. npm предлага да съхраните настройката в .npmrc на проекта, когато това поведение е съзнателна част от хранилището:

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

След това комитнете проектния .npmrc само ако това заобикаляне е съзнателно екипно решение – не защото един разработчик е имал нужда от еднократна спасителна команда. Вижте документацията за npm ci.

Какво ако поддържам пакета, който декларира peer зависимостта?

Тествайте версиите на хоста, които всъщност поддържате, след което декларирайте най-широкия точен диапазон. npm специфично предупреждава авторите на пакети срещу ненужно тесни спецификации на peer зависимости, защото те увеличават шанса иначе съвместими плъгини да не могат да бъдат инсталирани заедно.

Ако един плъгин работи в рамките на React 18.x, например, диапазон, който ненужно фиксира една коригираща версия, затруднява живота на потребителите. От друга страна, разширяването на диапазон без тестване просто прехвърля риска от времето на инсталация към времето на изпълнение.

Практическа последователност за ремонт

1. Прочетете изхода ERESOLVE и запишете намерената версия, конфликтния пакет и peer диапазона.
2. Стартирайте npm ls <host-package> --all и npm explain <conflicting-package>.
3. Използвайте npm view, за да сравните peer изискванията на наличните версии на пакета.
4. Изберете комбинация от версии, чиито декларирани диапазони всъщност се припокриват.
5. Актуализирайте package.json чрез npm install package@version или еквивалентно съзнателно редактиране, последвано от npm install.
6. Използвайте overrides или packageExtensions само когато транзитивната зависимост или метаданните наистина изискват намеса на ниво проект.
7. Използвайте --legacy-peer-deps само като документирано временно изключение; запазете --force за случаи, в които напълно разбирате каква предпазна мярка деактивирате.

Как да проверя, че конфликтът наистина е поправен?

Не спирайте, когато npm install върне изходен код 0. Проверете дървото от зависимости и приложението.

npm ls
npm test
npm run build

Използвайте действителните скриптове за тест и изграждане на проекта; не всяко хранилище дефинира точните горни команди. Ако хранилището има lockfile, тествайте и замразена чиста инсталация:

npm ci

Силен резултат има четири свойства:

• npm install успява без конфликт ERESOLVE.
• npm ls не докладва съответните пакети като невалидни или липсващи.
>Вашите тестове и производственото изграждане преминават с разрешените версии.
• npm ci успява в чиста среда, използвайки комитнатия lockfile и конфигурацията на проекта.

Ако можете да удовлетворите само първото условие, като използвате --force, конфликтът на зависимости не е наистина разрешен – вие сте инструктирали npm да го приеме. Това може да е съзнателно краткосрочно решение, но трябва да бъде записано като технически дълг с ясно идентифицирани несъвместимия пакет и предвидения път за замяна или надграждане.