Windows下nvm-windows完全指南：安装、切换与镜像加速

我在 Windows 上折腾 Node.js 这些年前前后后换过几十个版本。有一阵子全靠官网安装包来回卸载重装结果就是各种环境冲突直到用上 nvm-windows 才算是真正解脱。这篇就把 Windows 下 nvm 的完整玩法一次讲清楚从安装、环境变量到日常切换版本、npm 全局配置、镜像加速再附带一堆常见坑的排查思路。刚接触 Node.js 的新手可以照着一步步做被多版本切换折磨过的老开发也能从中找到几个以前没注意过的细节。1. 为什么 Windows 开发者需要一个 Node.js 版本管理器1.1 多版本并存才是真实世界的常态前阵子团队接了个维护多年的老系统后台还在 Node 14 上跑新建的接口服务又要求 Node 18我自己想验证一个新特性还得切到 Node 22一台机器三个版本来回倒腾。如果没有 nvm这种需求根本没法体面地落地。没有版本管理器的时候大家的常规操作是从官网下载安装包装新版发现旧项目崩了卸载重装旧版下次新项目又急用新版本再卸载、再安装。运气好一两个小时运气差还得处理全局 npm 包全部重装、环境变量被改乱、node -v输出不对等一系列遗留问题。我见过有人一年下来系统里积了七八个 nodejs 临时目录全是这种循环卸载留下的“尸体”。nvm 的出现就是来终结这个局面的。它的本质是在系统里维护多个彼此隔离的 Node.js 版本通过一个软链接随时切换当前生效版本。装完 nvm 之后日常最长用的命令就三条nvm install装版本nvm use切版本nvm list看已装列表。整个操作全程命令行不碰图形界面也不碰环境变量编辑器干净利落。1.2 先分清 nvm 和 nvm-windows这里必须先提醒经常搜教程的读者网上大量 nvm 安装资料都是针对 macOS 和 Linux 的比如 curl 拉一个 shell 脚本再 source 一下那套东西在 Windows 上基本不能用。Windows 下我们说的是 nvm-windows一个用 Go 写的独立开源项目作者是 coreybutlerGitHub 仓库名就叫 nvm-windows。nvm-windows 的命令和正统 nvm 保持了很大程度的一致常见的有 list、install、use、uninstall、current、alias 这些所以如果你以前用过 Unix 系的 nvm迁移成本几乎为零。它的工作原理也值得理解一下安装时会指定一个 root 目录存放所有下载的 Node.js 版本同时创建一个软链接 NVM_SYMLINK默认是 C:\Program Files\nodejs。nvm use本质上是把这个软链接重新指向目标版本目录。理解这条链路后面排查任何 node 命令失效的问题都会特别有方向感。下载 nvm-windows 我建议只认准 GitHub Releases 页面文件名选 nvm-setup.exe。那些“一键安装 nvm”的第三方站点、网盘资源我是从来不信的装这类开发工具来源越干净越好。2. 动手安装前先把旧环境处理干净2.1 卸载旧版 Node.js这一步别偷懒如果你机器上已经装了 Node.js不管是官方安装包装的还是绿色解压版我建议先彻底清理再上 nvm。原因在于 nvm-windows 是通过修改 PATH 加软链接来接管 node 命令的如果系统里已经有一个真实的 C:\Program Files\nodejs两者会直接冲突。最常见的现象就是nvm use明明提示成功了node -v依旧输出旧版本。清理步骤并不复杂。先在“设置 - 应用”里正常卸载 Node.js然后检查这几个残留目录存在就删C:\Program Files\nodejs、C:\Program Files (x86)\nodejs、%APPDATA%\npm、%APPDATA%\npm-cache。最后打开环境变量编辑窗口把 PATH 里和 nodejs、npm 相关的历史项逐条删掉。全部操作完新开一个命令提示符敲node -v时如果提示“不是内部或外部命令”说明清干净了。提示部分第三方软件安装过 Node 的运行时清理时可能会连带影响它们。删 PATH 之前先把需要保留的项记下来。如果不确定哪条有用宁可多截图再动手。2.2 nvm-windows 安装过程记住两个关键目录双击 nvm-setup.exe 后安装向导第一屏要你选择 nvm 安装目录。我强烈建议不要沿用默认的 C:\Users\你的用户名\AppData\Roaming\nvm。一是路径带用户名和空格某些第三方脚本在找 node 路径时会出问题二是用户目录的权限模型容易给后面nvm use添乱。我自己习惯装在 C:\nvm 或者 D:\DevTools\nvm全英文、无空格、层级浅一劳永逸。第二屏是设置 Node.js 软链接目录默认 C:\Program Files\nodejs这个一般不用动。很多编辑器、IDE、全局工具默认就会去这个路径找 node保持默认最省心。不过要注意创建软链接需要写文件系统的权限所以安装包尽量右键“以管理员身份运行”杀毒软件如果拦截询问放行即可。装完以后新开一个管理员命令提示符输入nvm version能输出版本号就说明安装成功。这时候打开 C:\Program Files应该能看到 nodejs 这个条目上面带一个小箭头图标表示它是一个符号链接。如果这个目录不存在多半是安装时权限不够后面nvm use也会失败趁早重装。2.3 看一眼 settings.txtnvm 的配置文件是纯文本nvm 安装目录下有一个 settings.txt内容约长这样root: C:\nvm path: C:\Program Files\nodejs arch: 64 proxy: noneroot 是版本库目录path 是软链接目标arch 是默认架构。如果网络情况不好还能在这个文件里追加 node_mirror 和 npm_mirror 两行指向国内镜像源这个在后面第 4 部分会细说。修改这个文件之前先关掉所有正在使用 node 的终端不然可能出现读取到旧配置的问题。有一点需要提醒arch 只是默认架构安装时也可以临时覆盖比如nvm install 18.20.4 32就会装 32 位版本。当前主流的 Windows 都是 64 位保持默认 64 基本就行只有那种跑老工具链的人才可能用到 32 位那也没问题nvm 会同时管理两套架构的版本。3. 核心操作安装、切换与删除 Node.js 版本3.1 用 nvm list available 查版本再 nvm install 装版本安装版本之前先看一眼远端有哪些版本可用命令是nvm list available。它会按大版本分组把当前可安装的版本列出来还专门标了 LTS 和 Current。这个列表本质上是从 Node 官方版本索引抓取的偶尔会有点缓存延迟出现最新版比官方晚几个小时是正常的。确定好版本号后就执行nvm install比如nvm install 18.20.4。nvm 会去官网下载对应的 zip 包自动解压到 root 目录。这里我建议按三位完整版本号安装别只写大版本比如nvm install 18那样虽然也能自动解析到最新补丁版但不利于以后复现和排查。带不带 v 前缀都可以nvm install v18.20.4也能识别我习惯不带。日常搭配方面我的典型配置是一套 LTS 版本当主力开发环境一套当前最新版用来验证新语法再留一套老项目锁定的版本比如 14.21.3。三套并行走天下九成场景都覆盖了。3.2 nvm use 切换版本权限是最大的坑版本装好以后切换用nvm use 18.20.4成功后会提示 Now using node v18.20.4 (64-bit)这时候当前终端的node -v和npm -v都会变成对应版本。但这里有个几乎所有新手都会踩的坑nvm use必须管理员权限否则会提示“无法创建软链接”或者干脆静默失败。还有个更隐蔽的现象普通权限终端里nvm use显示成功了但node -v还是旧版。这是因为软链接没建成功PATH 指向的 C:\Program Files\nodejs 没有任何变化。遇到这种情况别研究别的了关掉终端右键“以管理员身份运行”重新打开再执行一次nvm use立刻正常。切完以后建议顺手敲nvm current确认也可以用nvm list看当前版本行会标 * 号或 current 字样。如果项目对 npm 版本也有要求再敲一下npm -v确认一番。因为不同 Node 版本自带的 npm 差异挺大Node 18 带的是 npm 9Node 20 带的是 npm 10版本不对可能导致某些工程脚本行为不一致。3.3 删除版本、设置默认版本和别名装的版本多了磁盘占用不说nvm list输出也会刷屏不用的版本定期清理是对的。删除命令是nvm uninstall 14.21.3唯一限制是当前正在使用的版本不能删必须先切走再删。这个设计倒是很合理防止手滑把正在运行的版本删了。还有一个需要养成的习惯是设置 default 别名。nvm-windows 刚装完默认不会自动选中任何版本新开终端时 node 不可用必须先nvm use一次。如果你希望每次打开终端就有可用的 node执行nvm alias default 18.20.4之后新终端会自动切换到这个版本。alias 命令还可以自定义名字比如nvm alias old 14.21.3之后nvm use old就能切。团队协作里我通常会在项目 README 里写清楚推荐的 Node 版本和切换命令然后建议队友用 alias 简化操作哪怕只有一两个人协作也能省下不少沟通成本。4. 配合 npm 的全局配置与镜像加速4.1 npm 镜像源配置国内开发者绕不开的一步Node.js 装好了如果 npm 默认源很慢开发体验会立刻打折扣。国内最常用的替代源是 npmmirror前身是淘宝镜像registry 地址是 https://registry.npmmirror.com。配置方式有两种。临时用一次可以在装包时加参数npm install --registryhttps://registry.npmmirror.com 包名。更推荐的是配置到全局npm config set registry https://registry.npmmirror.com之后这台机器的 npm 都走镜像。想确认当前源就执行npm config get registry想还原官方源就npm config set registry https://registry.npmjs.org。这里我想说点经验镜像源和官方源数据同步有延迟但 npm 生态下延迟影响很小。如果哪天镜像上确实找不到某个刚发布的包可以临时加--registry参数从官方源拉一次没必要来回切全局配置。另外公司内网如果有自己的 npm 私服把 registry 指到私服地址也一样步骤完全相同。4.2 全局包为什么一切换版本就“消失”读者问最多的一个问题我明明npm i -g装了全局包怎么nvm use切个版本包全不见了我们先看事实在 nvm-windows 环境里执行npm root -g和npm prefix -g会发现全局目录是 C:\nvm\对应版本号\node_modules 这种格式。也就是说每个 Node 版本都维护着自己独立的全局包目录版本之间完全不共享。这既是特性也算坑。特性在于不同版本可以用不同版本的全局工具互不污染坑在于你切到 Node 18全局装个 yarn再切到 Node 20yarn 命令又没了很容易给人一种“环境坏了”的错觉。想清楚这套机制后你就不会再慌。我的建议是开发工具类全局包按需安装项目依赖一律走本地 devDependencies。如果确实需要在多个版本上用同样的全局包先把全局包列表导出来切到新版本后批量安装。导出命令是npm list -g --depth0输出就是一行行“包名版本号”清洗一下喂给npm i -g就行。或者干脆只在 default 版本上维护一套完整全局包其他版本保持最小化。4.3 核对 node 和 npm 版本对应关系有人会遇到“新项目 npm install 报 engine 警告”或者“某个命令在新 Node 上不兼容”这往往和 npm 版本有关。升级当前 Node 版本自带的 npm用npm install -g npmlatest。这条命令只影响当前 Node 版本其他版本的 npm 不受影响这正是 nvm 隔离环境的好处。但注意别盲目升级到最新新版 npm 可能会要求 Node 版本不能太低。比如你在 Node 14 环境下把 npm 升到最新版很可能直接报错因为新版 npm 最低要求 Node 18。稳妥的做法是装与当前 Node 大版本匹配的 npm 版本比如 Node 18 用 npm9 或 npm10Node 20 用 npm10。敲npm install -g npm10这种显式指定大版本的写法可控性更强。我的原则就一句话Node 版本不变npm 够用就行别追求最新。5. 常见问题与排查技巧实录5.1 node -v 提示“不是内部或外部命令”出现这个提示按顺序排查三件事。第一安装完 nvm 后是否重开过终端PATH 不是实时刷新的新开的终端才会生效。第二系统里有没有可用版本先nvm list看列表再nvm current看当前如果 current 是空说明还没有任何版本被选中要么nvm use一次要么设置 default 别名。第三C:\Program Files\nodejs 这个软链接目录是否存在如果不在了多半是被安全软件清理了管理员身份nvm use一下会自动重建。这三步走完九成问题能解决。剩下极少数情况是 PATH 里本来就有旧的 nodejs 路径在 nvm 路径之前导致系统优先执行了旧 node清理 PATH 时把旧项删掉即可。5.2 nvm install 下载慢或卡住把下载源切到镜像nvm install默认从官方源下载国内网络下若经常卡在进度条最简单的方法是修改 settings.txt 加两行镜像配置node_mirror: https://npmmirror.com/mirrors/node/ npm_mirror: https://npmmirror.com/mirrors/npm/保存后重开终端再执行nvm install就顺畅多了。原理也不复杂nvm 下载的其实是 node-v18.20.4-win-x64.zip 这类压缩包默认从 nodejs.org/dist 拉改成镜像后只是换了个下载地址解压和安装逻辑完全不变。如果改完镜像还是很慢那就是镜像源高峰期拥堵换个时段或者手动把 zip 下载到 nvm 的 temp 目录再nvm install也能识别。5.3 报错 Node.js 版本 is not yet released or is not available这个报错英文原文大概是Error installing 20.14.0: Node.js v20.14.0 is not yet released or is not available。遇到它先别急绝大多数情况不是环境坏了而是版本号不存在。比如输成了 18.99.99或者远端索引还没同步最新版本。做法是nvm list available刷新索引看列表里到底有没有这个版本然后复制一个准确的版本号重装。如果索引一直不刷新可以删掉 nvm 目录下的缓存文件再试一般就正常了。5.4 VSCode 终端切了版本没变化VSCode 内置终端比较特殊它会缓存整个环境变量和 shell 状态nvm use切换后如果当前终端node -v没变不用怀疑 nvm 坏了直接重开一个新的集成终端或者重启 VSCode。高频切换的话也可以给 VSCode 配置多个终端 profile每个 profile 预先执行好nvm use启动即用。我自己就配了 default 和 legacy 两个 profile分别对应不同项目实测很省事。5.5 常见问题速查表现象主要原因快速解决node -v 提示不是命令PATH 未刷新或无版本生效重开终端nvm use 或设 defaultnvm use 显示成功但版本不变权限不足导致软链接失败管理员终端重新 nvm usenvm install 卡进度条官方源下载慢settings.txt 配 node_mirror/npm_mirror切换版本后全局包消失每版本独立全局目录按版本装包或导出列表批量安装VSCode 终端版本没变环境变量缓存重启 VSCode 或新开终端删除版本报错删除的是当前使用版本先 nvm use 其他版本再删6. 团队协作里的版本管理经验6.1 用 .nvmrc 固定项目 Node 版本团队项目最常见的版本灾难是“我这跑得好好的你那怎么不行”一查原因两个人的 Node 版本不一样。解决方案就是让项目带上 .nvmrc 文件写入一行版本号比如 18.20.4。很多工具链会自动读取这个文件比如 nvm 配合某些 shell 插件会直接切换到对应版本。在 Windows 下虽然没有那么顺滑的自动切换但这个文件至少是一份明确的项目声明配合 README 里写一句“先 nvm use再 npm install”团队里谁都不会踩空。6.2 把 nvm 纳入环境初始化脚本新电脑、新同事入职配置开发环境是最容易出乱子的一环。我会把 nvm 安装、Node 版本安装、npm 镜像配置打包成一份脚本或者文档粘贴即用。核心命令就那几条安装 nvm、nvm install指定版本、nvm alias default设置默认版本、npm config set registry设置镜像源。花半小时把这些沉淀成团队标准后续每台新机器都能在一个小时内进入开发状态这笔账怎么算都划算。6.3 我这些年用 nvm 的最终心得如果只让我留三条建议第一是“一台机器只维护一套 nvm别混装任何版本的官方 Node”第二是“全局包越少越好项目依赖放本地”第三是“切换版本就相信管理员终端里的输出别被普通终端的假象骗了”。这些年我在无数台 Windows 上配过 nvm从 Win7 到 Win11踩过的坑比文档多得多。但说到底nvm 的价值就在于它把“多版本并存”这种看似复杂的事变成了三条命令。你现在花半小时把它配好未来每年能省下的时间和烦躁情绪绝对是超值的。