前段时间帮同事排查一个前端项目的构建问题发现他电脑上同时装着 Node 12 和 Node 18两个项目来回切的时候全靠手动改环境变量最后还是把系统搞得一团糟。其实这个场景在 Windows 开发机上太常见了老项目锁死的 Node 版本、新项目需要的高版本特性、npm 全局包在不同版本下互相污染……折腾到最后基本只剩一个解法——用 nvm 做 Node 版本管理。这篇文章就把我在 Windows 上从零安装 nvm、卸载旧 Node、配置 npm 的全过程完整整理一遍包括那些搜索频率极高的报错比如npm : 无法加载文件 ...\npm.ps1因为在此系统上禁止运行脚本一次性把坑提前排掉。1. 为什么 Windows 开发机上需要 nvm 这种版本管理器1.1 多项目多版本并存时手动装 Node 的代价很多人刚开始写前端的时候装 Node 都是去官网下一个最新版安装包一路 Next 完事。等到项目多起来问题就来了你维护一个三年前的老后台系统它依赖的node-sass在 Node 16 以上直接编译失败同时新接的工程化项目又要求 Node 20因为团队用的构建工具已经放弃低版本支持。这时候你怎么办卸载重装 Node一次两次还能忍三四次就会身心俱疲。而且手动卸载还经常卸不干净注册表、环境变量、npm 全局包里残留一堆东西。就算你勉强把版本切到老版本之前用高版本 npm 安装的全局工具又可能“失灵”构建产物莫名其妙变掉。我见过有人为了切换 Node 版本在系统里镜像了一份完整的 Node 目录然后手工改 PATH这种操作出错概率极高出错了都不知道从哪找。nvm 的核心价值就是把这个“切换版本”的动作压缩成一行命令。它把一个比较痛苦的运维问题变成一个日常开发里几乎无感知的小操作。在 Windows 上我们一般说的是nvm-windows也就是 coreybutler 开源的那个项目而不是 Linux/macOS 上常用的 shell 脚本版 nvm两者名字一样但使用方式和安装原理有区别后面会细说。1.2 nvm 的工作原理它到底替你做了什么要理解 nvm 为什么能切换版本就得先知道 Windows 下找 Node 命令的流程。你在终端敲node系统其实是在环境变量PATH里挨个目录找node.exe找到第一个就执行。所以谁的node.exe在 PATH 前面系统就用谁。nvm-windows 做的事很简单它在你机器上维护了一个目录默认是C:\Users\用户名\AppData\Roaming\nvm里面按版本号存着多个独立 Node比如v16.20.2、v18.20.4、v20.11.1每个目录都是完整的 Node 运行时。真正对外暴露的是一个“符号链接”类似快捷方式默认指向C:\Program Files\nodejs。当你执行nvm use 20.11.1nvm 就把这个符号链接重新指向v20.11.1目录然后刷新 PATH 里的条目。于是你再敲node -v实际执行的就是 20.11.1 版本。整个过程不需要卸载任何东西也不需要手动改环境变量你要做的只是敲一行命令。打个比方nvm 就像汽车变速箱的换挡杆每一个 Node 版本是不同挡位PATH 是传动轴换挡只需要拨一下杆子而不用把整个发动机拆下来换掉。想明白了这个道理后面遇到“切换失败”“版本不变”这类问题时排查思路就会清晰很多。1.3 什么情况下其实用不上 nvm说句公道话nvm 不是所有场景的银弹。如果你所在团队的 Node 版本完全统一新项目老项目都跑同一个 LTS 版本那确实没必要引入额外的工具如果你的开发环境已经完全容器化所有构建都在 Docker 里跑宿主机上的 Node 版本只是辅助那也可以不用 nvm再比如你只用一个脚手架工具生成项目完全不关心底层 Node 版本那 nvm 对你价值也不大。但只要你手上同时维护两个或以上、且 Node 版本要求不同的项目nvm 就值得装。另外有人提过mise这类更新的版本管理工具原理和 nvm 类似Windows 生态下也可以用但 nvm-windows 的社区覆盖率还是最高的碰到问题时搜到的解决方案也最多。新人上手我建议还是先用 nvm踩坑成本最低。2. 安装前先清场把旧 Node 环境卸干净2.1 为什么不清理就装 nvm一定会踩坑很多人图省事旧 Node 没卸载就直接装 nvm结果装完发现node -v永远显示的旧版本或者 nvm 切换成功了但 npm 命令还是指向老目录各种诡异问题。根因在于 nvm-windows 在切换版本时需要操作C:\Program Files\nodejs这个符号链接路径。如果这个目录里本来就有一个真实的node.exe旧安装器留下的nvm 要么创建符号链接失败要么被系统权限挡住。再加上旧的 PATH 里可能有写死的 Node 安装路径比如C:\Program Files\nodejs\或者D:\node\这些路径在 PATH 中的排列顺序如果比 nvm 生成的条目靠前系统就会优先执行旧目录里的 node造成 nvm“切了等于没切”。所以安装 nvm 之前把旧环境清理干净不是洁癖是必须。清理的工程量不大但每一步都别漏。2.2 卸载旧 Node 的完整清单先走正常程序卸载官方安装版打开“设置 - 应用 - 已安装的应用”找到 Node.js点卸载。如果你之前是用压缩包解压的绿色版 Node那卸载这步直接跳过进入手动清理。卸载完之后重点检查这几个残留位置有就删没有就跳过C:\Program Files\nodejs或D:\Program Files\nodejs如果目录还在直接手动删。这是最关键的残留它会让 nvm 的符号链接创建失败。C:\Users\你的用户名\AppData\Roaming\npmnpm 全局包的默认安装位置如果你有之前全局安装的工具删之前可以先跑一条命令备份清单后面重装会用到。C:\Users\你的用户名\AppData\Roaming\npm-cachenpm 的缓存目录也可以删。C:\Users\你的用户名\AppData\Local\Temp\npm-*临时文件顺手清理。C:\Users\你的用户名\.npmrcnpm 配置文件。如果你在里面手动配过 registry 镜像等建议看看内容确认不是自己需要的再删如果是公司私有源可以先复制到别处保留避免装完新环境后找不到源。如果你是重度用户可能还有 pnpm、yarn 的全局目录和缓存通常在AppData\Local\pnpm、AppData\Local\yarn按需清理。2.3 环境变量与注册表里的残留也要扫一遍卸载完还要检查环境变量这一步是很多人忽略的。按Win R输入sysdm.cpl回车切到“高级”选项卡点“环境变量”分别在“用户变量”和“系统变量”里检查两处Path中是否还有C:\Program Files\nodejs\、D:\node\、%APPDATA%\npm这类路径。是否存在NODE_PATH等自定义的 Node 相关变量。看到就直接删掉。特别注意用户变量里的Path和系统变量里的Path都有可能残留两个地方都要看不然你新建一个终端输入node -v可能又冒出来一个版本。注册表里的残留一般不用特意去动除非你虎到连 Node 安装日志都想清干净。想查的话可以搜索HKEY_LOCAL_MACHINE\SOFTWARE\Node.js有就删没有也没关系对实际使用影响不大。2.4 怎么确认已经卸载干净清理完成后新开一个终端窗口执行下面几条命令确认输出符合预期node -v npm -v正常情况是提示“不是内部或外部命令”或“无法识别”这就说明 PATH 里已经没有 Node 了。如果还是能输出版本号说明有残留路径没删干净继续排查。再补充一个确认命令where.exe node where.exe npm如果输出为空说明全清干净了。注意在 PowerShell 里不要简写成where node因为where在 PowerShell 里是别名行为完全不同加上.exe才是真正的文件定位命令。这个小细节我在现场帮人排查时踩过一并写出来。3. 下载与安装 nvm-windows以及必须提前做的基础配置3.1 选对安装包nvm-setup.exe 还是 nvm-noinstall.zip去 GitHub 搜coreybutler/nvm-windows进 Releases 页面会看到几个选项nvm-setup.exe安装向导版自动帮你把环境变量配好对新手最友好也是绝大多数文档推荐的方式。nvm-noinstall.zip绿色解压版解压后需要手动创建settings.txt手动配置环境变量适合喜欢折腾或者需要对多台机器做批量部署的人。nvm-setup.zip里面就是安装程序加一些说明文件作用和nvm-setup.exe一样。我建议一律用nvm-setup.exe把不必要的手动步骤交给安装器。版本号尽量选最新的稳定 release比如 1.1.12 等。老版本的 nvm-windows 在某些新 Node 版本的归档格式上兼容性一般容易在nvm install阶段出现解析失败的问题。3.2 安装路径的讲究避开 Program Files 和中文目录安装过程中会问你两个路径一个是 nvm 的安装目录比如默认的C:\Users\用户名\AppData\Roaming\nvm另一个是 nodejs 的符号链接路径默认是C:\Program Files\nodejs。很多教程让你直接保持默认但我个人强烈建议改一下。原因有两点。第一C:\Program Files下的目录默认需要管理员权限才能写入nvm 在切换版本时需要重建nodejs目录的符号链接频繁弹 UAC 提示框真的很烦而且在某些 CI 环境或受限账号下会直接失败。第二路径里最好不要有空格和中文虽然 nvm 自身能处理但很多老旧的构建工具、脚本对带空格的路径引号处理非常糟糕后续在 npm 全局包、node-gyp 编译原生模块时都可能踩到。我自己的习惯是装到D:\nvm符号链接路径设到D:\nodejs。如果你只有一个 C 盘那就设成C:\nvm和C:\nodejs。反正原则只有一个路径短、无空格、无中文、有写权限。安装时需要管理员权限因为 nvm 要创建符号链接和改系统环境变量这一步是躲不掉的。3.3 安装后的验证与 settings.txt 配置文件安装完成后新开一个终端执行nvm version能输出版本号就说明安装成功了。再执行nvm root能看到 nvm 当前使用的目录路径确认它指向安装时选择的目录。安装版一般会自动生成settings.txt位于 nvm 安装目录下。如果你用的是绿色解压版需要自己手动创建这个文件里面的核心配置是root: D:\nvm path: D:\nodejsroot就是 nvm 自己所在的目录path是 nodejs 符号链接要指向的目录。这两个路径必须和安装版保持一致否则 nvm 创建链接时会找不到位置。如果够细心会发现安装时指定的符号链接路径就是这里的path验证了 1.2 节讲的原理。3.4 下载 Node 太慢先把镜像源配置好nvm 安装 Node 时默认从 Node 官网下载压缩包。在国内网络环境下这个下载速度经常让人崩溃几十 MB 的包能下十分钟。解决办法是在settings.txt里配置镜像源root: D:\nvm path: D:\nodejs node_mirror: https://npmmirror.com/mirrors/node/ npm_mirror: https://npmmirror.com/mirrors/npm/node_mirror是 nvm 下载 Node 发行版的镜像地址npm_mirror是 nvm 从 Node 发行版中获取 npm 的镜像地址。改完保存新开终端或者重启终端再执行nvm install就能感受到速度提升。这里要提前划个重点node_mirror和npm_mirror是给 nvm 下载 Node 和 npm 本体用的跟后面讲到的 npm registry 完全不是一回事很多人第一次都会搞混。npm 的 registry 影响的是npm install拉取依赖包的来源而node_mirror影响的是 nvm 下载 Node 安装包本身。一个是给 nvm 用的一个是给 npm 用的别弄乱。4. 用 nvm 安装并切换 Node 版本以及高频报错处理4.1 nvm install 和 nvm use 的基本操作首先查看远程仓库里有哪些可用版本nvm list available输出的列表分左右两栏左边是 LTS 版本右边是当前版本很多人在这一步会困惑为什么同一排有两个版本号其实就是在提醒你先看 LTS除非你有超前体验新特性的需求否则选 LTS 最稳。安装指定版本nvm install 20.11.1如果你不指定具体版本号而是想装某个大版本里最新的可以这么写nvm install 20装完之后执行nvm use 20.11.1然后验证node -v npm -v这里有个特别容易踩的坑nvm install装完并不会自动切换到新版本必须手动执行一次nvm use才会生效。很多新手装完直接node -v发现还是原来的版本误以为没装成功其实只是忘了切。可以执行nvm list查看所有已安装的版本当前使用的版本前面会带一个*号一眼就能看出状态。4.2 PowerShell 提示禁止运行脚本npm.ps1报错的完整处理搜索统计里这个报错几乎常年霸榜npm : 无法加载文件 C:\Program Files\nodejs\npm.ps1因为在此系统上禁止运行脚本。有关详细信息请参阅 https:/go.microsoft.com/fwlink/?LinkID135170。出现这个报错的位置通常在 nvm 切换版本之后、第一次在 PowerShell 里执行npm的时候。根因和 nvm 关系不大是 Windows PowerShell 的脚本执行策略Execution Policy的问题。PowerShell 出于安全考虑默认把脚本执行策略设为Restricted也就是不允许执行任何.ps1脚本。nvm 在指向的 Node 目录里放了一个npm.ps1PowerShell 执行npm命令时优先去找npm.ps1然后就被拦截了。CMD、Git Bash 这类工具没有这个限制所以同样的环境在 CMD 里跑npm -v就正常在 PowerShell 里就报错这才误导了很多人以为是 nvm 装坏了。解决办法是修改当前用户的执行策略以管理员身份打开 PowerShell 执行Set-ExecutionPolicy -Scope CurrentUser RemoteSigned输入Y确认即可。RemoteSigned的含义是本地编写的脚本可以运行从互联网下载的脚本必须有签名。这个策略安全性适中日常开发完全够用。如果你只想对当前终端临时生效可以加-Process参数但重启终端后又要再设一次建议直接用CurrentUser级别。改完执行Get-ExecutionPolicy -List看看各级策略再跑npm -v验证是否正常。如果是公司统一管控的电脑执行策略可能被组策略锁住改CurrentUser会报错那就不要硬改直接用 CMD、Git Bash 或 WSL 里的终端来跑 npm 命令同样能绕开。4.3 切换到指定版本后node -v没变化的排查链路这是综合性的“假故障”症状五花八门但排查链路很统一。按顺序检查第一步确认你确实执行过nvm use且没有报错。nvm use执行完是有提示的比如Now using node v20.11.1 (64-bit)如果没有这个提示说明切换没成功。第二步检查当前终端是否是新开的。nvm use会修改 PATH 相关变量但已经打开的终端里环境变量不会自动刷新。正确姿势是切换后新开一个终端窗口再验证版本。第三步用where.exe node看实际解析到的路径。如果你输出了好几个路径比如一个在C:\Windows\System32一个在D:\nodejs说明 PATH 里有多个 Node 相关目录。这种情况下node -v显示的是 PATH 里排在前面的那个版本。需要回到sysdm.cpl里把多余的路径删掉只保留 nvm 生成的NVM_SYMLINK对应的路径。第四步检查符号链接D:\nodejs是否存在。如果这个目录不存在或它指向的版本目录不存在node命令就会落到 PATH 中其他目录或者直接提示找不到命令。修复办法很简单重新执行一次nvm use 版本或者用管理员权限执行nvm uninstall再重新nvm install。按照这个链路排查绝大多数“版本切不过去”的问题都能定位到根因。这套方法比盲目重装 nvm 有效得多。4.4 切换版本后 npm 全局包“消失”是怎么回事之前用 Node 16 的时候全局装了一堆工具切到 Node 20 之后执行这些工具名提示找不到命令。很多人以为环境坏了其实没坏这是 nvm 隔离机制的正常表现。npm 全局安装的包默认放在当前 Node 版本对应的目录下比如D:\nvm\v16.20.2\node_modules。切到v20.11.1之后系统去新的版本目录里找全局工具当然找不到。整个 nvm 的设计初衷就是要这种隔离每个 Node 版本拥有独立的全局环境可以避免不同版本间的包冲突。对老手来说这反而是优点但对习惯单一全局环境的人来说非常不习惯。我的应对方法是先切回旧版本执行npm ls -g --depth0查看装过哪些全局包保存到文本里再切到新版本按清单一个个重装。如果团队常用的全局工具就那么几个可以把安装命令写成一个脚本每次切换版本后执行一遍十几秒就能完成。也有人用修改.npmrc里prefix的方式把全局包统一放到一个独立目录这样所有版本共享一套全局包。这个思路可以用但要注意不同 Node 版本对全局工具的原生模块兼容性不同硬共享有时会引入新的问题不如隔离来得干净。5. 把 npm 调好镜像源、全局安装与 Path 配置5.1 npm registry 镜像源设置别和 nvm 的镜像搞混前面 3.4 节说过 nvm 的node_mirror现在说 npm 的 registry两者用途完全不同却经常被人当成一回事。npm 默认从官方源https://registry.npmjs.org/下载依赖国内网络环境时快时慢所以一般要换成国内镜像。查看当前 registrynpm config get registry设置镜像npm config set registry https://registry.npmmirror.com/这里必须提醒一句早年网上流传的https://registry.npm.taobao.org已经停止服务了现在官方维护的国内镜像域名是https://registry.npmmirror.com/依然用旧地址的人会直接碰到超时或证书错误。npm config set registry是写在用户目录下的.npmrc文件里的所以对所有项目都生效。如果某个项目临时要用官方源可以在项目根目录建一个.npmrc写registryhttps://registry.npmjs.org/项目内的.npmrc优先级高于用户级配置这是 npm 的配置优先级规则。如果改完镜像源想验证网络是否正常可以执行npm ping能返回PONG就说明连接正常。还有一件事值得做发布 npm 包之前把 registry 换回官方源因为npmmirror镜像默认只读你从它上面npm publish会失败或延迟同步。5.2 全局安装 npm 包的路径与常见权限报错全局安装是通过npm install -g 包名完成的。Windows 下npm prefix -g可以查看全局安装目录执行npm prefix -g在默认配置下输出的是当前使用版本的 Node 目录比如D:\nvm\v20.11.1。也就是说每个 Node 版本的全局包是独立的。如果你的NVM_SYMLINK指向的目录在C:\Program Files\nodejs这类受系统保护的位置全局安装时大概率会遇到权限错误比如EACCES: permission denied。解决办法有两个一个是让 nvm 的符号链接目录避开 Program Files另一个是全局安装时以管理员身份打开终端。前者一劳永逸后者治标不治本。常见的全局安装工具包括cnpm、pnpm、nodemon、typescript、eslint等。注意我特意把cnpm放进去是为了多提一嘴如果你的项目用了标准的 lock 文件我不建议日常使用cnpm来装依赖它对 lock 文件的处理逻辑和 npm 不完全一致容易在你没有注意到的时候改掉依赖树。国内环境可以把 npm 的 registry 指到镜像源日常命令始终保持npm ci或npm install比cnpm更稳妥。如果你改了全局安装位置比如在.npmrc里加了prefixD:\npm-global那记得把D:\npm-global加入 PATH否则执行全局安装的命令时系统找不到可执行文件。这种配置方式更贴合 nvm 的隔离设计但不建议新手一上来就搞等踩过默认方案的坑之后再试也不迟。5.3 npm 环境变量 Path到底要配哪几个路径打开环境变量编辑器nvm 安装器会自动帮你配置这些内容变量示例值作用NVM_HOMED:\nvm指向 nvm 程序所在目录NVM_SYMLINKD:\nodejs指向 nodejs 符号链接路径也就是当前 Node 版本对外暴露的入口Path追加项%NVM_HOME%;%NVM_SYMLINK%让系统能找到nvm.exe和node.exe这三项是 nvm 正常工作的基础不要随意删除。如果你自建了 npm 全局目录并配置了prefix还要把对应的prefix追加进Path这样全局安装的工具命令才能在任意目录下执行。有几点要特别说明Path中不要再手动添加某个具体版本的 Node 路径比如D:\nvm\v20.11.1。nvm 是靠NVM_SYMLINK这个符号链接动态切换的写死版本路径等于绕过 nvm会造成切换失效。系统变量里的Path和用户变量里的Path都会被系统解析配置项放哪个都行只要不重复。但如果你发现系统 PATH 中残留了旧 Node 路径优先级可能高于 nvm 的路径导致版本切换无效务必删掉。配置完后最好新开终端再测试。用where.exe node和where.exe npm验证一下它们指向同一个符号链接目录才是正常状态。5.4 发布 npm 包之前要确认的几件事搜索词里有“发布 npm 包”既然讲到了 npm 配置就一并把发布环节的常见坑列出来。发布前确认你的 npm 账号已经登录过本地npm login这一步会打开浏览器让你完成认证。登录状态可以用npm whoami查看。发布命令是npm publish这个命令在几百万开发者手里跑得很正常但发布前建议先做npm publish --dry-run它会列出本次发布将包含的文件清单避免把node_modules、.env这类文件意外传上去。发布前还要确认package.json里的name在 registry 上没有重名version不能和已发布的版本重复main、bin、files字段都要填写正确。实际发布中最常见的报错是403 Forbidden表示无权发布这个包名409 Conflict表示版本冲突以及你忘了把 registry 切回官方源导致npm publish一直超时或 404。解决办法分别是对应修改包名、递增版本号、临时切换 registry 到官方源。还有个小建议发布之前用npm view 你的包名确认一下包在公共仓库里是否已被占用省的把publishConfig折腾完才发现名字被人注册了。6. 如果要把 nvm 也卸载掉最后的兜底清理流程6.1 什么时候需要卸载 nvm以及卸载顺序有些人用了一段时间 nvm 后因为项目统一版本、公司安全策略或者单纯想回归简洁会把 nvm 卸载掉。卸载 nvm 比卸载普通软件更容易留尾巴因为 nvm 控制着符号链接和环境变量顺序反了会导致残留。正确的顺序是先用nvm list查看当前装了多少个 Node 版本然后对每个版本执行nvm uninstall 版本号把 nvm 管理的 Node 全部删掉。做完这一步再用 Windows 的“设置 - 应用”卸载 nvm-windows 本体。这个顺序的好处是nvm 在卸载 Node 版本时会同步处理 symlink 和相关目录避免后面手动清理时出现“符号链接指向不存在的版本目录”这种半瘫痪状态。如果你已经彻底乱了不用纠结直接删除 nvm 安装目录和NVM_SYMLINK指向的目录也可以但之后需要手动处理的环境变量残留会多一些。6.2 环境变量与符号链接的残留清理卸载完成不代表系统干净了。打开环境变量编辑器把以下内容逐一清理掉NVM_HOME整个变量删除。NVM_SYMLINK整个变量删除。Path中带nvm或nodejs的条目删除。接着检查符号链接目录。比如我之前使用D:\nodejs卸载后很可能还留着指向一个已删除版本的符号链接。在资源管理器里直接删除D:\nodejs这个“快捷方式/链接”或者在管理员终端执行rd D:\nodejs注意rd操作对象是符号链接或空目录时不会影响真正的文件安全度较高。再检查一下用户目录下的AppData\Roaming\npm、AppData\Local\npm-cache以及.npmrc按需清理。如果你之前自己改过 npm 的prefix那个目录也要处理。全部清理完之后新开终端执行node -v提示找不到命令就是清理干净了。6.3 回到官网安装器之前牢记一条铁律清理完 nvm想回归普通的官方 Node 安装方式那就去 Node 官网下载最新的 LTS 安装包一路 Next 安装。官方安装器会自动配置 PATH不需要你手动加环境变量这是它最大的优势。但这里有个坑如果你没有把 nvm 的NVM_SYMLINK目录删干净安装器又往同一个路径写入了新的 Node新旧文件可能打架。所以正式安装前把之前 nvm 相关的路径全部清理完。还有全局包的问题卸载 nvm 之前趁还能切换版本先在不同版本上执行npm ls -g --depth0把全局包清单导出来装完官方 Node 再统一重装否则那些工具就全没了。至于用官方 Node 安装器还是用 nvm 管理版本没有绝对的对错。我的观点是如果你日常只需要一个 Node 版本官方安装器省心省事只要有多版本需求nvm 这种工具就是刚需。两种方案都试过之后你会发现自己的需求其实很清楚。最后分享一个我的个人习惯每次nvm use之后先跑一遍node -v npm -v再开始干活整个过程一秒都不用但能省掉后面所有因为版本不对引发的莫名其妙报错。如果你也被 PowerShell 里的npm.ps1禁运脚本坑过把Set-ExecutionPolicy -Scope CurrentUser RemoteSigned这条命令记到自己的环境准备笔记里换台新电脑时照着敲一遍省得再来回查。工具这东西装好配置好只是开始真正顺手是一轮一轮踩坑踩出来的。