#Как проявляется ошибка и когда применим способ
После обновления npm-зависимости проект перестаёт собираться на прежнем Node.js. Часто новая версия пакета требует более новый движок, использует недоступный синтаксис JavaScript либо больше не поддерживает старую среду, указанную в engines.
#Причины и признаки
| Возможная причина | Как узнать | Что делать |
|---|---|---|
| Пакет повысил требуемую версию Node.jsРазработчик пакета обновил поле engines или используемые API. | В логе появляются EBADENGINE, SyntaxError или предупреждение о несовместимой версии. | Сверить engines и установить поддерживаемую версию Node.js в тестовой среде. |
| Lock указывает на несовместимый выпускДиапазон в package.json допустил новую версию пакета без проверки сборки. | Сборка до обновления была успешной; после обновления изменилась версия в lock-файле. | Вернуть проверенный lock или закрепить совместимую версию. |
#Пошаговая диагностика и решение
- 1. Откройте журнал и найдите первую несовместимостьВ сборочном окружении сохраните первую строку ошибки, содержащую имя пакета, EBADENGINE, unexpected token или версию Node.js. Не ориентируйтесь только на последнюю строку npm ERR!; она не указывает на истинную причину.
- 2. Определите рабочую версию Node.jsНа сервере и на компьютере выполните node --version и npm --version. Сопоставьте с настройками CI, файлами .nvmrc, .node-version или engines в package.json. Не обновляйте Node.js на рабочем сервере вслепую: у других приложений могут быть отдельные требования.Linux · Терминал (Bash)КомандаЧтение версий и заявленных ограничений проекта.
node --versionnpm --versionnpm pkg get engines
- 3. Узнайте новую версию и требования пакетаВ копии проекта выполните npm ls ИМЯ_ПАКЕТА и npm view с конкретной версией из lock-файла, чтобы проверить engines.node. Если у пакета нет engines, проверьте официальный журнал изменений; отсутствие записи не гарантирует совместимость.
- Подставьте реальные имя и версиюLinux · Терминал (Bash)КомандаПодставьте реальные имя и версию. Только чтение локального дерева и метаданных реестра.
npm ls ИМЯ_ПАКЕТАnpm view ИМЯ_ПАКЕТА@ВЕРСИЯ engines --json
- 4. Сравните последнюю успешную сборкуВ системе контроля версий посмотрите, когда package-lock.json изменился последний раз и какая версия пакета появилась. Если раньше поддерживалась старая Node.js, зафиксируйте совместимую версию на отдельной ветке и подготовьте запуск npm ci, не удаляя файлы действующего проекта.
- 5. Выберите один безопасный путьПервый вариант — обновить Node.js лишь в изолированном окружении сборки на поддерживаемую версию. Второй — откатить конкретный пакет к проверенному выпуску. Для обоих путей просмотрите lock-файл, список затронутых зависимостей и возможные изменения API. Не отключайте engine-strict ради обхода несовместимости.
- 6. Проведите чистую сборку на копииНа отдельной ветке выполните npm ci с сохранённым lock-файлом, затем привычную команду npm run build. Отслеживайте новый код ошибки: если возникла ошибка в коде проекта, простой смены Node.js недостаточно. Проверьте тесты, прежде чем выпускать изменение.
- Дополнительная команда по темеLinux · Терминал (Bash)С осторожностьюТолько копия доверенного проекта; npm ci удаляет node_modules, сценарий build выполняет команды проекта.
npm cinpm run buildКоманда может изменить состояние системы или её настройки. Проверьте параметры и последствия перед запуском.
- 7. Закрепите совместимую средуЗапишите поддерживаемую версию Node.js в проектный файл и настройку CI. Зафиксируйте обновлённый lock-файл либо проверенный откат пакета. Если после запуска в тесте приложение не работает, верните прежнюю версию инструмента и сохранённые файлы.
#Проверка результата и действия при повторении
После выбора совместимого выпуска Node.js или пакета чистый npm ci и npm run build проходят в воспроизводимой тестовой среде. Версии в build-логе и lock-файле подтверждают одно и то же сочетание зависимостей.
Если на указанном шаге результат отличается, остановитесь и запишите первое полное сообщение об ошибке, версию инструментов и проверенное состояние до исправления. Не переходите к опасным действиям на действующем проекте: повторите проверку на отдельной копии, верните сохранённые файлы и только затем выбирайте следующую причину.