Как устранить конфликт peerDependencies при переходе на новую основную версию React

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

После установки новой основной версии React npm может остановиться с ERESOLVE: одна из библиотек заявляет совместимость только со старой основной версией React. Это конфликт требований пакетов, а не повреждение npm. Разбор относится к переходу React на новую основную версию; не заменяет общую статью о любых ошибках ERESOLVE.

#Как отличить возможные причины

#Пошаговая диагностика и устранение

1. Сохраните исходный рабочий набор зависимостейПри изменении версии React работайте в отдельной ветке Git или копии проекта. Проверьте, что есть package.json и package-lock.json; сохраните оба файла и незакоммиченные изменения. Не запускайте npm install --force в действующем проекте: он способен создать несовместимое дерево зависимостей.
2. Выпишите точную пару конфликтующих пакетовОткройте VS Code → папку проекта → Терминал → Создать терминал. Повторите команду установки, которой обновляли React, либо используйте сохранённый журнал npm: найдите строки ERESOLVE, Found: react@..., peer react@... from .... Запишите имя конфликтующей библиотеки; не считайте React виновником без этих строк.
3. Проверьте версии установленного React и NodeВ терминале выполните node --version, npm --version, затем npm ls react react-dom --depth=0. Последняя команда может завершиться ненулевым кодом при уже конфликтующем наборе — это диагностический результат. Сравните записи dependencies и devDependencies в package.json.
4. Проверьте требования конкретной библиотекиДля известного пакета из текста ERESOLVE откройте его страницу в официальном реестре npm или выполните npm view ИМЯ_ПАКЕТА@ВЕРСИЯ peerDependencies --json, заменив оба элемента фактическими данными. В результате появятся поддерживаемые диапазоны (например, ^18, не включающий ^19); если команда не смогла подключиться к реестру, проверьте сеть или настройки корпоративного реестра, а не отключайте TLS.
5. Выберите поддерживаемый путь обновленияЕсли есть новый выпуск конфликтующей библиотеки с поддержкой нужной основной версии React, обновите именно его после чтения примечаний о несовместимых изменениях. Если такого выпуска пока нет, оставьте прежнюю совместимую версию React и запланируйте миграцию позже; удалять библиотеку без замены можно только после проверки функций приложения.
6. Согласованно измените версии в контролируемой копииВ рабочей ветке откройте package.json, установите совместимые диапазоны для react, react-dom и проблемной библиотеки. Для сохранения согласованного предыдущего релиза допустимо выполнить npm install react@18 react-dom@18 только если ваш проект действительно должен оставаться на React 18 и остальные зависимости это допускают. Для другой версии подставьте выбранный поддерживаемый релиз, не копируйте номер автоматически.
7. Повторите установку и проверьте дерево зависимостейВ той же папке выполните npm install (устанавливает зависимости и может выполнять их скрипты; доверяйте только зависимостям проекта), затем npm ls react react-dom --depth=0 и при необходимости npm explain ИМЯ_ПАКЕТА. Успех — без ERESOLVE, необходимые пакеты присутствуют. Не используйте --legacy-peer-deps как постоянную маскировку несовместимости.
8. Запустите тесты приложения и проверьте откатВ package.json найдите раздел scripts и выполните предусмотренные проектом npm test или npm run build, если команды существуют; откройте страницу приложения и проверьте компоненты, формы, маршруты. При сбое верните package.json и package-lock.json из Git, а затем восстановите зависимости из доверенного lock-файла; npm ci очищает node_modules и подходит только после сохранения локального состояния.
9. Команды для отдельных ситуацийВыберите только подходящий вариант. Это не одна последовательность: часть команд диагностирует проблему, а часть меняет настройки или данные.
   Выберите подходящий вариант — это не команды для последовательного выполнения

   Вариант 1Только чтение в корне проекта.

   Linux · Терминал (Bash)КомандаКопировать всёВыделить

   Только чтение в корне проекта. npm ls иногда возвращает ненулевой код, если дерево зависимостей несовместимо.

   node --version

   npm --version

   npm ls react react-dom --depth=0

   Вариант 2Пример сознательного возвращения на React 18, а не универсальная команда обновления.

   Linux · Терминал (Bash)С осторожностьюКопировать всёВыделить

   Пример сознательного возвращения на React 18, а не универсальная команда обновления. Меняет package.json, package-lock.json и node_modules, может запускать скрипты зависимостей; используйте только в отдельной ветке и при подтверждённой совместимости.

   npm install react@18 react-dom@18

   Команда может изменить состояние системы или её настройки. Проверьте параметры и последствия перед запуском.

#Минимальный пример и проверка на тестовом проекте

{
  "dependencies": {
    "react": "^19.0.0",
    "react-dom": "^19.0.0",
    "example-widget": "^1.0.0"
  }
}

#Проверка результата и действия при неуспехе

Установка завершилась без ERESOLVE, npm ls react react-dom --depth=0 показывает согласованные версии и проектные тесты проходят. Если npm сообщает новый конфликт, проверьте весь путь требования через npm explain и повторите выбор совместимых релизов, не отключая проверки.