在实际的 Node.js 开发中，你是否遇到过这样的场景：接手一个老项目，发现它依赖 Node.js 12，而你本地环境是 Node.js 18，直接运行会报错；或者，你需要同时维护一个使用 Node.js 16 的稳定项目和一个正在尝鲜 Node.js 20 新特性的实验项目。频繁地手动卸载、安装、配置不同版本的 Node.js 不仅繁琐，而且容易出错，导致开发环境混乱。这正是 Node Version Manager（nvm）要解决的核心问题。

nvm 是一个命令行工具，它允许你在同一台机器上安装多个版本的 Node.js，并能根据项目或当前终端会话的需要，快速、轻松地在这些版本之间切换。它通过独立管理每个 Node.js 版本的安装目录和全局 npm 包，实现了版本环境的完全隔离，避免了全局污染。对于前端开发者、Node.js 后端开发者或任何需要处理多版本 Node.js 项目的工程师来说，掌握 nvm 是构建一个干净、可控、高效开发环境的第一步。

本文将带你从零开始，在 Windows 系统上完成 nvm 的安装、配置和使用。你将学会如何安装 nvm，如何用它安装和管理多个 Node.js 版本，如何解决切换版本时常见的权限和脚本执行策略问题，以及如何为不同的项目配置默认的 Node.js 版本。最终，你将拥有一个灵活、强大的 Node.js 版本管理环境。

1. 理解 nvm 的工作原理与核心价值

在深入操作之前，理解 nvm 如何工作以及它解决了哪些痛点，能帮助你在遇到问题时更快地定位和解决。

1.1 为什么需要版本管理工具？

Node.js 生态活跃，版本迭代迅速。不同项目可能因为依赖的第三方库、框架或特定的语法特性，而被锁定在特定的 Node.js 版本上。例如：

• 项目A：一个遗留系统，使用async/await但不支持顶级await，需要 Node.js 14+。
• 项目B：一个使用最新 Next.js 的项目，需要 Node.js 18.17+ 以获得最佳性能和新特性。
• 项目C：一个内部工具，其某个关键依赖仅兼容 Node.js 16。

如果没有版本管理工具，你只能：

1. 全局安装一个“折中”版本，可能导致部分项目无法运行。
2. 为每个项目维护一个独立的虚拟机或容器，资源消耗大。
3. 手动修改系统 PATH 和环境变量，过程极易出错且难以维护。

nvm 通过一个简单的设计解决了这个问题：它将每个 Node.js 版本安装在一个独立的目录下（例如C:\Users\YourName\AppData\Roaming\nvm），并通过修改当前终端会话的环境变量PATH，来指向你选中的那个版本的 Node.js 和 npm 可执行文件。当你切换版本时，nvm 只是改变了PATH的指向，不同版本之间完全隔离。

1.2 nvm 与其它工具的区别

你可能也听说过n、fnm或volta等 Node.js 版本管理工具。对于 Windows 用户而言，nvm-windows（即我们常说的 nvm for Windows）是社区维护最广泛、文档最齐全的选择。它与 macOS/Linux 上的原版nvm（由nvm-sh组织维护）命令基本兼容，但底层实现因操作系统差异而不同。本文聚焦于 Windows 平台下的nvm-windows。

注意：nvm-windows是一个独立的项目，并非官方nvm的移植。因此，某些高级命令或特性可能略有不同，但其核心的版本管理功能完全一致且稳定。

1.3 核心概念：版本别名与长期支持版

nvm 不仅管理具体版本号，还支持别名：

• node： 安装最新的稳定版。
• lts： 安装最新的长期支持版。对于生产环境，通常推荐使用 LTS 版本。
• lts/erbium： 安装指定代号（如 Erbium）的 LTS 版本。

理解这些别名能让你更高效地管理版本。

2. 在 Windows 系统上安装 nvm

我们将使用nvm-windows项目提供的安装包。在开始前，请务必完成一个关键步骤：卸载已存在的 Node.js。

2.1 安装前的准备工作

1. 卸载现有 Node.js：

   • 打开 Windows 的“应用和功能”设置。
   • 搜索 “Node.js”，将其卸载。这一步至关重要，因为系统原有的 Node.js 会干扰 nvm 对环境变量的管理。
   • 同时，检查并删除可能残留的 Node.js 安装目录（如C:\Program Files\nodejs）和用户目录下的npm、npm-cache等文件夹。

2. 确认系统架构：

   • 在“设置”->“系统”->“关于”中，查看“系统类型”，确认是 64 位（x64）还是 32 位（x86）操作系统。大多数现代电脑是 64 位。

2.2 下载与安装 nvm-setup.exe

1. 访问nvm-windows项目的官方发布页面。通常，你应该选择最新的nvm-setup.exe安装程序。

2. 运行nvm-setup.exe。

3. 在安装过程中，你会看到两个重要的路径配置：

   • nvm 安装目录： 这是 nvm 自身的管理文件存放位置。默认是C:\Users\[你的用户名]\AppData\Roaming\nvm。建议保持默认。
   • Node.js 符号链接目录： 这是 nvm 创建的一个“快捷方式”目录，用于统一指向当前激活的 Node.js 版本。默认是C:\Program Files\nodejs。这个目录需要管理员权限才能写入，但安装程序会处理。保持默认即可。

   注意：第二个路径（符号链接目录）是 nvm 工作的关键。nvm 会将你“正在使用”的 Node.js 版本的可执行文件，通过一个名为nodejs的文件夹链接到这里，并将此路径添加到系统PATH中。这样，无论你在命令行何处，输入node或npm命令，都会指向当前激活的版本。

4. 完成安装。

2.3 验证安装

安装完成后，以管理员身份打开一个新的命令提示符（CMD）或 PowerShell 窗口。这是为了确保有足够的权限进行后续的 Node.js 安装。

输入以下命令验证 nvm 是否安装成功：

nvm version

如果安装正确，你会看到类似1.1.12的版本号输出。

如果命令未识别，请检查：

• 是否打开了新的终端窗口？（安装后需要新会话才能加载新的环境变量）
• 环境变量PATH中是否包含了 nvm 的安装目录？你可以在终端输入echo %PATH%(CMD) 或$env:PATH(PowerShell) 查看。

3. 使用 nvm 安装与管理多个 Node.js 版本

nvm 安装成功后，你就可以开始安装和管理 Node.js 了。

3.1 常用 nvm 命令一览

首先，熟悉最核心的几个命令：

3.2 安装你的第一个 Node.js 版本

我们首先安装一个最新的长期支持版，这是最稳妥的起点。

在之前打开的管理员权限终端中，执行：

nvm install lts

命令执行后，你会看到 nvm 开始下载 Node.js 和对应的 npm，并自动进行安装。安装完成后，它通常会提示你使用nvm use命令来启用这个新版本。

接着，启用刚安装的 LTS 版本：

nvm use lts

如果成功，终端会显示Now using node v18.17.0 (64-bit)之类的信息。

现在，验证 Node.js 和 npm 是否可用：

node -v npm -v

你应该能看到对应的版本号。

3.3 安装第二个版本并切换

为了演示多版本管理，我们再安装一个较新的版本，比如 Node.js 20。

nvm install 20.9.0

安装完成后，查看本地已安装的版本列表：

nvm list

输出会类似于：

* 18.17.0 (Currently using 64-bit executable) 20.9.0

*号表示当前激活的是 18.17.0。

现在，切换到 Node.js 20：

nvm use 20.9.0

再次验证版本：

node -v # 应输出 v20.9.0 nvm current # 应输出 20.9.0

你可以通过nvm use命令在18.17.0和20.9.0之间自由切换，体验无缝的版本变更。

3.4 配置项目默认版本

每次新开终端都需要nvm use可能有些麻烦。nvm 允许你为特定项目目录设置默认版本。

1. 在项目根目录下，创建一个名为.nvmrc的文本文件。
2. 在文件中写入你想要的 Node.js 版本号，例如18.17.0。
3. 保存文件。

之后，在该项目目录下打开终端，只需执行：

nvm use

nvm 会自动读取.nvmrc文件中的版本号并切换过去。你可以将这个命令与终端启动脚本结合，实现进入目录自动切换版本。

4. 解决常见问题与故障排查

在使用 nvm 的过程中，你可能会遇到一些典型问题。以下是排查和解决方法。

4.1 权限问题：exit status 5: Access is denied.

现象： 在执行nvm use或nvm install时，提示访问被拒绝。原因： nvm 需要向C:\Program Files\nodejs这个符号链接目录写入数据，该操作需要管理员权限。解决方案：始终以管理员身份运行命令提示符或 PowerShell，然后再执行 nvm 命令。这是 Windows 下使用 nvm 最重要的习惯。

4.2 PowerShell 脚本执行策略问题

现象： 在 PowerShell 中执行npm命令时，出现红色错误：

npm : 无法加载文件 D:\nvm\nodejs\npm.ps1，因为在此系统上禁止运行脚本。有关详细信息，请参阅...

原因： PowerShell 默认的执行策略（Execution Policy）是Restricted，禁止运行任何脚本。nvm 切换版本后，npm命令实际上是通过一个.ps1脚本文件调用的。解决方案： 以管理员身份打开 PowerShell，执行以下命令修改当前用户的执行策略：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

输入Y确认。这个命令将策略改为RemoteSigned，允许运行本地脚本和来自可信远程源的签名脚本。修改后，关闭并重新打开 PowerShell，问题即可解决。

注意：RemoteSigned是开发环境中常用的平衡安全与便利的策略。切勿设置为Unrestricted。

4.3 切换版本后命令未生效

现象： 执行nvm use后，node -v显示的版本没有变化。原因：

1. 可能没有使用管理员权限的终端。
2. 系统中可能存在其他位置的node.exe（如旧版未卸载干净）在PATH环境变量中排在 nvm 的路径之前。
3. 终端缓存了旧的路径信息。排查与解决：
4. 确认使用管理员终端。
5. 执行where node命令。它会列出所有在PATH中找到的node.exe路径。第一个就是当前生效的。检查它是否指向C:\Program Files\nodejs或 nvm 的安装目录。
6. 如果指向错误，检查系统环境变量PATH，确保没有其他 Node.js 路径（如C:\Program Files\nodejs\，注意不是 nvm 的符号链接目录）排在 nvm 相关路径之前。如果有，编辑环境变量将其移除。
7. 关闭所有终端窗口，重新以管理员身份打开。

4.4 安装缓慢或失败

现象：nvm install下载速度极慢或超时失败。原因： 网络连接 Node.js 官方下载服务器可能不稳定。解决方案： 为 nvm 配置国内镜像源。编辑 nvm 安装目录下的settings.txt文件（例如C:\Users\YourName\AppData\Roaming\nvm\settings.txt），添加以下两行：

node_mirror: https://npmmirror.com/mirrors/node/ npm_mirror: https://npmmirror.com/mirrors/npm/

保存后，再次执行安装命令，速度会有显著提升。

5. 最佳实践与进阶配置

掌握了基本操作和排错后，遵循一些最佳实践能让你的开发环境更加健壮。

5.1 环境变量与全局包管理

• 全局包安装位置： 使用 nvm 时，每个 Node.js 版本都有自己独立的全局node_modules目录。这意味着你在 Node.js 18 下用npm install -g yarn安装的yarn，在切换到 Node.js 20 后是不可用的。这是特性而非缺陷，它保证了版本的纯净性。如果某个工具需要跨版本使用，需要在每个版本下单独安装。
• 项目级依赖： 始终优先使用npm install --save将依赖安装到项目的node_modules中，这能确保项目在任何装有正确 Node.js 版本的环境下都能运行。

5.2 与 WSL 的协作

如果你在 Windows 上使用 WSL（Windows Subsystem for Linux）进行开发，请注意：

• Windows 上的 nvm-windows 和 WSL 内的 Linux 环境是完全隔离的。
• 你需要在 WSL 的 Linux 发行版中，按照其原生方式（通常是使用curl或wget脚本）安装 Linux 版本的nvm。
• 两个环境管理各自的 Node.js 版本，互不影响。这实际上提供了更大的灵活性，你可以在 Windows 终端测试一个版本，同时在 WSL 中测试另一个。

5.3 定期维护

• 清理旧版本： 定期使用nvm list查看已安装版本，对于不再使用的旧版本，使用nvm uninstall <version>进行卸载，释放磁盘空间。
• 更新 nvm 自身： 关注nvm-windows的发布页面，可以下载新版本的nvm-setup.exe覆盖安装来升级 nvm。
• 备份settings.txt： 如果你自定义了镜像源等配置，可以备份此文件，重装系统或 nvm 后可以快速恢复。

5.4 集成到终端提示符

对于高级用户，可以将当前 Node.js 版本信息集成到终端提示符中（如 Oh My Posh、Starship 等）。这样，你无需输入命令就能一眼看出当前激活的版本，避免在错误版本下运行项目。这通常通过读取$env:NVM_CURRENT（PowerShell）或%NVM_CURRENT%（CMD）环境变量来实现。

通过本文，你不仅学会了在 Windows 上安装和使用 nvm 的具体步骤，更重要的是理解了其隔离管理、灵活切换的设计哲学。从今天起，你可以自信地为每个项目选择合适的 Node.js 版本，而无需担心环境冲突。当你下次遇到“这个项目需要老版本 Node”的情况时，只需一句nvm use即可轻松应对。