Node.js: The engine "node" is incompatible with this module

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

Ошибка The engine "node" is incompatible with this module. Expected version ">=18" (Yarn) или предупреждение npm WARN EBADENGINE означает, что версия Node.js не удовлетворяет полю engines в package.json проекта или зависимости. Это защита от некорректной сборки.

Нужно переключиться на подходящую версию Node, а не отключать проверку.

Для этого удобен менеджер версий.

Проект требует другую версию Node.js, чем установлена. Установите нужную версию через менеджер версий (nvm, fnm) или обновите Node.

#Причины и решения

#Пошаговое решение

1. Проверьте версии node и npmОткройте терминал в каталоге проекта: VS Code → «Терминал» → «Новый терминал», Windows PowerShell или терминал Linux/macOS. Выполните node --version и npm --version (для Yarn дополнительно yarn --version). Сравните версию Node с диапазоном в точном сообщении Expected version/EBADENGINE; нужно учитывать не только главный номер, но и минимальный выпуск. Если node не найден, сначала установите поддерживаемый выпуск Node.js согласно документам проекта.
2. Прочитайте engines в package.jsonОткройте package.json редактором и найдите engines.node; проверьте .nvmrc/.node-version, если есть. Например, >=20 <23 означает Node 20–22, но не Node 23; это пример, а фактический диапазон берётся из проекта. Если несовместимость выдал пакет-зависимость, посмотрите её точное имя и версию в ошибке и требования в опубликованной документации. Не подменяйте engines на произвольный диапазон ради установки: это не гарантирует совместимость.
3. Установите менеджер версийВыберите один поддерживаемый механизм управления версиями: на Linux/macOS обычно nvm или fnm, на Windows — официальный установщик либо nvm-windows/fnm (названия и команды могут различаться). Установку менеджера проводите по официальным инструкциям, затем откройте новое окно терминала. Если в проекте уже используется .nvmrc, в среде с nvm выполните nvm install, затем nvm use; иначе укажите согласованную поддерживаемую версию, например nvm install 22. Не устанавливайте версии со статусом «поддержка прекращена», если доступен вариант с поддержкой.
4. Переключитесь на нужную версиюВ новом терминале проверьте node -v и соответствие требованиям, затем npm -v. Если проект использует lock-файл package-lock.json, сделайте резервную копию нужных изменений и выполните npm ci из корня проекта: команда удаляет и заново создаёт node_modules, поэтому не запускайте её, если в папке есть вручную добавленные файлы, которые нужно сохранить. Для Yarn/pnpm используйте штатные команды своего менеджера и его lock-файл. Не удаляйте package-lock.json как типовое решение несовместимости движка.
5. Пересоздайте node_modulesПовторите исходную команду установки/сборки и убедитесь, что больше нет EBADENGINE или incompatible engine. Если ошибка сохраняется, проверьте, какой node реально используется: Windows — where.exe node, Linux/macOS — command -v node, и сравните терминал IDE с обычным. Если приложение требует версию без поддержки безопасности, согласуйте обновление самого приложения/пакетов; обход --ignore-engines/engine-strict=false не делает старый Node совместимым.
6. Дополнительная команда по теме

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

   Строки с # — условные отдельные действия; при npm ci папка node_modules будет удалена и восстановлена.

   node --version

   npm --version

   # При использовании nvm в правильно настроенном терминале:

   # nvm install

   # nvm use

   # Только при наличии package-lock.json и после проверки node_modules:

   # npm ci

#Диагностика

Проверьте версии: node -v и npm -v. Откройте package.json и найдите engines, а также файлы .nvmrc, .node-version, .tool-versions. Для зависимости смотрите в тексте ошибки, какой пакет требует версию. Список поддерживаемых релизов — на nodejs.org/en/about/previous-releases.

#Переключение версии

Установите менеджер: nvm-windows или nvm (Linux/macOS), либо fnm, либо Volta. Команды: nvm install и nvm use при наличии .nvmrc, либо используйте конкретный поддерживаемый диапазоном релиз. Для проекта: nvm use читает .nvmrc. После переключения пересоздайте зависимости: при наличии package-lock.json выполните npm ci после проверки, что в node_modules нет вручную сохранённых файлов; команда сама пересоздаёт этот каталог.

#Обходные пути

Для Yarn Classic: yarn install --ignore-engines (небезопасно, может сломать сборку). Для npm: npm install --engine-strict=false. Лучше обновить проект или зависимость до версии, поддерживающей ваш Node. В Docker используйте образ нужной версии (FROM node:20-alpine). В CI укажите версию через actions/setup-node.