使用 nvm 管理 Node.js 版本，告别兼容性烦恼

在开发 Node.js 项目时，经常会遇到不同项目需要不同 Node 版本的场景。比如你接手了一个旧项目，它的依赖只支持 Node 14，而你的开发环境是 Node 18，运行 npm install 时就会冒出 EBADENGINE 警告甚至报错。这时候，nvm（Node Version Manager） 就是你的救星。

本文将从零开始，详细介绍 nvm 的安装、常用命令以及如何用它解决版本兼容性问题，帮助你轻松应对多版本 Node 环境。

一、什么是 nvm？

nvm 是一个可以让你在同一台机器上安装、切换多个 Node.js 版本的命令行工具。它支持 Unix 系统（macOS、Linux）和 Windows（通过 nvm-windows 实现），让你能够：

• 为不同项目指定 Node 版本
• 轻松测试代码在不同 Node 版本下的兼容性
• 快速升级或回退 Node 版本

二、安装 nvm

1. macOS / Linux

在终端中执行以下命令安装 nvm：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

或者使用 wget：

wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

安装完成后，重启终端或执行 source ~/.bashrc（或 ~/.zshrc）使配置生效。

验证安装：

nvm --version

2. Windows

Windows 用户需要使用 nvm-windows，它是一个独立的工具。

• 访问 nvm-windows 发布页
• 下载最新版本的 nvm-setup.zip，解压后运行安装程序
• 安装过程中注意选择安装路径

安装完成后，以管理员身份打开 CMD 或 PowerShell，运行：

nvm version

如果看到版本号，说明安装成功。

三、常用命令速查表

注意：nvm 和 nvm-windows 的命令略有差异，比如 nvm list available 是 nvm-windows 独有的；在 Unix 系统上，可用版本需要通过 nvm ls-remote 查看。

四、解决项目版本不兼容的实战

场景重现

你在 GitHub 上 clone 了一个旧项目，执行 npm install 时出现类似下面的警告：

npm warn EBADENGINE Unsupported engine {
npm warn EBADENGINE   package: '@achrinza/node-ipc@9.2.2',
npm warn EBADENGINE   required: { node: '8 || 10 || 12 || 14 || 16 || 17' },
npm warn EBADENGINE   current: { node: 'v24.13.1', npm: '11.8.0' }
}

这说明项目要求的 Node 版本与你当前系统版本（v24）不符。虽然 npm 可能只是警告，但某些依赖在过高版本的 Node 下可能无法正常工作。

解决步骤

1. 查看项目需要的 Node 版本

通常可以在项目的 package.json 中查看 engines 字段：

"engines": {
  "node": ">=16 <18"
}

如果没有这个字段，可以查看项目文档或根据警告信息推断。

2. 安装兼容的 Node 版本

假设项目需要 Node 16，那么执行：

# macOS/Linux
nvm install 16

# Windows
nvm install 16.20.2   # 指定具体版本号

3. 切换到该版本

nvm use 16

使用 node -v 确认版本已切换。

4. 重新安装依赖

删除已有的 node_modules 和 package-lock.json（如果有），然后重新运行：

npm install

此时不会再出现引擎不兼容的警告，依赖安装过程也会更加顺畅。

5. 设置项目默认版本（可选）

为了方便，可以为项目目录单独指定 Node 版本。在项目根目录创建 .nvmrc 文件，内容为所需版本号（如 16）。以后进入该目录时，只需执行 nvm use 即可自动切换到对应版本。

五、其他实用技巧

1. 设置全局默认版本

如果你希望新打开的终端默认使用某个版本，可以执行：

nvm alias default 18.20.0

之后每次启动终端都会自动切换到该版本。

2. 查看已安装版本

nvm ls

输出示例：

->     v16.20.2
       v18.20.0
         v20.10.0
default -> 18.20.0

3. 卸载不再使用的版本

保持系统整洁，及时清理旧版本：

nvm uninstall 14.21.3

六、常见问题

Q1：nvm 切换版本后，新终端又变回旧版本？

A：需要设置默认版本，使用 nvm alias default <version> 即可。

Q2：Windows 上安装 nvm-windows 后无法使用 nvm use？

A：尝试以管理员身份运行 CMD 或 PowerShell；如果仍然提示“version not installed”，先执行 nvm list 确认版本是否安装成功，若未显示，重新安装。

Q3：项目需要多个版本，每次都要手动切换吗？

A：使用 .nvmrc 文件配合 nvm use 可以简化操作。也可以利用 avn 等工具实现自动切换。

七、总结

nvm 是 Node.js 开发者必备的工具之一，它解决了版本碎片化带来的头疼问题。通过简单的命令行操作，你就能：

• 快速安装任意 Node 版本
• 在不同项目间无缝切换
• 确保依赖安装时不会因引擎限制而失败

参考资料

• nvm GitHub 仓库
• nvm-windows GitHub 仓库
• Node.js 官方下载页面