Ошибка «версия Node.js не подходит» бывает трёх видов: сам проект объявляет несовместимый engines, пакет использует API другого runtime или нативный модуль собран для другой ABI и платформы. До удаления node_modules сохраните первую ошибку и фактические версии. Последние строки лога часто содержат каскад, а полезная причина находится выше — например EBADENGINE, SyntaxError или NODE_MODULE_VERSION.

Цель — не подобрать версию, на которой команда случайно прошла один раз, а записать воспроизводимый контракт. Разработчик, CI и контейнер должны брать одну поддерживаемую линию Node.js, один package manager и lockfile. Production может не выполнять сборку вообще: безопаснее доставлять проверенный artifact из CI, если архитектура проекта это позволяет.

Снимок окружения отделяет runtime от зависимостей

node --version
npm --version
node -p "process.platform + ' ' + process.arch + ' abi=' + process.versions.modules"
npm config get registry
npm config get engine-strict

# затем сохранить первую ошибку чистой установки
npm ci

Команды не исправляют проект, а создают сравнимый снимок. Выполните их в локальном shell, CI job и внутри контейнера сборки. Отдельно запишите базовый образ и архитектуру: arm64 и x64 могут получать разные бинарные зависимости. Не публикуйте полный npm config — в нём могут быть registry token и приватные адреса; нужны только безопасные параметры и версии.

Файлы проекта отвечают на разные вопросы

Файл или полеЧто фиксируетЧастая ошибка
package.json enginesдопустимый диапазон Node/npmслишком широкий диапазон или только warning
.nvmrcверсию для nvm в репозиториифайл есть, но CI его не читает
packageManagerожидаемый менеджер и версиюлокально npm, в CI другой инструмент
package-lock.jsonточное дерево npmlockfile изменён другой major-версией npm
Dockerfile/CI imageреальный runtime сборкиплавающий тег node:latest
native addonABI и платформу бинарникакопирование node_modules между системами

Поле engines в npm по умолчанию может быть только предупреждением для зависимостей, если не включён строгий режим. Поэтому оно документирует контракт, но не заменяет выбор образа CI. .nvmrc помогает nvm использовать указанную версию в shell, однако runner и Docker должны явно читать её или получать то же значение из единого параметра. Не держите три несвязанных номера в разных файлах без автоматической проверки.

Чистая установка воспроизводит то, что проверит CI

  • удаление node_modules не сопровождается удалением lockfile, если задача — воспроизвести текущее дерево;
  • npm ci требует согласованности package.json и lockfile и не переписывает lock в процессе установки;
  • node_modules не копируется с Windows или macOS в Linux-контейнер;
  • кеш CI получает ключ из ОС, архитектуры, Node, package manager и hash lockfile;
  • preinstall/postinstall scripts изучаются до запуска в чувствительном окружении;
  • build и тесты выполняются в том же образе, который планируется закрепить.

Если npm ci падает только на нативном пакете, проверьте наличие готового бинарника для версии Node и libc, а также инструменты сборки. Не лечите это глобальным npm install и копированием получившейся папки. Либо выберите поддерживаемую комбинацию, либо обновите зависимость, либо воспроизводимо собирайте её из исходников в подходящем образе.

Переход на новую LTS-линию делают отдельным изменением

Сначала убедитесь по официальному графику Node.js, что выбранная линия поддерживается. Создайте ветку обновления, поменяйте закреплённую версию, выполните чистую установку, тесты, сборку и smoke-test artifact. Только после этого обновляйте lockfile тем package manager, который будет использовать CI. Не объединяйте миграцию Node, редизайн и массовое обновление зависимостей в один релиз.

Если старая линия уже не поддерживается, временное закрепление восстанавливает сборку, но не является финальным решением. Зафиксируйте срок миграции и список несовместимых пакетов. Автоматический бот обновлений полезен после зелёной baseline-сборки; до неё он добавит шум и усложнит поиск зависимости, которая держит проект на старой версии.

Контракт окружения проверяется до долгой сборки

  1. Добавить ранний шаг CI, который печатает безопасные версии и сравнивает Node с политикой проекта.
  2. Собирать из digest или конкретного version tag, а не из плавающего latest.
  3. Запускать npm ci на чистом workspace и не использовать node_modules из предыдущей версии Node.
  4. Сохранить package-lock и checksums artifact вместе с идентификатором образа.
  5. Проверить запуск результата в staging и только затем заменить production artifact.

Для разбора подготовьте package.json, lockfile, .nvmrc, Dockerfile или фрагмент CI, безопасный снимок версий и первую ошибку. Registry token, .npmrc с секретами и весь node_modules не нужны. Возврат выполняется заменой artifact и образа на предыдущие проверенные версии, а не ручной установкой другой Node.js прямо на production-сервере.

Проверенные источники