在实际的 Node.js 开发中你是否遇到过这样的场景接手一个老项目发现它依赖 Node.js 12而你本地环境是 Node.js 18直接运行会报错或者你需要同时维护一个使用 Node.js 16 的稳定项目和一个正在尝鲜 Node.js 20 新特性的实验项目。频繁地手动卸载、安装、配置不同版本的 Node.js 不仅繁琐而且容易出错导致开发环境混乱。这正是 Node Version Managernvm要解决的核心问题。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。如果没有版本管理工具你只能全局安装一个“折中”版本可能导致部分项目无法运行。为每个项目维护一个独立的虚拟机或容器资源消耗大。手动修改系统 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 安装前的准备工作卸载现有 Node.js打开 Windows 的“应用和功能”设置。搜索 “Node.js”将其卸载。这一步至关重要因为系统原有的 Node.js 会干扰 nvm 对环境变量的管理。同时检查并删除可能残留的 Node.js 安装目录如C:\Program Files\nodejs和用户目录下的npm、npm-cache等文件夹。确认系统架构在“设置”-“系统”-“关于”中查看“系统类型”确认是 64 位x64还是 32 位x86操作系统。大多数现代电脑是 64 位。2.2 下载与安装 nvm-setup.exe访问nvm-windows项目的官方发布页面。通常你应该选择最新的nvm-setup.exe安装程序。运行nvm-setup.exe。在安装过程中你会看到两个重要的路径配置nvm 安装目录 这是 nvm 自身的管理文件存放位置。默认是C:\Users\[你的用户名]\AppData\Roaming\nvm。建议保持默认。Node.js 符号链接目录 这是 nvm 创建的一个“快捷方式”目录用于统一指向当前激活的 Node.js 版本。默认是C:\Program Files\nodejs。这个目录需要管理员权限才能写入但安装程序会处理。保持默认即可。注意第二个路径符号链接目录是 nvm 工作的关键。nvm 会将你“正在使用”的 Node.js 版本的可执行文件通过一个名为nodejs的文件夹链接到这里并将此路径添加到系统PATH中。这样无论你在命令行何处输入node或npm命令都会指向当前激活的版本。完成安装。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 命令一览首先熟悉最核心的几个命令命令说明nvm list available查看所有可在线安装的 Node.js 版本包括 LTS 和最新版。nvm install version安装指定版本的 Node.js。例如nvm install 18.17.0或nvm install lts。nvm list或nvm ls列出本地已安装的所有 Node.js 版本。当前正在使用的版本前会有*标记。nvm use version切换到指定版本。需要管理员权限的终端。nvm current显示当前正在使用的 Node.js 版本。nvm uninstall version卸载指定版本的 Node.js。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 20nvm 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 允许你为特定项目目录设置默认版本。在项目根目录下创建一个名为.nvmrc的文本文件。在文件中写入你想要的 Node.js 版本号例如18.17.0。保存文件。之后在该项目目录下打开终端只需执行nvm usenvm 会自动读取.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显示的版本没有变化。原因可能没有使用管理员权限的终端。系统中可能存在其他位置的node.exe如旧版未卸载干净在PATH环境变量中排在 nvm 的路径之前。终端缓存了旧的路径信息。排查与解决确认使用管理员终端。执行where node命令。它会列出所有在PATH中找到的node.exe路径。第一个就是当前生效的。检查它是否指向C:\Program Files\nodejs或 nvm 的安装目录。如果指向错误检查系统环境变量PATH确保没有其他 Node.js 路径如C:\Program Files\nodejs\注意不是 nvm 的符号链接目录排在 nvm 相关路径之前。如果有编辑环境变量将其移除。关闭所有终端窗口重新以管理员身份打开。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 上使用 WSLWindows 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_CURRENTPowerShell或%NVM_CURRENT%CMD环境变量来实现。通过本文你不仅学会了在 Windows 上安装和使用 nvm 的具体步骤更重要的是理解了其隔离管理、灵活切换的设计哲学。从今天起你可以自信地为每个项目选择合适的 Node.js 版本而无需担心环境冲突。当你下次遇到“这个项目需要老版本 Node”的情况时只需一句nvm use即可轻松应对。