Краткий ответ
Ошибка «Версия Node.js несовместима» чаще всего означает, что ваш проект требует другую версию Node.js, отличную от установленной. Решение: проверить текущую версию, установить подходящую (например, через nvm на macOS/Linux или nvm-windows на Windows) и повторно запустить установку зависимостей.
Как проявляется проблема
- npm install или yarn install выдает ошибку о несовместимой версии Node.js
- Приложение не запускается или падает сразу после запуска
- Сообщение содержит «engine» или «Unsupported engine» и требуемую версию
- Некоторые функции работают, но сборка или тесты падают
- CI/CD pipeline выдает ошибку из-за версии Node.js
Частые причины
Проект требует более новую версию Node.js
В файле package.json или .nvmrc указана минимальная версия, которой не соответствует текущая установка.
Установлена устаревшая версия Node.js
В системе установлена более старая версия (например, 22.x), тогда как проект требует 24.x или более новую LTS версию.
Конфликт нескольких версий Node.js
На компьютере установлено несколько версий, а PATH указывает на неправильную, или используется глобальный npm вместо локального.
Отсутствует управление версиями
Без такого инструмента, как nvm, переключение между проектами требует ручной установки и удаления.
Пошаговое решение
- 1
Проверьте текущую версию Node.js
Откройте терминал и выполните
node -vиnpm -v. Запишите вывод. Также проверьте, есть ли в проекте файл.nvmrcили полеenginesвpackage.json, которое определяет требуемую версию. - 2
Найдите требуемую версию
Если в проекте есть
.nvmrc, содержимое этого файла является версией, которую нужно использовать. В противном случае посмотритеenginesвpackage.jsonили документацию проекта. Если данных нет, установите текущую LTS версию с официального сайта nodejs.org. - 3
Установите инструмент управления версиями (рекомендуется)
В Windows скачайте и установите nvm-windows с официального GitHub репозитория. В macOS/Linux используйте
nvm(Node Version Manager) согласно инструкции с официального сайта. После установки закройте и снова откройте терминал. - 4
Установите подходящую версию Node.js
Если вы используете nvm, выполните
nvm install 24(замените число на версию, требуемую проектом). Затем активируйте ее с помощьюnvm use 24. В Windows с nvm-windows команды те же, но выполняйте их в Command Prompt или PowerShell. - 5
Установите версию по умолчанию (необязательно)
Чтобы избежать повторной активации, в macOS/Linux установите версию по умолчанию:
nvm alias default 24. В Windows с nvm-windows достаточно выполнитьnvm use 24; nvm-windows не поддерживаетalias default. Проверьте с помощьюnode -v, активна ли нужная версия. - 6
Очистите кеш и переустановите зависимости
Сделайте резервную копию или проверьте, что изменения сохранены в Git. Удалите
node_modules, аpackage-lock.json(илиyarn.lock) только если это необходимо. Затем при необходимости выполнитеnpm cache clean --forceиnpm install(илиyarn install/pnpm install, в зависимости от пакетного менеджера). Это позволяет избежать остатков старых бинарных модулей, которые могут вызвать ошибки. - 7
Проверьте, сохраняется ли ошибка
Запустите
npm run buildилиnpm startи проверьте вывод. Если вы все еще получаете ошибку о версии, проверьте, не требует ли какой-либо глобальный пакет другую версию или правильный ли PATH (which nodeв macOS/Linux,where.exe nodeв Windows). - 8
Обновите конфигурацию CI/CD
Если вы используете GitHub Actions, GitLab CI или аналоги, в конфигурационном файле установите ту же версию Node.js (например,
node-version: 24). Не забудьте согласовать локальную среду с CI средой.
Если ничего не помогает
Если вы испробовали все шаги, а ошибка остается, проверьте, есть ли в проекте .npmrc с engine-strict=true, который блокирует установку. Временно вы можете удалить его или установить в false, но делайте это только если понимаете последствия. Также проверьте, используете ли вы подходящий пакетный менеджер (npm, yarn, pnpm) и его версию. Иногда необходимо очистить и глобальный кеш npm и переустановить npm. Если ошибка возникает только на продакшн-сервере, проверьте, установлена ли там та же версия Node.js, что и локально. Для сложных проектов с несколькими микросервисами рассмотрите использование Docker, который гарантирует согласованную среду.
Как избежать повторения
- Всегда используйте `.nvmrc` или `engines` в `package.json`, чтобы явно указать версию Node.js.
- Регулярно обновляйте Node.js до стабильной LTS версии и следите, когда проекты требуют более новую.
- Используйте инструмент управления версиями (nvm, nvm-windows, fnm) для легкого переключения между проектами.
- В CI/CD pipeline определите ту же версию Node.js, что и в локальной разработке.
Когда лучше обратиться к специалисту
Если ошибка влияет на продакшн-среду или вы не можете согласовать версии в команде, обратитесь в IT поддержку. Они могут настроить правильную среду и предотвратить простои в работе.
Разработка ПО и продуктов · Приложения на заказ, SaaS и MVP за 4-8 недельЧастые вопросы
Как узнать, какая версия Node.js требуется проекту?
Чаще всего она указана в `.nvmrc` или в поле `engines` внутри `package.json`. Если этих данных нет, посмотрите README или документацию проекта. В противном случае установите последнюю LTS версию.
Могу ли я установить несколько версий Node.js одновременно?
Да, используйте nvm (macOS/Linux) или nvm-windows. Они позволяют устанавливать несколько версий и выбирать, какую использовать для каждого проекта.
Безопасно ли удалять node_modules и package-lock.json?
Удаление `node_modules` является обычной практикой и безопасно, если после этого вы переустановите зависимости. Удаление `package-lock.json` или `yarn.lock` может изменить дерево зависимостей, поэтому делайте это только при необходимости и сначала сохраните файл или проверьте, что изменение закоммичено. После удаления выполните `npm install` (или соответствующую команду для yarn/pnpm).