Node 版本不匹配怎么解决？EBADENGINE / Unsupported engine 和 nvm 切换

装依赖或启动项目时报 npm WARN EBADENGINE Unsupported engine、The engine "node" is incompatible，或本地能跑、线上构建失败——核心都是一个：你本机的 Node 版本，和项目（或某个依赖）要求的版本对不上。

最稳的解法不是删依赖，而是用版本管理器（nvm）把 Node 切到项目要求的版本。

第一步：看清楚要求哪个版本

node -v                     # 你当前的版本

报错里通常会写 required: { node: '>=18' } 之类，或看项目 package.json 的 engines 字段。把"当前版本"和"要求版本"对上号，差在哪一目了然。

① 用 nvm 切到项目要求的版本（推荐）

成因：全局只装了一个 Node 版本，换项目就不匹配。

修复：用 nvm 装并切换，不同项目用不同版本：

nvm install 20      # 装项目要求的大版本
nvm use 20          # 切过去
node -v             # 确认

没装 nvm 的：macOS/Linux 用 nvm，Windows 用 nvm-windows。

② 给项目锁版本：.nvmrc + engines

成因：团队/自己换设备后又踩同样的版本坑。

修复：在项目根目录建 .nvmrc 写上版本号（如 20），以后进项目 nvm use 自动读它；同时在 package.json 声明：

"engines": { "node": ">=20 <21" }

这样别人和构建平台都知道该用哪个版本。

③ EBADENGINE 只是 WARN 还是 ERROR

成因：npm WARN EBADENGINE 是警告，多数时候能继续装；变成报错通常是依赖或 CI 强校验。

修复：是 WARN 且功能正常可暂时忽略；但要根治还是切到兼容版本（见 ①），别长期带着不匹配跑。

④ 本地和线上 Node 版本不一致（最隐蔽）

成因：本地 Node 20、Vercel/CI 默认别的版本，于是本地过、线上挂（或反过来）。

修复：

• 在 package.json 用 engines.node 写死版本；
• 构建平台（Vercel → Settings → Node.js Version）选成和本地一致；
• 用 .nvmrc 让本地和支持它的 CI 自动对齐。

一个稳妥的对齐流程

1. 项目根目录建 .nvmrc（写要求的大版本）。
2. package.json 加 engines.node。
3. 本地 nvm use 切过去，npm ci 重装。
4. 构建平台 Node 版本设成同一个。

4 步对齐后，"本地能跑线上挂"这类版本问题基本消失。

让 Codex 辅助

我报 EBADENGINE / Node 版本不匹配（贴完整报错）。
node -v 是 X，项目 engines 要求 Y。请给出用 nvm 切换并锁定版本的步骤，
以及怎么让本地和构建平台版本一致。

风险提醒

• 别为了消报错随便降级或升级全局 Node，会影响别的项目；用 nvm 按项目隔离。
• 改 engines 不会自动帮你装对版本，它只是声明；真正切版本还得 nvm。

相关工具

• 报错解释器
• Codex 工具页
• 项目报价助手

相关报错排查

同一套排查思路的常见报错，建议一起看：

• npm install 报错怎么解决
• npm run dev 能跑但 build 失败
• npm command not found 怎么解决

免责声明

本文命令对应 nvm / npm engines 的标准行为，供学习和排查参考；在受管设备或客户环境切换 Node 版本需明确授权并人工复核。