Як виправити помилку npm ERR! code ERESOLVE: конфлікт залежностей-партнерів

Ви запускаєте npm install, очікуєте, що npm додасть один пакет, але натомість отримуєте стіну виводу, що закінчується повідомленням npm ERR! code ERESOLVE та «unable to resolve dependency tree». Важливе питання не в тому, «як змусити npm перестати скаржитися?». Воно полягає в тому, «які дві вимоги до версій не можуть бути виконані одночасно?»

Це розрізнення визначає, чи отримаєте ви стабільне виправлення, чи просто змусите npm встановити дерево залежностей, підтримку якого один із ваших пакетів явно заперечує.

Примітка про версію: станом на 11 вересня 2026 року документація npm позначає CLI npm 12.0.2 як останню версію документації. npm автоматично встановлює peerDependencies за замовчуванням починаючи з npm 7, і конфліктні вимоги до залежностей-партнерів можуть призвести до збою встановлення, коли npm не може побудувати валідне дерево. Див. документацію npm package.json.

Що насправді означає ERESOLVE?

Пряма відповідь: npm знайшов вимоги до залежностей, які не можуть бути задоволені одночасно в межах поточного дерева залежностей.

Залежність-партнер (peer dependency) — це контракт сумісності. Плагін або супутній пакет може оголосити, що очікує від вашого проєкту надання сумісної версії іншого пакета. Наприклад, плагін може оголосити:

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

Якщо ваш проєкт вимагає React 18, а цей плагін оголошує сумісність лише з React 17, npm має докази того, що запитана комбінація може не підтримуватися. Пакет може випадково працювати з React 18, але npm не може припускати, що автор пакета мав на увазі таку сумісність.

Власна документація npm радить авторам пакетів зберігати діапазони залежностей-партнерів настільки широкими, наскільки це дозволяє протестована сумісність, оскільки надто вузькі діапазони можуть створювати конфлікти. Це не означає, що споживачі повинні просто ігнорувати кожен діапазон, який їм не подобається.

Який пакет насправді спричиняє конфлікт?

Прочитайте звіт 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 та діапазоном залежностей-партнерів, оголошеним some-package.

Запишіть три значення перед тим, як редагувати package.json: хост-пакет, конфліктний пакет та діапазон залежностей-партнерів, який він очікує.

Чи потрібно спочатку перевіряти дерево залежностей?

Так, особливо коли конфліктний пакет не є прямою залежністю. 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.

Чи можна виправити це, встановивши сумісну версію пакета?

Зазвичай це найкраще виправлення. Знайдіть перетин між версією хоста, яка потрібна вашому додатку, та діапазоном залежностей-партнерів, який підтримується плагіном.

Припустимо, ваш проєкт містить:

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

Якщо новіший реліз some-package оголошує сумісність з React 18, оновіть цей пакет:

npm install some-package@latest

Якщо вашому додатку не потрібен React 18, а плагін важливий, протилежний вибір може бути безпечнішим: встановіть версію React, яка фактично задовольняє задокументований діапазон залежностей-партнерів плагіна.

Правильний напрямок залежить від вашого додатку. Не автоматично знижуйте версію фреймворку лише для збереження покинутого плагіна і не автоматично оновлюйте плагін через мажорну версію, не прочитавши його нотатки щодо міграції.

Чи потрібно спочатку редагувати package.json, чи спочатку видаляти node_modules?

Спочатку виправте рішення щодо версії. Видалення node_modules не змінює несумісний діапазон залежностей-партнерів.

Як тільки package.json описує сумісний набір прямих залежностей, запустіть звичайне встановлення, щоб npm міг оновити lockfile:

npm install

Якщо ви свідомо перебудовуєте застарілу локальну інсталяцію після виправлення оголошень, видалення node_modules може допомогти забезпечити чисте наступне встановлення. Але видалення файлів без зміни несумісних вимог просто змушує npm знову виявити той самий конфлікт.

Так само очищення кешу npm не є звичайним засобом для семантичного конфлікту залежностей-партнерів. Звіт ERESOLVE, який називає несумісні діапазони версій, вже повідомляє вам, до якої категорії належить ваша проблема.

Коли слід використовувати overrides у package.json?

Використовуйте overrides, коли вам навмисно потрібно змінити, на що розв’язується існуюче ребро залежності, зазвичай для транзитивної залежності. npm документує overrides як механізм кореневого проєкту для заміни версій залежностей, обмеження транзитивного пакета або заміни форку.

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

Не розглядайте overrides як загальну команду для оголошення, що несумісний контракт залежностей-партнерів магічним чином є валідним. Якщо справжня проблема полягає в тому, що сторонній пакет має некоректні або надто вузькі метадані залежностей, переконайтеся, що код сумісний, і віддавайте перевагу виправленому релізу від розробника, коли він доступний.

Документація npm 12 також описує packageExtensions, який може додавати або виправляти метадані залежностей сторонніх пакетів, включаючи діапазони залежностей-партнерів, з кореневого проєкту, поки очікується виправлення від розробника. Це просунутий інструмент, оскільки ви берете на себе відповідальність за виправлені метадані. Див. npm package.json: overrides та packageExtensions.

Чи слід використовувати --legacy-peer-deps?

Використовуйте його лише тоді, коли вам свідомо потрібен тимчасовий вихід для сумісності.

npm install --legacy-peer-deps

npm документує legacy-peer-deps як параметр, що змушує npm ігнорувати залежності-партнери під час побудови дерева пакетів, подібно до поведінки npm 3 через npm 6. npm явно зазначає, що його використання не рекомендується, оскільки він не забезпечує дотримання контракту залежностей-партнерів, на який можуть покладатися пакети. Див. документацію конфігурації npm.

Цей прапорець може бути розумним, коли ви незалежно протестували комбінацію, заблоковані надто обмежувальним діапазоном залежностей-партнерів від розробника і потребуєте короткострокового шляху, поки замінюєте або оновлюєте пакет. Це поганий варіант за замовчуванням для кожної невдалої інсталяції.

Чи --force це те саме?

Ні. --force є ширшим і більш агресивним.

npm install --force

npm стверджує, що force видаляє кілька захистів і, серед інших ефектів, дозволяє встановлювати конфліктні залежності-партнери в кореневому проєкті. Документація npm попереджає проти використання, коли ви чітко не розумієте наслідків. Див. npm config: force.

Якщо ваша єдина мета — тимчасово обійти забезпечення залежностей-партнерів, --legacy-peer-deps є вужчим за наміром. Жоден із цих прапорців не доводить, що отриманий додаток є сумісним.

Чому npm ci не вдається після успішного npm install?

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

Є додаткова деталь щодо залежностей-партнерів: якщо lockfile було створено з прапорцем формування дерева, таким як --legacy-peer-deps, npm каже, що ви повинні передати той самий параметр до npm ci, інакше можуть виникнути помилки. npm пропонує зберігати цей параметр у .npmrc проєкту, коли така поведінка є навмисною частиною репозиторію:

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

Потім комітьте .npmrc проєкту лише якщо цей обхід є свідомим командним рішенням, а не тому, що одному розробнику потрібна була разова рятувальна команда. Див. документацію npm ci.

Що робити, якщо я підтримую пакет, який оголошує залежність-партнера?

Протестуйте версії хоста, які ви фактично підтримуєте, а потім оголосіть найширший точний діапазон. npm спеціально попереджає авторів пакетів проти надмірно вузьких специфікацій залежностей-партнерів, оскільки вони збільшують ймовірність того, що інакше сумісні плагіни не зможуть бути встановлені разом.

Якщо плагін працює з React 18.x, наприклад, діапазон, який надмірно прив’язує одну патч-версію, ускладнює життя споживачам. З іншого боку, розширення діапазону без тестування просто переносить ризик з часу встановлення на час виконання.

Практична послідовність виправлення

1. Прочитайте вивід ERESOLVE і запишіть знайдену версію, конфліктний пакет та діапазон залежностей-партнерів.
2. Запустіть npm ls <host-package> --all та npm explain <conflicting-package>.
3. Використовуйте npm view для порівняння вимог до залежностей-партнерів доступних версій пакетів.
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 прийняти його. Це може бути свідомим короткостроковим рішенням, але його слід записати як технічний борг із чітко визначеним несумісним пакетом та запланованим шляхом заміни або оновлення.