Ошибка «версия 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 | точное дерево npm | lockfile изменён другой major-версией npm |
| Dockerfile/CI image | реальный runtime сборки | плавающий тег node:latest |
| native addon | ABI и платформу бинарника | копирование 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-сборки; до неё он добавит шум и усложнит поиск зависимости, которая держит проект на старой версии.
Контракт окружения проверяется до долгой сборки
- Добавить ранний шаг CI, который печатает безопасные версии и сравнивает Node с политикой проекта.
- Собирать из digest или конкретного version tag, а не из плавающего latest.
- Запускать npm ci на чистом workspace и не использовать node_modules из предыдущей версии Node.
- Сохранить package-lock и checksums artifact вместе с идентификатором образа.
- Проверить запуск результата в staging и только затем заменить production artifact.
Для разбора подготовьте package.json, lockfile, .nvmrc, Dockerfile или фрагмент CI, безопасный снимок версий и первую ошибку. Registry token, .npmrc с секретами и весь node_modules не нужны. Возврат выполняется заменой artifact и образа на предыдущие проверенные версии, а не ручной установкой другой Node.js прямо на production-сервере.