在 Windows 上做 Node.js 开发最绕不开的一个工具就是 nvm。前阵子我同事的电脑就出了这么一档子事老项目原本跑得稳稳的结果某天 npm run dev 直接报错查了半天发现是 Node.js 版本被全局升级给顶上了而项目依赖只兼容旧版。我接手后第一反应就是这机器上怎么还没装 nvmnvm 的全称是 Node Version Manager听名字就知道它是专门用来管理 Node.js 多版本的工具。在 Windows 上我们一般用的是 nvm-windows 这个版本。它能让你在一台电脑上同时安装 Node.js 16、18、20、22 等多个版本并且随时一键切换哪个项目需要哪个版本就用哪个版本再也不用因为全局升级搞得鸡飞狗跳。这篇文章我会从为什么需要它、怎么装、怎么用、怎么排查问题这几个方面把我这些年踩过的坑和验证过的方案都写出来照着操作基本不会翻车。如果你是前端开发者、Node.js 后端开发者或者刚接触 Node.js 不知道怎么下手的新手这篇内容都很适合先收藏再实操。1. 为什么 Windows 开发者需要 nvm版本冲突的真实场景1.1 Node.js 版本错乱带来的日常崩溃先讲一个很典型的场景。很多公司里老项目用的还是 Node.js 12 或 14依赖里锁了 node-sass这个库对 Node 版本极其敏感Node 一升级就直接编译失败。另一边新项目可能一上来就要求 Node.js 18因为要用到新的 API 和构建工具。如果你只在电脑上装了一个全局的 Node.js那这两类项目就像水火不容的室友总有一个要闹脾气。再比如你全局装了某些 CLI 工具比如打包工具、脚手架工具这些工具本身依赖某个 Node 版本当你为了一个新项目把全局 Node 升上去之后这些工具可能就悄悄罢工了报错信息千奇百怪有时候根本不是代码的问题就是运行环境的锅。nvm 解决的就是这种“环境的混乱”。它让你电脑上可以同时存在多个 Node.js 版本每个版本都是一个独立的安装目录互不干扰。用哪个版本就在终端里执行一条命令切过去成本几乎为零。1.2 nvm-windows 和 Linux/macOS 上的 nvm 不是同一个东西新手最容易踩的第一个坑就是去网上搜 nvm 的安装教程搜出来一堆 Linux 上的操作方式结果在 Windows 上一跑全是错的。这里必须强调Windows 上使用的 nvm-windows和 Linux/macOS 常用的 nvmGitHub 上是 nvm-sh/nvm完全是两个项目。Linux/macOS 上的 nvm 是一个 shell 脚本通过修改当前 shell 环境来切换 Node 版本很多用法依赖 bash 或 zsh。Windows 上的 nvm-windows 是 coreybutler 用 Go 写的独立工具安装后会生成 exe 程序通过修改环境变量和创建符号链接来切换版本。两者的命令有些相似比如 nvm install、nvm use但工作机制完全不同。所以你在搜资料的时候尽量加上“Windows”或“nvm-windows”关键词否则可能照着教程折腾半天最后发现压根对不上。其实 Windows 上以前还有 nvmw、nodist 这些同类工具但生态和更新速度都不如 nvm-windows现在社区里用 nvm-windows 的人最多遇到问题也更容易搜到解决方案。1.3 它是怎么工作的符号链接 环境变量理解 nvm-windows 的原理能帮你少踩很多坑。简单来说它做的事情分两步第一它在自己的安装目录比如 C:\dev\nvm下为每个安装的 Node 版本单独建一个文件夹比如 v16.20.2、v18.20.4、v20.14.0里面分别是完整的 Node.js 运行文件。第二它维护一个“符号链接”symlink相当于 Windows 上的一个快捷方式指向你当前正在使用的那个版本。你在终端里执行 nvm use 20.14.0它就把这个链接重新指向 v20.14.0 文件夹。然后它把这个符号链接路径加入系统的 PATH 环境变量。这样一来你打开终端输入 node -v系统就会顺着 PATH 找到这个快捷方式再跳到目标版本目录里的 node.exe从而拿到正确的版本号。打个比方这个符号链接就像家里墙上挂的“当前钥匙示意图”nvm 每次切换版本就是把示意图换一张而门锁本身PATH 环境变量不用动。理解了这点你就能明白为什么安装目录里 Node 版本文件夹不能乱删为什么切换版本后有时要重启终端以及为什么某些环境变量冲突会带来诡异的问题。2. 安装前的准备工作与 nvm 完整安装流程2.1 先卸载旧版 Node.js别偷懒很多人装 nvm 之前电脑里已经装过一个 Node.js 了这时候如果直接装 nvm很容易出现 node 命令指向混乱的情况。原因很简单旧版 Node.js 通常安装在 C:\Program Files\nodejs这个目录本身就在系统 PATH 里而且路径优先级往往还不低。nvm 的符号链接会指向自己的 Node 版本目录两个路径同时在 PATH 里待着系统不知道该听谁的结果就是乱套。所以安装 nvm 之前我强烈建议先把旧的 Node.js 彻底卸载。具体步骤打开 Windows 设置进入“应用”或“应用和功能”找到 Node.js点击卸载。卸载完成后检查一下 C:\Program Files\nodejs 这个目录是否还存在如果存在手动删除。按下 Win R输入 sysdm.cpl在“高级”选项卡里点“环境变量”检查 Path 变量里有没有残留的 Node.js 路径比如 C:\Program Files\nodejs\有就删掉。顺手检查一下 %APPDATA%\npm 和 %APPDATA%\npm-cache 这两个目录如果里面是你之前全局安装的 npm 包可以留着后面还能用不放心的话也可以备份后清掉。这一步真的不能偷懒。我见过太多人装完 nvm 后 node 命令还是指向原来的旧版本最后排查半天发现就是卸载没卸干净。与其之后头疼不如一开始就先理清环境。2.2 下载安装 nvm-windows两个关键路径nvm-windows 的下载通常去 GitHub 仓库 coreybutler/nvm-windows 的 Releases 页面找一个叫 nvm-setup.exe 的安装包下载。下载好之后直接运行安装向导会引导你选择两个路径这一步是整个安装过程中最重要的决策点。第一个路径是 nvm 自身的安装目录也就是以后存放 Node.js 各版本的地方。第二个路径是 Node.js 符号链接的路径也就是以后 nvm use 之后node.exe 实际能通过快捷方式访问到的位置。这两个路径有一个共同的硬性要求不要包含空格也不要包含中文。比如 C:\Program Files\nvm 这种路径虽然向导默认可能建议但我强烈不建议用。因为 nvm-windows 在创建符号链接的管理员权限操作中对带空格的路径处理得并不好轻则切换版本报错重则符号链接失效node 命令直接找不到。我自己用过比较顺的路径规划是用途推荐路径nvm 安装目录C:\dev\nvm 或 D:\nvmNode.js 符号链接C:\dev\nodejs 或 D:\nodejs放在 D 盘的好处是万一系统崩了要重装开发环境可以少折腾一部分放在 C 盘的好处是读写速度相对稳定看你个人习惯。但无论如何路径里别有空格、别有中文。2.3 安装后的目录与环境变量检查装完 nvm-windows 后它会自动配置好环境变量主要涉及两个NVM_HOME指向 nvm 的安装目录。NVM_SYMLINK指向 Node.js 符号链接目录。同时PATH 里会加入 %NVM_HOME% 和 %NVM_SYMLINK%。你可以在环境变量设置里检查一下有没有多出这两条如果没看到说明安装过程可能出了问题或者需要手动补上。这时候打开一个全新的终端这一步必须新开窗口旧窗口读取不到最新的环境变量输入nvm version如果输出类似 1.1.12 这样的版本号说明 nvm 已经装好了。再看一眼 NVM_SYMLINK 指向的目录比如 C:\dev\nodejs目前大概率是不存在的这是正常的等你第一次 nvm use 指定某个版本后nvm 会自动创建这个符号链接。如果输入 nvm 提示“不是内部或外部命令”先别慌多半是环境变量没刷新或者安装时 PATH 没写进去重启终端再试还不行就手动把 NVM_HOME 和 NVM_SYMLINK 加进系统环境变量再重启一次终端。3. 用 nvm 管理 Node.js命令速查与实战流程3.1 高频命令速查表nvm-windows 的命令不多日常用到的就那么十来条我整理成了一份速查表建议收藏命令作用nvm version查看 nvm 自身版本nvm list列出本机已安装的 Node.js 版本带 * 的是当前使用版本nvm list available列出可以安装的 Node.js 版本从镜像源获取nvm install 20.14.0安装指定版本的 Node.jsnvm uninstall 20.14.0卸载指定版本nvm use 20.14.0切换到指定版本nvm alias default 20.14.0设置默认版本新开终端默认使用nvm on启用 nvm 管理的 Node.jsnvm off暂停 nvm 管理的 Node.jsnode 命令会暂时失效nvm root查看 nvm 的安装根目录nvm arch查看/设置 Node.js 架构64 或 32nvm node_mirror设置 Node.js 下载镜像nvm npm_mirror设置 npm 下载镜像这里面最常用的是 nvm list、nvm install、nvm use 这三个记住它们基本就能应付 90% 的日常需求。3.2 从零安装一个 Node.js 版本的完整流程假设你现在是一台全新的 Windows 电脑刚装好 nvm接下来要安装 Node.js。完整流程是这样的第一步先看看有哪些版本可以装nvm list available它会显示一段版本列表通常分成 CURRENT、LTS 等区域。LTS 是长期支持版本适合绝大多数生产环境CURRENT 是最新功能版本适合尝鲜但不建议在正式项目里用。第二步安装一个 LTS 版本比如nvm install 22.14.0这个过程会去 Node.js 官方或你配置的镜像源下载对应版本的压缩包然后解压到 nvm 安装目录。下载速度取决于网络环境如果很慢可以按照 3.3 节的方法配置镜像源。第三步切换到刚安装的版本nvm use 22.14.0如果安装成功且切换成功再运行node -v npm -v就能看到对应版本号了。到这一步你的 Node.js 环境就算正式跑起来了。第四步如果你希望以后每次新开终端都默认使用这个版本可以设置默认别名nvm alias default 22.14.0设置完之后新终端会自动加载默认版本省得每次手动切换。3.3 配置镜像源解决下载慢的问题nvm 安装 Node.js 的时候默认是从 Node.js 官方源下载的。国内网络访问这个源经常很慢有时候还会下载失败解决方法是给 nvm 配置一个国内镜像源目前比较主流的是 npmmirror淘宝镜像。在终端里执行nvm node_mirror https://npmmirror.com/mirrors/node/这样 nvm install 下载 Node.js 时就会走这个镜像。同理npm 也有自己的镜像源可以一并配好nvm npm_mirror https://npmmirror.com/mirrors/npm/配置完之后再用 nvm list available 查看版本列表速度一般会有明显提升。这里提醒一句配置镜像的命令在部分 nvm-windows 版本里会要求末尾带斜杠如果设置后不生效检查一下 URL 结尾有没有 /。另外如果你在公司网络环境下载还很慢可以考虑先用浏览器或下载工具把 Node.js 的 zip 包手动下载到本地然后放到 nvm 的临时目录里再 install 指定版本但这个方案操作门槛略高普通场景配好镜像就够用了。4. 全局配置npm、全局包与不同 Node 版本的关系4.1 每个版本都有独立的全局环境这一点很多人一开始没意识到我也是踩了坑才明白的在 nvm 管理下每个 Node.js 版本都有自己独立的全局 node_modules 目录。也就是说你在 Node.js 20.14.0 版本下执行 npm install -g pnpm那 pnpm 只存在于 20.14.0 这个版本的环境里。你切换到 Node.js 18.20.4 的时候pnpm 命令就找不到了需要重新装一遍。这不是 bug而是 nvm 的设计特点。因为不同 Node 版本的原生模块比如 node-sass、node-gyp 编译出来的东西是不能跨版本通用的如果全局包都放在一个公共目录版本一混就会出各种问题。独立隔离反而是更安全的设计。但这也带来了一个实际困扰如果常用五个版本难道每个版本都要把一堆全局 CLI 工具装一遍我的应对经验是选定一个主力 LTS 版本作为日常工作的默认版本。在这个默认版本里安装所有高频使用的全局工具比如 pnpm、yarn、nrm、typescript 等。其他版本按需安装只在特定项目需要时切过去并且只装必要的全局包尽量用 npx 临时调用。这样维护成本最低。如果你确实需要让多个版本共享同一套全局包也可以调整 npm 的 prefix 指向一个公共目录但这会带来原生模块跨版本兼容的隐患我不太推荐新手这么干。4.2 npm registry 与全局包的缓存配置npm 默认的官方仓库 registry 在国内访问也很慢装包时经常卡住。这个和 nvm 镜像源是两回事需要单独配置。查看当前 registrynpm config get registry如果返回的不是国内镜像可以设置成 npmmirrornpm config set registry https://registry.npmmirror.com/设置之后npm install 的速度通常会有明显改善。这里要注意registry 配置是跟着当前 Node 版本走的还是那个隔离逻辑切到另一个版本后可能需要再配一次。如果你希望所有版本都默认用这个 registry可以后续在用户目录的 .npmrc 里统一维护或者每切一次版本后执行一遍上面的命令。另外npm 的全局包安装目录和缓存目录也可以通过 npm config set prefix 和 npm config set cache 修改。如果你对自定义目录没把握保持默认就行。默认情况下全局包会装到当前 Node 版本目录下的 node_modules 里缓存会放在用户目录正常使用没有问题不需要强行改动。4.3 项目级 Node 版本管理.nvmrc 与 alias在团队协作中不同项目锁定不同 Node 版本很常见。很多项目会在根目录放一个 .nvmrc 文件里面写着一行版本号比如 20.14.0用来声明这个项目应该用哪个 Node 版本。Linux/macOS 上的 nvm 支持自动读取 .nvmrc进入目录后自动切版本。但 nvm-windows 原生不支持这个自动化行为进入项目目录后不会自动切换你需要手动执行nvm use等等nvm-windows 的 nvm use 不带参数时并不会读取 .nvmrc它会直接报错或提示缺少版本参数。所以实际的操作方式有两种方案一先 cat 或打开 .nvmrc 看到版本号然后手动 nvm use 20.14.0。方案二用 nvm alias default 20.14.0 把默认版本设成项目需要的版本进入项目前手动切过去。如果你希望更自动化可以写个小脚本或者用 PowerShell 的 prompt 钩子去读取 .nvmrc 再自动执行 nvm use但这属于进阶玩法小白先手动切也够用。我的习惯是把 .nvmrc 当作团队项目的“版本契约”进来先瞄一眼文件内容然后 nvm use 切过去全程十秒不到也没有多麻烦。5. 常见问题与排查技巧实录5.1 Error installing 24.20.0: is not yet released or is not available这个报错我见过不少人遇到包括我自己也踩过。看着像是网络问题或版本没发布实际上多半是版本号写错了或者镜像源里根本没有这个版本。Node.js 的版本号不是随便编的像 24.20.0 这种拼法在官方版本列表里根本不存在镜像源当然也找不到。解决办法是先运行 nvm list available看清楚当前可用的版本有哪些再挑一个真实存在的版本号去 install。如果你确信版本号是对的但依然报这个错那就要检查镜像源是否同步了最新的版本列表。npm 镜像和 Node 镜像有时会有短暂延迟特别是大版本刚发布的头几天。遇到这种情况可以等一两天或者临时把 node_mirror 切回官方源试试下载。5.2 nvm 命令不识别 / Exit code 1 / 权限问题这三个问题往往连在一起出现。nvm 命令不识别多半是安装后没有新开终端环境变量没刷新或者是 PATH 里确实没有 nvm 的安装目录需要手动补上 NVM_HOME 和 NVM_SYMLINK。Exit code 1 则是最典型的权限问题。nvm-windows 切换版本时创建符号链接需要管理员权限如果你在普通权限的终端里执行 nvm use就会看到类似“Exit code: 1”的错误。解决办法很简单右键点击 Windows Terminal 或 CMD选择“以管理员身份运行”然后再执行切换命令。这里还有个细节就算你不是用管理员终端某些版本的 nvm 也可能会弹出系统权限确认框你只有点了“是”才能正常切换。如果点了“否”就会报错。所以看到权限相关的报错先检查终端是不是管理员模式再检查 UAC 弹窗有没有被拦掉。5.3 切换版本后 node -v 还是旧版本这种情况通常不是 nvm 没切换成功而是系统里还有其他 node.exe 在捣乱。你可以运行where node这个命令会列出 PATH 中所有 node.exe 的位置。如果输出中除了 nvm 的符号链接路径还有其他路径比如 C:\Program Files\nodejs\node.exe那就说明旧版 Node.js 没卸载干净或者 PATH 顺序里旧路径排在了 nvm 前面。解决办法是彻底卸载或删除旧版 Node.js 的残留目录。打开环境变量把 nvm 相关的 %NVM_HOME% 和 %NVM_SYMLINK% 调整到 PATH 列表的前面确保系统优先找到 nvm 管理的 node。重启终端必要时重启电脑。还有一个小概率原因你当前终端是安装 nvm 之前开的环境变量快照停留在旧状态。这种只要完全关闭所有终端窗口重新打开一个全新的就行。记得是“完全关闭”如果用了终端的多标签页其他标签页也要一起关掉否则新环境变量可能不会加载。5.4 安装桌面开发工具时卡在 Installing Node.js dependencies现在很多桌面端的开发工具、编辑器插件、抓包调试软件安装时会在本地拉取或调用 Node.js 环境来完成依赖安装。如果你的系统里没有 Node.js或者 Node.js 版本太旧安装过程就会一直卡在 “Installing Node.js dependencies” 这一步看起来像死机了一样。这种情况其实不用去动那个卡住的软件而是先把系统的 Node.js 环境准备好。装好 nvm然后安装一个较新的 LTS 版本nvm install 22.14.0 nvm use 22.14.0再重试安装那个桌面工具大部分情况下问题就解决了。这类工具通常要求 Node.js 18 以上所以尽量别只装一个很老的版本。我自己的固定套路是默认版本永远是最新的稳定 LTS项目里有特殊要求再往低版本切这样系统级工具和项目开发互不耽误。5.5 高频问题速查表现象可能原因解决办法nvm 不是内部或外部命令环境变量未配置或终端未刷新新开终端检查 NVM_HOME、NVM_SYMLINK手动补 PATHnvm use 报 Exit code 1无管理员权限以管理员身份运行终端允许 UAC 弹窗node -v 仍是旧版本旧 Node.js 残留或 PATH 顺序问题where node 排查删除残留提升 PATH 中 nvm 优先级nvm install 下载很慢访问官方源速度慢配置 npmmirror 镜像安装版本提示 not yet released版本号写错或镜像未同步nvm list available 查询真实版本等待镜像同步npm install 超时npm registry 访问慢npm config set registry 为国内镜像切换版本后全局包消失每个版本全局环境隔离在常用版本中重装全局包或固定默认版本桌面工具卡在 Installing Node.js dependencies系统缺少 Node.js 或版本过旧安装并切换到 18 的 LTS 版本我在 Windows 上折腾 nvm 这几年最大的体会就是环境问题排查看似麻烦但绝大多数都是“卸载不干净”“权限不够”“PATH 顺序不对”这三个老牌原因反复出现。只要把安装前的准备工作做扎实后面至少能少走 80% 的弯路。最后再分享一个小技巧如果你在公司和个人项目之间频繁切换 Node 版本不妨把下面的 PowerShell 命令存成一个脚本放进 profile 里function Use-NodeVersion($version) { nvm use $version node -v npm -v }以后只要输入 Use-NodeVersion 20.14.0就能一次完成切换并验证版本省去重复敲命令的麻烦。工具始终是为人服务的怎么顺手怎么来。