npm: peer dependency conflict — когда использовать --legacy-peer-deps

#Что означает ошибка

Ошибка ERESOLVE unable to resolve dependency tree / peer dependency conflict возникает с npm 7+: пакет требует версию зависимости, которая конфликтует с уже установленной. npm теперь не устанавливает пакеты, нарушающие peer-зависимости, как раньше.

Есть быстрый обход и правильное решение.

Обход подходит для разработки, но может скрыть несовместимость.

Конфликт peer-зависимостей возникает при несовместимых версиях. Предпочтительно привести версии к совместимым; флаг --legacy-peer-deps — временный обход.

#Причины и решения

#Пошаговое решение

1. Прочитайте, какие версии конфликтуютВ каталоге проекта откройте терминал и выполните npm install (или исходную команду), найдите в отчёте ERESOLVE строки Found: и Could not resolve dependency:. Выпишите название и версию основного пакета и диапазон peerDependencies, который требует зависимость; например, библиотека может требовать React 18, а проект использует React 19. Сохраните package.json и package-lock.json в системе контроля версий. Ошибка может появиться после обновления npm, когда выявилась существовавшая несовместимость.
2. Временно используйте --legacy-peer-depsПараметр --legacy-peer-deps рассматривайте только как временный обход при тестировании, если надо понять, работает ли прежняя сборка. Он заставляет npm игнорировать требования peer-зависимостей и может привести к ошибкам выполнения. На экспериментальной ветке можно выполнить npm install --legacy-peer-deps, затем обязательно прогнать сборку и тесты; не применяйте его автоматически в промышленной сборке и не добавляйте в постоянный .npmrc без согласования. Для npm ci важна совместимость флагов с теми, с которыми создавался lock-файл.
3. Обновите конфликтующие пакетыНайдите реальные совместимые версии: выполните npm view ИМЯ_ПАКЕТА peerDependencies --json и npm ls ИМЯ_ОСНОВНОГО_ПАКЕТА, заменив обе заглушки. Сверьте их с требованиями в package.json, документацией и поддерживаемой версией Node. Затем точечно обновите нужный пакет или понизьте основную зависимость до поддерживаемого релиза; делайте это на отдельной ветке, проверяя изменения package-lock.json. Не запускайте массовое npm update ради одного конфликта.
4. Добавьте overrides в package.jsonПоле overrides в package.json применяется к определённым вложенным зависимостям, но оно не отменяет реальные требования совместимости peerDependencies. Добавляйте overrides только при точно установленном несовместимом вложенном пакете и когда исправленная версия подтверждена тестами. Не прописывайте принудительную версию React или другого основного пакета вслепую: разные части проекта могут требовать разный API. После изменения выполните штатную чистую установку согласно проектному lock-файлу.
5. Убедитесь, что менеджер пакетов завершил работуПосле согласованного изменения версий в корне проекта выполните npm ls и штатный сценарий тестирования npm test (если он определён в package.json), затем npm run build при наличии сценария сборки. Ошибок ERESOLVE и несовместимых API быть не должно; наличие предупреждений нужно оценивать отдельно. Если тесты не проходят, откатите изменения в зависимости из Git и выберите другой подтверждённо совместимый набор версий. Проверять процессы apt/dpkg для npm не нужно: это другой менеджер пакетов.

#Быстрый обход

Только для краткой изолированной проверки совместимости допускается разовый npm install --legacy-peer-deps. Такой запуск не гарантирует работоспособности пакетов; npm install --force ещё сильнее обходит защитные проверки и не должен предлагаться как стандартное исправление. Не закрепляйте обход в .npmrc проекта, пока не установлены причина конфликта и приемлемость риска.

#Настоящее решение

Прочитайте текст ошибки: там указано, какая версия пакета запрошена и что установлено. Проверьте требования: npm view пакет peerDependencies. Обновите конфликтующие пакеты до совместимых версий (npm install react@18 react-dom@18), либо установите версию плагина, совместимую с вашим фреймворком. Просмотрите дерево: npm ls имя_пакета.

#Принудительная фиксация

Поле overrides в npm меняет выбранные вложенные версии зависимостей, но не гарантирует выполнения peerDependencies. Работайте на отдельной ветке: установите фактически совместимые пакеты, сохраните и проверьте изменения package-lock.json, затем прогоните тесты. Не удаляйте lock-файл ради исчезновения ERESOLVE, не используйте обновление Node без оценки требований проекта.