做前端这些年我在 Windows 上装过无数次 Node.js。很长一段时间里电脑上只装一个版本项目要哪个版本我就手工换哪个看起来没什么问题直到同时维护两个老项目一个要求 Node 14一个要求 Node 20才发现这种“一个版本走天下”的做法有多麻烦。后来我把 Node 管理切到了 nvmWindows 下的体验才算真正顺起来。nvm 的全称是 Node Version Manager听名字就知道它是专门用来装 Node、切 Node、删 Node 的工具。它解决的问题很具体让你在同一台 Windows 电脑上同时保留多个 Node 版本哪个项目需要哪个版本敲一条命令就能切换。这篇文章我会从为什么要用、环境怎么收拾、安装配置到常见问题的排查完整走一遍新手可以照着抄老手也可以看看有没有漏掉的细节。1. 为什么要用 nvm 管 Node.js多版本并用才是常态1.1 一个老前端踩过的坑单版本安装的连锁问题先说我自己的经历。有段时间我电脑上装的是 Node 22用来跑一个新项目非常舒服。结果同事丢给我一个两年前的老后台项目dependencies 里还锁着 node-sass 4.xnpm install 一执行就是编译报错node-gyp 各种抱怨查到最后发现它只认 Node 14 或 16。我一开始还想着“升级依赖不就行了”真动手才发现老项目的升级成本远比你想象的高很多依赖只要一动整个构建链路都会跟着变。类似的场景在 daily 开发里太常见了公司内部工具链只兼容 Node 16个人开源项目又要用 Node 22 的新特性甚至有的 CI 环境还锁在 Node 18。你要同时跑这些项目靠“卸载重装”显然不现实因为每次切换都要重新下载安装包、重新配环境变量、重新装一遍全局工具一个操作失误还会把系统环境搞乱。所以我一直认为Node 版本管理器不应该是“进阶工具”而应该是 Windows 开发者的基础标配。它的定位就像给电脑装了一个“软件路由器”同一个版本的文件夹都存放在一个统一目录里你用哪条“线路”它就把哪条「接」到系统命令里。切换成本从“半小时重装”降到“一条命令搞定”这才是它最值钱的地方。1.2 nvm 与普通安装包的本质区别Windows 下大家说的 nvm严格一点应该叫 nvm-windows。它和 Linux 或 macOS 上那个由 nvm-sh 维护的 nvm 并不是同一个项目功能上也有细微差别但设计思路是一致的管理多套 Node互不干扰。普通安装包装 Node 的时候会把 node.exe 放到 C:\Program Files\nodejs然后往系统 PATH 里写一条固定路径。如果这时候再装另一个版本的安装包它要么覆盖原有文件要么安装到不同目录但 PATH 里只能生效一个最后终端里出现的 node 到底是哪个完全取决于 PATH 顺序和环境变量的残留情况。这也是很多 Windows 用户“明明装了新版node -v 还显示旧版”的根源。nvm-windows 的做法完全不同。它会创建两个核心目录一个是版本仓库比如 C:\Users\你的用户名\AppData\Roaming\nvm里面按版本号存放所有下载好的 Node另一个是固定的入口目录默认是 C:\Program Files\nodejs它只是一个“符号链接”指向当前用户选中的那个版本。你执行 nvm use 20.11.1 时nvm 会把这个链接重新指向版本仓库里的 20.11.1 目录。node 命令的真实路径没变但实际执行的文件变了。这种方式的好处很明显切换版本不需要重新下载版本之间互不干扰而且系统环境变量的配置极少只需要 PATH 里保留 C:\Program Files\nodejs 一条就够了。缺点也有就是它对权限比较敏感因为修改符号链接会写入到 Program Files 目录所以 nvm use 往往要以管理员身份运行后面我会详细说。2. 动手前先把环境洗干净卸载旧版与确认前提2.1 卸载旧版 Node.js 的完整流程如果你电脑上已经装了 Node.js 官方安装包那在装 nvm 之前建议先把它卸载干净。不是 nvm 不能和旧版共存而是留一个“旧版入口”在 PATH 里后患很多最常见的现象就是 nvm use 之后 node -v 还是旧版本排查半天才发现 PATH 里躺着另一个 node.exe。卸载流程分三步。第一步从系统里正常卸载按 Win I 打开设置进入“应用”-“已安装的应用”搜索 Node.js点卸载也可以直接用 winget uninstall OpenJS.NodeJS.LTS 这类命令来卸载。第二步手动清理残留目录重点检查这几个位置C:\Program Files\nodejsC:\Users\你的用户名\AppData\Roaming\npmC:\Users\你的用户名\AppData\Local\npm-cacheC:\Users\你的用户名\AppData\Roaming\npm-cache第三步检查环境变量。右键“此电脑”-“属性”-“高级系统设置”-“环境变量”在“用户变量”和“系统变量”的 Path 里看看有没有指向 nodejs 或 npm 的路径如果有就删掉。不要怕删错最多就是命令找不到后面 nvm 会重新配好。之所以要把环境收拾得这么干净是因为残留 PATH 是最消耗排查时间的坑。我帮同事处理过一个案例他 nvm list 显示的版本没问题但终端一执行 node -v 就跑出另一个版本最后发现是之前某个安装脚本把 Node 装到了 C:\nodejs并把这条路径加到了“系统变量”里排到了 nvm 前面。Windows 找命令是按 PATH 顺序从上到下找先找到哪个用哪个所以这个旧路径直接“截胡”了 nvm 的入口。2.2 检查环境变量和确认前提条件老环境清理干净后别急着安装先确认三件事。第一确认系统架构和版本。现在绝大多数 Windows 都是 64 位nvm-windows 也主要面向 64 位系统。你可以在 PowerShell 里执行 $env:PROCESSOR_ARCHITECTURE如果输出 AMD64 就是 64 位。32 位系统虽然也能装但很多新版本 Node 已经不再提供 32 位安装包了会白折腾一场。第二确认你的用户目录和权限。nvm 默认会往 C:\Users\你的用户名\AppData\Roaming\nvm 写文件同时往 C:\Program Files\nodejs 创建符号链接。后者需要管理员权限所以从安装到使用建议全程用管理员身份打开 PowerShell 或 CMD。我见过很多人卡在“nvm use 显示 success 但 node 没反应”十有八九是没用管理员终端。第三看下电脑里有没有其他包管理器或者 Node 管理工具。如果你之前用过 chocolatey 或者 scoop 装过 Node最好也一并卸载否则之后会出现“两个管理器抢同一个命令”的冲突。曾经有用户问为什么 nvm list 只有一个版本但 node -v 显示的版本不在列表里查到最后是 scoop 目录里躺着一个 node.exe优先级还比 nvm 高。确认完这些你的 Windows 环境就像一张白纸接下来装 nvm 才不会有一堆历史包袱来添乱。3. nvm 安装与基础命令从下载到第一次切版本3.1 下载 nvm-windows 与两种安装方式Windows 下安装 nvm推荐直接去 nvm-windows 的 GitHub Releases 页面下载安装包认准两个文件一个是 nvm-setup.exe适合大多数用户安装过程带图形界面会自动帮你配好环境变量另一个是 nvm-noinstall.zip适合喜欢手动控制的用户解压即用但需要自己写 settings.txt 和配 PATH。我一般建议新手直接用 nvm-setup.exe。安装的时候有几个细节要注意。一是安装路径尽量用默认的 C:\Users\你的用户名\AppData\Roaming\nvm别放到带中文或空格的路径里后面有些工具对路径兼容性并不好。二是它会提示你设置“Node.js Symlink”路径也就是刚才说的固定入口默认是 C:\Program Files\nodejs保持默认就行不要改成其他盘。三是安装完成后先别急着用关掉所有终端窗口重新以管理员身份打开 PowerShell这一步很重要因为终端的环境变量缓存不会自动刷新。如果你选 nvm-noinstall.zip手动配置也不复杂解压到一个目录比如 D:\nvm然后新建一个 settings.txt 文件内容至少包含 root 和 path 两行root 填文件夹路径path 填符号链接路径再把路径加入系统 PATH。只是这种方式容易配错新手默认推荐安装包方式就够了。装完以后在管理员终端里执行 nvm version如果能输出版本号说明安装成功了。这一步出了任何问题大概率是 PATH 没生效重启一次终端再试。3.2 常用命令实战安装、切换、查看、卸载nvm 的命令不算多日常用到的也就十个以内。我先列一个最常用的命令集合后面再用一段完整流程演示nvm list available # 查看远程可安装的 Node 版本列表 nvm install 20.11.1 # 安装指定版本全版本号要写完整 nvm use 20.11.1 # 切换当前使用的版本需要管理员权限 nvm list # 查看本机已安装的版本列表 nvm current # 查看当前正在使用的版本 nvm alias default 20.11.1 # 设置默认版本新开终端时自动启用 nvm uninstall 18.17.0 # 卸载指定版本 nvm purge # 清空所有 nvm 相关配置和版本演示一个典型场景项目 A 需要 Node 18项目 B 需要 Node 22。先在管理员终端执行 nvm install 18.17.0看到 install complete 之后执行 nvm use 18.17.0再 node -v 确认一下变成 v18.17.0然后继续 nvm install 22.11.0项目切到 B 的时候执行 nvm use 22.11.0node -v 就会变成 v22.11.0。整个切换过程只要几秒钟npm 也会跟着变成对应版本因为它和 node 是绑定在同一个目录下的。有一点我要特别提醒nvm use 之后当前这个终端窗口有效但如果你再开一个新的终端窗口它读取的可能是默认版本而不是你手工切换的那个版本。这就是为什么建议你一开始就执行 nvm alias default 设置好默认版本。我的习惯是默认装一个 LTS 版本平时无脑用特殊情况需要老版本就手工 nvm use。4. 让下载快起来镜像源与全局配置一次讲清4.1 配置 node 和 npm 镜像源很多人装完 nvm 后做的第一件事是 nvm install 某个版本结果卡在下载 node.exe 这一步速度慢得像蜗牛甚至直接卡死超时。这不是 nvm 的问题而是默认下载地址在国外网络环境不佳时天然会慢、会不稳定。解决办法是给 nvm 配置镜像源。nvm-windows 在安装时会自动生成一个 settings.txt 文件路径在 C:\Users\你的用户名\AppData\Roaming\nvm\settings.txt。用编辑器打开它在末尾加两行配置root: C:\Users\你的用户名\AppData\Roaming\nvm path: C:\Program Files\nodejs node_mirror: https://npmmirror.com/mirrors/node/ npm_mirror: https://npmmirror.com/mirrors/npm/node_mirror 负责 node.exe 的下载来源npm_mirror 负责 npm 包的下载来源。配好之后再次 nvm install速度会有明显提升之前动辄卡几分钟现在几十秒就能装完一个版本。这里有个容易踩的坑node_mirror 的路径末尾一定要带斜杠并且要写到 node 这个目录层不是写到 npmmirror.com 就结束。如果写错了nvm 拼接下载地址的时候会得到错误的 URL然后报一个“找不到文件”或“版本不可用”的错误看起来像是版本号的问题其实只是镜像地址配错了。安全起见你也可以遇到下载慢时才加镜像平时保留官方地址。我个人是直接长期配镜像的国内环境用起来更稳npm registry 我也是直接切到了国内镜像这个下面会说。4.2 修改 npm 全局安装目录与 registrynpm 默认的全局安装目录会跟随当前 Node 的安装位置也就是符号链接指向的那个真实目录。比如你用 nvm use 切到 22.11.0那么执行 npm install -g 任意包它会被装到 C:\Program Files\nodejs\node_modules 下面而这个目录在切换版本后会被重新指向另一个版本目录。后果用一句话说清楚你在 Node 18 下装的全局包切到 Node 22 后全部“消失”。这是 nvm 多版本管理下不可避免的隔离特性我不建议强行去改变它。你越想去修改 npm 的全局目录让所有版本共享一套全局包踩的坑越多因为很多包的命令行脚本和原生编译产物跟 Node 版本是强相关的硬要共享反而会出现诡异报错。更务实的做法是全局包尽量少装能用 npx 的就用 npx。运行 npx 某个包的时候它会临时下载并按需执行用完即走既不污染全局环境也不会因为切换版本而丢失。如果你的工作流里确实需要保留一些关键的 CLI比如某些老的构建工具那么在切到对应 Node 版本后重新安装一次就够了。关于 registry这个我还是建议改一下。执行这两条命令npm config set registry https://registry.npmmirror.com npm config get registry第一条把 npm 官方源切到国内镜像第二条用来验证是否生效。以后 npm install 下载依赖包的速度会快很多。如果你用的包是私有仓库里的或者公司内部有自己的 npm 源直接替换成你公司的地址就行。顺便提一句 npm cache。npm 默认缓存目录在 C:\Users\你的用户名\AppData\Local\npm-cache装包多了会占好几个 G。想清理就执行 npm cache verify 或者 npm cache clean --force这个跟版本管理没有直接关系但排查“npm 装包一直报错”的时候清一次缓存往往有奇效。5. 常见问题排查与避坑实录5.1 nvm 命令不识别、权限不足报错信息“nvm 不是内部或外部命令”或者 PowerShell 提示无法识别 nvm。这个问题排在首位因为它太经典了。排查分三步第一步看安装是否成功检查 C:\Users\你的用户名\AppData\Roaming\nvm 目录是否存在里面有没有 nvm.exe第二步看 PATH 里有没有对应的路径系统环境变量里应该有 C:\Users\你的用户名\AppData\Roaming\nvm第三步看终端窗口是不是安装前打开的如果是关掉重新打开。还有一种情况是 nvm.exe 存在但执行 nvm use 报错错误码是 5。这个错误在 Windows 下几乎可以断定是权限问题因为 nvm use 要重新创建 C:\Program Files\nodejs 这个符号链接而普通权限没有写 Program Files 的资格。解决办法很简单右键 PowerShell 或 CMD选择“以管理员身份运行”再执行一次 nvm use 就好了。记住一点nvm install 和 nvm list 一般不需要管理员权限但 nvm use 和 nvm uninstall 涉及符号链接变更基本都需要管理员权限。5.2 安装指定版本报错版本不可用其实不一定是版本问题nvm install 的时候有时候会碰到这种错误error installing 24.20.0: node.js v24.20.0 is not yet released or is not available。看到这个报错第一反应是不是版本号写错了确实是可能性之一。Node 的版本号必须写成 x.y.z 完整三段比如 20.11.1不能只写 20 或者 20.11也不能在后面随便拼什么后缀字符。但版本号没问题依然报这个错时优先怀疑镜像源。如果你在 settings.txt 里配置了 node_mirror但地址写错了或者镜像源还没同步到这个版本nvm 去抓取下载信息时就会找不到对应目录于是抛出一个“not yet released or is not available”的提示。这时候可以把 settings.txt 里 node_mirror 临时注释掉换回官方源再执行一次。也可以先去 nodejs.org/dist 页面手动看一眼这个版本是否存在确认之后再做判断。还有一个容易被忽略的原因是 nvm 缓存了版本列表。每次 nvm install 之前nvm 会向远程源请求版本索引如果你的远程请求失败或者设置了不合适的镜像索引可能就是旧的。这时候执行 nvm list available 看看列出来的版本是否和你预期一致能很好地判断是不是索引问题。实在不行重启终端再试一遍很多时候网络环境恢复了就好了。5.3 切换版本后 node -v 还是旧版本这个问题的排查思路我在前面提过但值得单独列出来因为它足够常见。执行 nvm use 显示 success 之后node -v 还是显示旧版本通常有几种情况。第一种当前终端没刷新环境变量。nvm use 改的是系统符号链接已经打开的终端窗口不一定能感知到变化尤其是用 PowerShell 的时候。解决方法是关掉终端重新打开再执行 node -v。Windows 终端的 PATH 读取时机是进程启动时不是命令执行时所以“重启终端”这个动作虽然简单但能解决一大半问题。第二种系统里存在其他 Node。执行 where node 看一下输出路径如果列出的路径不是 C:\Program Files\nodejs\node.exe说明有其他 Node 安装目录排在前面。这种情况要回到 PATH 环境变量里去清理把不相干的 Node 路径全部删掉只保留 nvm 使用的那个入口。第三种比较隐蔽是符号链接被意外破坏。你可以直接打开 C:\Program Files\nodejs 目录看看是否能进入、里面是不是一个真实的文件夹。如果它是一个损坏的链接或者目录内容为空那 nvm use 执行得再顺利也没用。我的处理办法是执行 nvm uninstall 当前版本再重新 nvm install 一遍让符号链接重新生成。5.4 切换 Node 版本后全局包消失你可能会遇到这种情况原本安装了 vue/cli、yarn 之类的全局工具用 nvm 切了一下 Node 版本再敲 yarn 就提示不是内部或外部命令这时候不用慌不是工具坏了也不是 nvm 出问题了而是全局包和 Node 版本绑定了。前面 4.2 说过全局安装目录会跟着符号链接指向的版本目录走切换版本相当于换了一套全新的“系统盘”原来的全局包自然不在里面。你只需要在切换后的版本里重新装一次全局包即可。如果你经常来回切换版本又不想每次重装我建议调整一下使用习惯全局只保留必须用命令行直接调用的工具其他的能指定版本就跑指定版本比如项目里用 pnpm 管理依赖的时候pnpm 版本其实可以锁定在 packageManager 字段里比依赖全局安装更可靠。这里多说一句有的同学为了让所有版本共享全局包会把 npm prefix 改成公共目录比如执行 npm config set prefix D:\npm-global然后把这个目录加进 PATH。这个方案在固定版本时好用但切版本后很容易出现“包的运行依赖找不到对应 version 的模块”的诡异问题。说实话我不推荐路径坑大于收益。做前端这些年我自己踩过几次最后都退回“按版本装全局包”的老路了。6. 我的日常使用工作流让 nvm 真正融入项目6.1 项目锁版本用 .nvmrc 固定 Node 版本有的人可能会问nvm 很好用但一个项目到底该用哪个版本总不能靠团队里每个人“感觉”吧解法很简单项目根目录放一个 .nvmrc 文件里面只写一行版本号比如 20.11.1。这个文件的作用是“声明”告诉团队这个项目应该在哪个 Node 版本下运行。nvm-windows 不像 Linux/macOS 的 nvm 那样能基于 .nvmrc 自动切换版本但你可以手动执行 nvm use它会读取当前目录的 .nvmrc 吗这里有个坑nvm-windows 的 nvm use 默认不读取 .nvmrc你需要先查看文件内容再手动敲版本号。如果你愿意折腾可以写一个小脚本读取 .nvmrc 之后执行 nvm use但我实际用下来觉得意义不大毕竟项目数量少的时候手动敲一条命令也没多费事。真正有用的是.nvmrc 把“版本约定”固化到了代码库里。团队协作时新同学 clone 下来直接看这个文件就知道该切哪个版本不用再在群里问“你用的 node 几”。包括后续配置 CI也可以直接读取 .nvmrc 里的版本号来安装对应 Node保证本地和流水线完全一致这才是多版本管理最有价值的地方。6.2 一套减少折腾的本机 Node 管理思路最后分享一个我目前正在用的方案不一定适合所有人但比较省心可以当参考。我在本机长期保留一个 LTS 版本作为默认比如当前长期维护的 Node 20 系列设置成 default alias。日常开发新项目、写脚本、跑一些通用工具全部走默认版本不用费心去想“今天该用哪个版本”。只有当某个老项目或者某个特殊依赖明确要求旧版本时才临时 nvm use 到对应版本项目做完再切回来。全局工具只安装两样东西一个是用得最勤快的包管理工具另一个是必要的脚手架 CLI其他一律用 npx。这样做的好处是切版本时痛感很小顶多重装一两个包需要大量全局包的操作反而会逼着我去思考“它能不能做局部依赖”。项目内部依赖用 package.json 锁死Node 版本用 .nvmrc 锁死。Windows 下配合 Docker 使用也是同理容器里的 Node 环境跟宿主机完全隔离本地 nvm 只管开发体验。这套流程跑了快两年再没出现过“换项目先重装 Node”这种事。工具就是拿来解决问题的nvm 帮我解决的多版本切换问题就值回安装花费的十分钟了。如果你也正在 Windows 上被各种 Node 版本问题折磨照着上面的步骤装一个然后从一个小项目开始切换试试应该很快就能感受到差别。