1. 为什么 Windows 上折腾 Node 版本第一步就得是 nvm1.1 不想再被“版本不对”支配我有一个老项目至今还锁在 Node 14 上仓库里有些历史包袱没法升级而最近在搞的新项目Vite 7 直接把 Node 版本要求写到了 20.19 或 22.12。以前见同事处理这种版本冲突都是点开 nodejs.org 重新下载安装包卸了装、装了卸折腾一天最后另一个项目反而跑不起来了。这其实不是操作不熟练而是 Windows 下的 Node 版本管理本身就有不少讲究。后来我在 Windows 上用 nvm 把 Node.js 的安装、切换、全局配置全理顺了再没被版本问题折腾过。这篇文章就完整记录我这套流程nvm 是什么、怎么装、怎么用、全局怎么配以及那些你迟早会遇到的坑。先交代一下背景知识。Node.js 是干什么的我尽量一句话说清它让 JavaScript 不再只能在浏览器里跑也能在服务端、命令行工具链里运行。日常开发里你跑 npm install、npm run dev、启动前端脚手架这些底层全是 Node.js。正因为它太常用版本的脾气也就格外重要。正式的版本号里奇数版本属于尝鲜版比如 17、19、21偶数版本一般是稳定路线18、20、22团队项目通常都会按照 LTS长期维护版本来锁环境。问题来了你的电脑上不可能永远只跑一个项目。老项目依赖 Node 14新项目要求 Node 20还有一堆内部工具要 Node 22。没有版本管理工具时常见的操作就是官网下载安装包覆盖安装装完再手动改 PATH。这操作偶尔一次还行次数多了必然翻车——装新版本覆盖了旧版本老项目的依赖就开始报错想切回去又得重新下载解压折腾到怀疑人生。我在最开始就是被这种“版本对不上”支配了很久后来才下定决心把 nvm 装起来。1.2 nvm 到底是谁Windows 上的 nvm 和 Mac/Linux 不是同一个东西这里必须先说清楚一个非常容易混淆的点很多教程直接写 nvm但 Linux/macOS 上的 nvm 和 Windows 上用的 nvm 不是同一个项目。Linux/macOS 那个是 nvm-sh/nvm本质是一个 shell 函数写在 .bashrc 或 .zshrc 里执行。Windows 上我们通常装的是 coreybutler/nvm-windows这是一个独立的 Windows 程序虽然命令风格长得像但实现机制完全不一样。所以你在网上搜到一条 Mac 上的 nvm 用法直接搬来 Windows 用很多时候会碰壁——比如某些配置项根本不存在或者路径格式完全对不上。我自己就被坑过一次照着某个 GitHub issue 里 Linux 的配置去改 settings.txt改完发现这个程序根本没有那个参数。Windows 的版本虽然也被大家叫 nvm但它更准确的叫法是 nvm-windows下载别下错看教程也认准这个项目。后面我提到的所有命令默认都是 nvm-windows 环境下的行为Linux 用户不要完全照搬。1.3 nvm-windows 的工作机制NVM_HOME、NVM_SYMLINK 和 PATHnvm-windows 的核心机制我用一句话概括它创建了一个“当前 Node 版本”的快捷入口切版本时只需要把这个入口重新指向另一个版本目录。安装 nvm 时它会要求你填两个路径第一个是 NVM_HOME用来存放 nvm 程序本身以及你将来安装的所有 Node 版本目录第二个是 NVM_SYMLINK它是一个链接路径平时你的 PATH 环境变量里加的其实是这个链接路径而不是某个具体版本。当你执行 nvm use 20.19.0nvm 就会把这个链接路径重新指向 NVM_HOME 里的 v20.19.0 目录。链接路径本身没有变所以 PATH 不需要反复修改新打开的终端里 node 命令会自动走新版本。理解了这个机制后面排坑会轻松很多。1.4 它真正解决掉的三个痛点把它放到实际工作里我觉得 nvm-windows 解决的核心痛点有三个。第一个是多版本共存一个项目一个版本不用卸载重装第二个是秒切版本切完新开终端立刻生效第三个是环境一致接新项目时看 .nvmrc 或 package.json 里记录的版本一条命令就能进入正确环境。对刚入门的开发者来说nvm 的另一个价值是“兜底”你不需要知道 Node 安装包到底装到了哪里也不需要手工维护 PATH出错了大不了 nvm uninstall 再 nvm install。这套工具的容错率比手动管理高太多了。2. nvm-windows 安装实操下载安装包、路径规划和管理员权限2.1 从哪里下载、下载哪个版本装 nvm-windows 之前第一件事不是下载而是检查本机有没有装过 Node。如果以前下载过官方安装包建议先把 Node 卸载干净再把 PATH 里和 nodejs 相关的路径清掉。这一步很多人容易忽略留着旧 Node 再装 nvm会经常遇到“明明 nvm use 切过去了node -v 还是老版本”这种鬼问题原因就是 PATH 里旧路径的优先级更高。下载渠道就是 coreybutler/nvm-windows 的 GitHub Releases 页面。它提供几种安装方式最常见的两个nvm-setup.exe 是安装版一路下一步配好nvm-noinstall.zip 是免安装版适合喜欢自己掌控环境的同学。新手我强烈建议用 nvm-setup.exe省心程度高很多。GitHub 下载速度看网络情况如果很慢国内一些镜像站也有同步下载后在本地核对一下文件体积和校验信息就行。需要说明的是安装 nvm 并不会自动安装 Node它只是一个“版本仓库管理员”Node 版本要靠后面的 nvm install 来安装。所以安装完 nvm 后执行 node -v 提示“不是内部或外部命令”是正常的这说明还没有任何 Node 版本被激活先不用慌。2.2 安装时的两个路径到底怎么填安装界面里最关键的就两个路径。第一个是 nvm 安装目录默认一般在 C:\Users\xxx\AppData\Roaming\nvm我建议改成纯英文无空格的路径比如 C:\dev\nvm。不是说不支持默认路径而是后面很多基于 Node 的命令行工具、脚本在解析带空格或带中文的路径时容易出现莫名其妙的问题。第二个路径叫做 Node.js Symlink也就是 NVM_SYMLINK默认是 C:\Program Files\nodejs。如果你不想每次切换版本都要管理员权限建议也改到用户目录下比如 C:\dev\nodejs。这两个路径选好后安装程序会自动写环境变量。即使你以前从未配置过环境变量这一步也不用你操心。唯一要注意的是安装目录要保证你有完全控制权。如果你用的是公司电脑账户权限受限安装过程可能会提示创建目录失败那就需要找管理员授权或者换一个用户目录来装。2.3 环境变量检查装完后最容易翻车的环节安装完成后打开一个新的终端先执行 nvm version 确认程序可用。如果提示找不到命令要么是安装程序没有把 NVM_HOME 写进 PATH要么是环境变量没有刷新。解决方法不复杂右键“此电脑”-“属性”-“高级系统设置”-“环境变量”在系统变量里确认有没有 NVM_HOME 和 NVM_SYMLINK并在 PATH 里确认包含了 nvm 安装目录。很多新手在这一步会犯一个错改完环境变量后继续在旧终端里敲命令。Windows 的环境变量改动不会对已经打开的终端生效必须新开一个终端窗口。这里我建议直接把 Windows Terminal 设为默认终端因为它新开窗口方便切换管理员模式也顺手。另外可以顺手运行 echo %NVM_HOME% 和 echo %NVM_SYMLINK% 验证环境变量输出不为空就说明配好了。2.4 管理员权限和 WSL 的边界问题再聊权限。nvm-windows 的版本切换依赖符号链接也就是在 NVM_SYMLINK 目录生成一个指向具体版本目录的链接。如果你把链接目录放在 C:\Program Files 这类系统目录下创建链接就需要管理员权限否则 nvm use 容易报错。常见的报错信息大约长这样“Could not create symlink”或者“Error while creating symlink”。解决办法有两个第一个是永远用管理员身份打开 PowerShell 或 CMD 再执行 nvm use第二个是把 NVM_SYMLINK 改到用户目录下比如 C:\dev\nodejs这样大多数情况下就不再需要管理员权限了。我个人的做法是用后者省得每次右键“以管理员身份运行”。还有一个经常被忽略的边界问题WSL 里的 Node 和 Windows 的 Node 是两套独立环境。如果你在 WSL 里也装了 nvm那是在 Linux 环境下的 nvm跟 Windows 上这个 nvm-windows 不通用。两边各自负责各自的不要在 Windows 终端里查 WSL 的版本也别指望 WSL 里的 node 命令能跟随 Windows nvm 切换。3. 高频命令实战装版本、切版本、删版本以及默认版本设置3.1 安装 Node.js 的正确姿势nvm 装好后安装 Node 就非常简单了。最省事的命令是nvm install lts这会安装当前最新的 LTS长期维护版适合大多数新项目。如果想装最新版用 nvm install latest。如果想指定某个具体版本比如团队的 CI 环境锁的是 Node 20.19.0nvm install 20.19.0这里有个小提醒版本号别带 v 前缀写 20.19.0 而不是 v20.19.0。带 v 前缀时nvm 偶尔会把版本名当成目录名的一部分导致后续 nvm use 时不匹配。在安装前想看看远端到底有哪些版本可选可以执行nvm list available输出里会列出当前可用的版本列表。这个命令特别适合用来排查报错比如你明明记得有个 24.20.0列表里却没有那就说明版本号不存在或者输入有误。3.2 切换版本nvm use 背后的真实行为安装完版本之后nvm 不会自动把它设为当前版本。你必须手动执行切换nvm use 20.19.0看到输出类似 Now using node v20.19.0 (64-bit) 之后再执行 node -v 确认。这里有个非常容易踩的细节如果你是在已经打开的旧终端里执行 nvm use切换后这个终端里的 PATH 信息可能还是旧的node -v 输出不一定是新版本。建议执行完 nvm use 后新开一个终端再验证。这不是 nvm 的 bug而是 Windows 环境下 PATH 更新的固有特性。nvm current 这条命令可以快速查看当前在用的版本比 node -v 更直接因为它不依赖 node 命令本身。当你的 Node 还没激活、node 命令都找不到的时候nvm current 依然能告诉你当前指向了哪个版本。3.3 版本列表管理list、uninstall、alias 与 default版本装多了以后管理就变得重要了。nvm list 列出所有已安装版本带星号的表示当前使用版本nvm list想删掉某个不再用的版本用 nvm uninstall 20.19.0。注意一个细节不要删除当前正在使用的版本否则 Windows 下的链接目录会指向一个不存在的目录导致 node 命令失效。稳妥的做法是先 nvm use 到别的版本再 uninstall 旧版本。设置默认版本也是一条命令的事nvm alias default 20.19.0这样每次新开终端系统会自动指向这个默认版本。对大部分只跑普通项目的开发者来说装上 nvm 加设好 default日常根本不需要频繁切换。我把最常用的命令整理成了一张表命令作用nvm version查看 nvm 自身版本nvm list列出本机已安装的 Node 版本nvm list available查看远端可安装版本nvm install version|lts|latest安装指定版本nvm use切换当前使用的版本nvm current查看当前使用的版本nvm alias default设置默认版本nvm uninstall卸载指定版本nvm root显示 nvm 的安装根目录nvm on / nvm off启用 / 停用 nvm 接管建议把这张表存到本地等需要查的时候不用再去翻文档。3.4 关于 .nvmrc 的真实使用体验很多现代项目会在根目录放一个 .nvmrc 文件里面写一行数字比如 20.19.0用来声明“这个项目应该用 Node 20.19.0”。Linux/macOS 的 nvm 可以在项目目录下直接执行 nvm use自动读取 .nvmrc但 nvm-windows 默认没有这个自动读取能力nvm use 不带参数不会去读 .nvmrc。所以 Windows 下的实际做法是每次进入项目自己看一眼 .nvmrc 里的版本号手动执行 nvm use 20.19.0。虽然麻烦一点但只要你形成了习惯也就几秒的事。如果你特别在意这层体验也可以考虑把它交给更现代化的替代工具比如 fnm 或者 volta。fnm 在 Windows 上支持从 .nvmrc 自动读取版本volta 则更进一步会根据 package.json 里声明的工具链自动选择。不过这些工具的配置机制和 nvm-windows 又不一样刚上手的人不要同时装好几个选一个用熟最重要。我的建议是先把 nvm-windows 的这套命令玩熟真觉得自动读取 .nvmrc 是刚需再考虑换工具。4. 装完 Node 别急着跑项目先把 npm 这套全局配置理顺4.1 换一个下载够快的 npm 镜像源每次新装完 Node我做的第一件事不是跑项目而是先配 npm 镜像和全局路径。npm 是 Node 自带的包管理器正常情况下你执行 npm install 时它默认去官方源拉包。官方源在国外国内网络环境下一不小心就是几十秒的等待或者干脆超时。所以先把 registry 换成 npmmirror 的镜像npm config set registry https://registry.npmmirror.com/执行完可以用 npm config get registry 验证。如果你只想在某个项目里临时用一次镜像也可以这样npm install --registryhttps://registry.npmmirror.com但全局配置显然更省心。这个配置最终会写进 C:\Users\你的用户名.npmrc 文件属于用户级配置对所有项目生效。我印象很深的一次经历一个前端项目几十个依赖没配镜像时 npm install 卡了快十分钟配置完镜像后两分钟装完。项目能不能跑还是小事关键是反复等超时特别消磨耐心所以这一条无论如何都要排在最前面。4.2 全局包路径和缓存路径多版本共用的关键接下来是全局包路径。默认情况下npm 会把全局命令行工具安装到当前激活的 Node 版本目录附近。你可以用 npm prefix -g 查看当前全局安装前缀用 npm root -g 查看全局 node_modules 的位置。问题在于当你用 nvm 切换了 Node 版本全局工具的路径可能跟着变化上一秒还能用的全局命令下一秒就找不到了。我推荐的做法是把全局包统一安装到一个和 Node 版本无关的固定目录。先在 D 盘建两个目录比如 D:\dev\npm 和 D:\dev\npm-cache然后执行npm config set prefix D:\dev\npm npm config set cache D:\dev\npm-cache配置完以后再用 npm install -g 安装任何工具都会写到 D:\dev\npm\node_modules 里生成的命令行脚本也会放在 D:\dev\npm 下。接下来手动把这个目录加进系统环境变量 PATHD:\dev\npm加完新开终端全局安装的 npm 命令就能稳定识别再也不受 nvm 切换版本的影响。要注意的是这个方案带来的代价是所有 Node 版本的全局包是共享的如果某个全局工具对不同版本的 Node 兼容性差异很大切换版本后可能需要重新安装或升级它。但对大多数工具来说共享远比反复安装省心。我个人的全局工具列表里包括 pnpm、yarn、rimraf、http-server 这类通用工具共享了两年多没出过什么大问题。4.3 corepack 与包管理器交给工程体系而不是全局在全局工具里pnpm 和 yarn 的地位比较特殊。它们本身也是 npm 包但实际项目中我们更希望包管理器的版本跟着项目走而不是全机器一个版本。新版 Node 内置的 corepack 就是干这件事的它可以根据 package.json 里的 packageManager 字段自动启用对应版本的 pnpm 或 yarn。如果你想用新版 Node又不想手动全局装 pnpm可以打开 corepackcorepack enable特别提示某些新版 Node 发行版不再默认捆绑 corepack需要单独安装。如果你执行 corepack enable 提示找不到命令去查一下对应版本的安装说明就行。这里也顺便回应一个常见的现象很多桌面开发工具尤其是基于 Electron 的一些工具在安装或启动时会卡在“installing node.js dependencies”大概率就是本机 Node 环境太乱导致的。要么是全局 prefix 不在 PATH 里要么是某个全局包被 Node 版本切换带走了。把 4.1 和 4.2 的配置做好之后这类问题基本能消掉一大半。5. 用 nvm 两年踩过的坑从版本对不上到 npm 消失的排查链路5.1 坑一nvm use 成功了node -v 却还是旧版本先说最常见的一个坑nvm use 明明成功了但 node -v 还是旧版本。遇到这个问题第一步不是重装而是按顺序排查。先新开一个终端排除 PATH 缓存问题。然后运行 where.exe node看 node 命令实际来自哪个路径。如果输出里有 C:\Program Files\nodejs\node.exe 之外的其他路径而且那个路径下有旧 Node就说明 PATH 里旧路径的优先级更高。解决办法是把旧 Node 的路径从 PATH 里删掉或者把它移到 NVM_SYMLINK 之后。如果 where.exe node 显示的就是 NVM_SYMLINK 路径但版本还是旧值那就是链接没有创建成功。去 NVM_SYMLINK 目录里看一眼确认它是不是一个带箭头的链接目录。如果不是用管理员权限重新执行 nvm use。我碰到过一次很奇怪的情况目录存在但里面没有 node.exe原因是之前安装 nvm 前没卸载干净链接被一个残留的空目录挡住了。把那个空目录删掉再 nvm use 就好了。5.2 坑二nvm install 报 “not yet released or is not available”第二个坑就是标题里的那个经典报错我把它完整写出来Error installing 24.20.0: Node.js v24.20.0 is not yet released or is not available这个报错字面意思是“这个版本还没发布或不可用”。网上能看到这个报错原因通常是两种版本号打错了或者输入了一个当前远程列表里不存在的版本。比如 Node 24 的版本线里根本没有 24.20.0自然装不了。遇到就执行 nvm list available 看真实版本号再重新执行 nvm install 就解决了。另一个隐藏原因是 nvm install 后跟大版本号这种写法比如 nvm install 24nvm-windows 不一定支持这种简写它可能去找一个完整版本号找不到就报错。所以我的建议是永远写完整的小版本号比如 24.2.0。还有一点nvm-windows 缓存了一份远端版本列表如果你本地列表太旧刚发布的新版本可能看不到。常规操作就是更新 nvm-windows 到最新版或者在 settings.txt 里配好 node_mirror 指向国内镜像源然后重新执行 install。5.3 坑三切换版本后 npm 没了全局命令也找不到第三个坑切换了 Node 版本之后npm 命令直接没了或者全局命令行工具找不到了。npm 是随 Node 一起走的理论上切了 Node 版本npm 也会跟着切换。如果 node -v 正常但 npm -v 报错先检查 NVM_SYMLINK 指向的目录里有没有 npm.cmd。如果没有可能是安装了精简版 Node 或者解压不完整重新执行一次 nvm uninstall、nvm install 就行。如果 npm 还在但全局命令找不到了那就是我前面说的全局 prefix 路径问题。用 npm prefix -g 看一眼当前全局前缀再对照 PATH 里有没有这个路径。如果你之前没有按 4.2 配置固定 prefix那切换版本后默认前缀跟着变了之前全局安装的工具自然就“消失”了。解决方法就是统一配置 prefix 并加入 PATH一次性解决问题。5.4 坑四在 Git Bash 里切版本为什么不生效第四个坑比较隐蔽在 Git Bash 里执行 nvm use 后版本切换不完全生效。Git Bash 是很多 Windows 开发者必备的终端但 nvm-windows 是通过修改链接目录来切版本的而 Git Bash 对 Windows 路径有一套自己的转换规则加上 MSYS 环境变量处理方式不同经常出现“明明 use 了node -v 还是旧版本”的情况。遇到这种问题最直接的办法是在 Git Bash 里新开一个窗口或者临时用 cmd /c nvm use 20.19.0 node -v 来执行。我个人更建议Windows 下用 nvm-windows 时日常操作还是以 PowerShell 或 Windows Terminal 为主Git Bash 用来跑 shell 脚本就好了两边工具各干各的别硬凑。最后再分享一个我个人的小习惯每接一个新项目第一件事是看 package.json 里的 engines 字段、根目录的 .nvmrc、以及包管理器声明确认 Node 版本范围然后 nvm install 加 nvm use。这套流程跑顺之后nvm 的存在感会变得很低——基本就是一条命令的事。工具的意义也正在于此不是让你天天研究它而是让它安静地待在背后你要用的时候它一直在。如果你现在还在用卸载重装的方式折腾 Node 版本我真的建议花十几分钟把 nvm 装好这个投入的回报率太高了。
Windows下用nvm管理Node版本：安装、切换与避坑指南
1. 为什么 Windows 上折腾 Node 版本第一步就得是 nvm1.1 不想再被“版本不对”支配我有一个老项目至今还锁在 Node 14 上仓库里有些历史包袱没法升级而最近在搞的新项目Vite 7 直接把 Node 版本要求写到了 20.19 或 22.12。以前见同事处理这种版本冲突都是点开 nodejs.org 重新下载安装包卸了装、装了卸折腾一天最后另一个项目反而跑不起来了。这其实不是操作不熟练而是 Windows 下的 Node 版本管理本身就有不少讲究。后来我在 Windows 上用 nvm 把 Node.js 的安装、切换、全局配置全理顺了再没被版本问题折腾过。这篇文章就完整记录我这套流程nvm 是什么、怎么装、怎么用、全局怎么配以及那些你迟早会遇到的坑。先交代一下背景知识。Node.js 是干什么的我尽量一句话说清它让 JavaScript 不再只能在浏览器里跑也能在服务端、命令行工具链里运行。日常开发里你跑 npm install、npm run dev、启动前端脚手架这些底层全是 Node.js。正因为它太常用版本的脾气也就格外重要。正式的版本号里奇数版本属于尝鲜版比如 17、19、21偶数版本一般是稳定路线18、20、22团队项目通常都会按照 LTS长期维护版本来锁环境。问题来了你的电脑上不可能永远只跑一个项目。老项目依赖 Node 14新项目要求 Node 20还有一堆内部工具要 Node 22。没有版本管理工具时常见的操作就是官网下载安装包覆盖安装装完再手动改 PATH。这操作偶尔一次还行次数多了必然翻车——装新版本覆盖了旧版本老项目的依赖就开始报错想切回去又得重新下载解压折腾到怀疑人生。我在最开始就是被这种“版本对不上”支配了很久后来才下定决心把 nvm 装起来。1.2 nvm 到底是谁Windows 上的 nvm 和 Mac/Linux 不是同一个东西这里必须先说清楚一个非常容易混淆的点很多教程直接写 nvm但 Linux/macOS 上的 nvm 和 Windows 上用的 nvm 不是同一个项目。Linux/macOS 那个是 nvm-sh/nvm本质是一个 shell 函数写在 .bashrc 或 .zshrc 里执行。Windows 上我们通常装的是 coreybutler/nvm-windows这是一个独立的 Windows 程序虽然命令风格长得像但实现机制完全不一样。所以你在网上搜到一条 Mac 上的 nvm 用法直接搬来 Windows 用很多时候会碰壁——比如某些配置项根本不存在或者路径格式完全对不上。我自己就被坑过一次照着某个 GitHub issue 里 Linux 的配置去改 settings.txt改完发现这个程序根本没有那个参数。Windows 的版本虽然也被大家叫 nvm但它更准确的叫法是 nvm-windows下载别下错看教程也认准这个项目。后面我提到的所有命令默认都是 nvm-windows 环境下的行为Linux 用户不要完全照搬。1.3 nvm-windows 的工作机制NVM_HOME、NVM_SYMLINK 和 PATHnvm-windows 的核心机制我用一句话概括它创建了一个“当前 Node 版本”的快捷入口切版本时只需要把这个入口重新指向另一个版本目录。安装 nvm 时它会要求你填两个路径第一个是 NVM_HOME用来存放 nvm 程序本身以及你将来安装的所有 Node 版本目录第二个是 NVM_SYMLINK它是一个链接路径平时你的 PATH 环境变量里加的其实是这个链接路径而不是某个具体版本。当你执行 nvm use 20.19.0nvm 就会把这个链接路径重新指向 NVM_HOME 里的 v20.19.0 目录。链接路径本身没有变所以 PATH 不需要反复修改新打开的终端里 node 命令会自动走新版本。理解了这个机制后面排坑会轻松很多。1.4 它真正解决掉的三个痛点把它放到实际工作里我觉得 nvm-windows 解决的核心痛点有三个。第一个是多版本共存一个项目一个版本不用卸载重装第二个是秒切版本切完新开终端立刻生效第三个是环境一致接新项目时看 .nvmrc 或 package.json 里记录的版本一条命令就能进入正确环境。对刚入门的开发者来说nvm 的另一个价值是“兜底”你不需要知道 Node 安装包到底装到了哪里也不需要手工维护 PATH出错了大不了 nvm uninstall 再 nvm install。这套工具的容错率比手动管理高太多了。2. nvm-windows 安装实操下载安装包、路径规划和管理员权限2.1 从哪里下载、下载哪个版本装 nvm-windows 之前第一件事不是下载而是检查本机有没有装过 Node。如果以前下载过官方安装包建议先把 Node 卸载干净再把 PATH 里和 nodejs 相关的路径清掉。这一步很多人容易忽略留着旧 Node 再装 nvm会经常遇到“明明 nvm use 切过去了node -v 还是老版本”这种鬼问题原因就是 PATH 里旧路径的优先级更高。下载渠道就是 coreybutler/nvm-windows 的 GitHub Releases 页面。它提供几种安装方式最常见的两个nvm-setup.exe 是安装版一路下一步配好nvm-noinstall.zip 是免安装版适合喜欢自己掌控环境的同学。新手我强烈建议用 nvm-setup.exe省心程度高很多。GitHub 下载速度看网络情况如果很慢国内一些镜像站也有同步下载后在本地核对一下文件体积和校验信息就行。需要说明的是安装 nvm 并不会自动安装 Node它只是一个“版本仓库管理员”Node 版本要靠后面的 nvm install 来安装。所以安装完 nvm 后执行 node -v 提示“不是内部或外部命令”是正常的这说明还没有任何 Node 版本被激活先不用慌。2.2 安装时的两个路径到底怎么填安装界面里最关键的就两个路径。第一个是 nvm 安装目录默认一般在 C:\Users\xxx\AppData\Roaming\nvm我建议改成纯英文无空格的路径比如 C:\dev\nvm。不是说不支持默认路径而是后面很多基于 Node 的命令行工具、脚本在解析带空格或带中文的路径时容易出现莫名其妙的问题。第二个路径叫做 Node.js Symlink也就是 NVM_SYMLINK默认是 C:\Program Files\nodejs。如果你不想每次切换版本都要管理员权限建议也改到用户目录下比如 C:\dev\nodejs。这两个路径选好后安装程序会自动写环境变量。即使你以前从未配置过环境变量这一步也不用你操心。唯一要注意的是安装目录要保证你有完全控制权。如果你用的是公司电脑账户权限受限安装过程可能会提示创建目录失败那就需要找管理员授权或者换一个用户目录来装。2.3 环境变量检查装完后最容易翻车的环节安装完成后打开一个新的终端先执行 nvm version 确认程序可用。如果提示找不到命令要么是安装程序没有把 NVM_HOME 写进 PATH要么是环境变量没有刷新。解决方法不复杂右键“此电脑”-“属性”-“高级系统设置”-“环境变量”在系统变量里确认有没有 NVM_HOME 和 NVM_SYMLINK并在 PATH 里确认包含了 nvm 安装目录。很多新手在这一步会犯一个错改完环境变量后继续在旧终端里敲命令。Windows 的环境变量改动不会对已经打开的终端生效必须新开一个终端窗口。这里我建议直接把 Windows Terminal 设为默认终端因为它新开窗口方便切换管理员模式也顺手。另外可以顺手运行 echo %NVM_HOME% 和 echo %NVM_SYMLINK% 验证环境变量输出不为空就说明配好了。2.4 管理员权限和 WSL 的边界问题再聊权限。nvm-windows 的版本切换依赖符号链接也就是在 NVM_SYMLINK 目录生成一个指向具体版本目录的链接。如果你把链接目录放在 C:\Program Files 这类系统目录下创建链接就需要管理员权限否则 nvm use 容易报错。常见的报错信息大约长这样“Could not create symlink”或者“Error while creating symlink”。解决办法有两个第一个是永远用管理员身份打开 PowerShell 或 CMD 再执行 nvm use第二个是把 NVM_SYMLINK 改到用户目录下比如 C:\dev\nodejs这样大多数情况下就不再需要管理员权限了。我个人的做法是用后者省得每次右键“以管理员身份运行”。还有一个经常被忽略的边界问题WSL 里的 Node 和 Windows 的 Node 是两套独立环境。如果你在 WSL 里也装了 nvm那是在 Linux 环境下的 nvm跟 Windows 上这个 nvm-windows 不通用。两边各自负责各自的不要在 Windows 终端里查 WSL 的版本也别指望 WSL 里的 node 命令能跟随 Windows nvm 切换。3. 高频命令实战装版本、切版本、删版本以及默认版本设置3.1 安装 Node.js 的正确姿势nvm 装好后安装 Node 就非常简单了。最省事的命令是nvm install lts这会安装当前最新的 LTS长期维护版适合大多数新项目。如果想装最新版用 nvm install latest。如果想指定某个具体版本比如团队的 CI 环境锁的是 Node 20.19.0nvm install 20.19.0这里有个小提醒版本号别带 v 前缀写 20.19.0 而不是 v20.19.0。带 v 前缀时nvm 偶尔会把版本名当成目录名的一部分导致后续 nvm use 时不匹配。在安装前想看看远端到底有哪些版本可选可以执行nvm list available输出里会列出当前可用的版本列表。这个命令特别适合用来排查报错比如你明明记得有个 24.20.0列表里却没有那就说明版本号不存在或者输入有误。3.2 切换版本nvm use 背后的真实行为安装完版本之后nvm 不会自动把它设为当前版本。你必须手动执行切换nvm use 20.19.0看到输出类似 Now using node v20.19.0 (64-bit) 之后再执行 node -v 确认。这里有个非常容易踩的细节如果你是在已经打开的旧终端里执行 nvm use切换后这个终端里的 PATH 信息可能还是旧的node -v 输出不一定是新版本。建议执行完 nvm use 后新开一个终端再验证。这不是 nvm 的 bug而是 Windows 环境下 PATH 更新的固有特性。nvm current 这条命令可以快速查看当前在用的版本比 node -v 更直接因为它不依赖 node 命令本身。当你的 Node 还没激活、node 命令都找不到的时候nvm current 依然能告诉你当前指向了哪个版本。3.3 版本列表管理list、uninstall、alias 与 default版本装多了以后管理就变得重要了。nvm list 列出所有已安装版本带星号的表示当前使用版本nvm list想删掉某个不再用的版本用 nvm uninstall 20.19.0。注意一个细节不要删除当前正在使用的版本否则 Windows 下的链接目录会指向一个不存在的目录导致 node 命令失效。稳妥的做法是先 nvm use 到别的版本再 uninstall 旧版本。设置默认版本也是一条命令的事nvm alias default 20.19.0这样每次新开终端系统会自动指向这个默认版本。对大部分只跑普通项目的开发者来说装上 nvm 加设好 default日常根本不需要频繁切换。我把最常用的命令整理成了一张表命令作用nvm version查看 nvm 自身版本nvm list列出本机已安装的 Node 版本nvm list available查看远端可安装版本nvm install version|lts|latest安装指定版本nvm use切换当前使用的版本nvm current查看当前使用的版本nvm alias default设置默认版本nvm uninstall卸载指定版本nvm root显示 nvm 的安装根目录nvm on / nvm off启用 / 停用 nvm 接管建议把这张表存到本地等需要查的时候不用再去翻文档。3.4 关于 .nvmrc 的真实使用体验很多现代项目会在根目录放一个 .nvmrc 文件里面写一行数字比如 20.19.0用来声明“这个项目应该用 Node 20.19.0”。Linux/macOS 的 nvm 可以在项目目录下直接执行 nvm use自动读取 .nvmrc但 nvm-windows 默认没有这个自动读取能力nvm use 不带参数不会去读 .nvmrc。所以 Windows 下的实际做法是每次进入项目自己看一眼 .nvmrc 里的版本号手动执行 nvm use 20.19.0。虽然麻烦一点但只要你形成了习惯也就几秒的事。如果你特别在意这层体验也可以考虑把它交给更现代化的替代工具比如 fnm 或者 volta。fnm 在 Windows 上支持从 .nvmrc 自动读取版本volta 则更进一步会根据 package.json 里声明的工具链自动选择。不过这些工具的配置机制和 nvm-windows 又不一样刚上手的人不要同时装好几个选一个用熟最重要。我的建议是先把 nvm-windows 的这套命令玩熟真觉得自动读取 .nvmrc 是刚需再考虑换工具。4. 装完 Node 别急着跑项目先把 npm 这套全局配置理顺4.1 换一个下载够快的 npm 镜像源每次新装完 Node我做的第一件事不是跑项目而是先配 npm 镜像和全局路径。npm 是 Node 自带的包管理器正常情况下你执行 npm install 时它默认去官方源拉包。官方源在国外国内网络环境下一不小心就是几十秒的等待或者干脆超时。所以先把 registry 换成 npmmirror 的镜像npm config set registry https://registry.npmmirror.com/执行完可以用 npm config get registry 验证。如果你只想在某个项目里临时用一次镜像也可以这样npm install --registryhttps://registry.npmmirror.com但全局配置显然更省心。这个配置最终会写进 C:\Users\你的用户名.npmrc 文件属于用户级配置对所有项目生效。我印象很深的一次经历一个前端项目几十个依赖没配镜像时 npm install 卡了快十分钟配置完镜像后两分钟装完。项目能不能跑还是小事关键是反复等超时特别消磨耐心所以这一条无论如何都要排在最前面。4.2 全局包路径和缓存路径多版本共用的关键接下来是全局包路径。默认情况下npm 会把全局命令行工具安装到当前激活的 Node 版本目录附近。你可以用 npm prefix -g 查看当前全局安装前缀用 npm root -g 查看全局 node_modules 的位置。问题在于当你用 nvm 切换了 Node 版本全局工具的路径可能跟着变化上一秒还能用的全局命令下一秒就找不到了。我推荐的做法是把全局包统一安装到一个和 Node 版本无关的固定目录。先在 D 盘建两个目录比如 D:\dev\npm 和 D:\dev\npm-cache然后执行npm config set prefix D:\dev\npm npm config set cache D:\dev\npm-cache配置完以后再用 npm install -g 安装任何工具都会写到 D:\dev\npm\node_modules 里生成的命令行脚本也会放在 D:\dev\npm 下。接下来手动把这个目录加进系统环境变量 PATHD:\dev\npm加完新开终端全局安装的 npm 命令就能稳定识别再也不受 nvm 切换版本的影响。要注意的是这个方案带来的代价是所有 Node 版本的全局包是共享的如果某个全局工具对不同版本的 Node 兼容性差异很大切换版本后可能需要重新安装或升级它。但对大多数工具来说共享远比反复安装省心。我个人的全局工具列表里包括 pnpm、yarn、rimraf、http-server 这类通用工具共享了两年多没出过什么大问题。4.3 corepack 与包管理器交给工程体系而不是全局在全局工具里pnpm 和 yarn 的地位比较特殊。它们本身也是 npm 包但实际项目中我们更希望包管理器的版本跟着项目走而不是全机器一个版本。新版 Node 内置的 corepack 就是干这件事的它可以根据 package.json 里的 packageManager 字段自动启用对应版本的 pnpm 或 yarn。如果你想用新版 Node又不想手动全局装 pnpm可以打开 corepackcorepack enable特别提示某些新版 Node 发行版不再默认捆绑 corepack需要单独安装。如果你执行 corepack enable 提示找不到命令去查一下对应版本的安装说明就行。这里也顺便回应一个常见的现象很多桌面开发工具尤其是基于 Electron 的一些工具在安装或启动时会卡在“installing node.js dependencies”大概率就是本机 Node 环境太乱导致的。要么是全局 prefix 不在 PATH 里要么是某个全局包被 Node 版本切换带走了。把 4.1 和 4.2 的配置做好之后这类问题基本能消掉一大半。5. 用 nvm 两年踩过的坑从版本对不上到 npm 消失的排查链路5.1 坑一nvm use 成功了node -v 却还是旧版本先说最常见的一个坑nvm use 明明成功了但 node -v 还是旧版本。遇到这个问题第一步不是重装而是按顺序排查。先新开一个终端排除 PATH 缓存问题。然后运行 where.exe node看 node 命令实际来自哪个路径。如果输出里有 C:\Program Files\nodejs\node.exe 之外的其他路径而且那个路径下有旧 Node就说明 PATH 里旧路径的优先级更高。解决办法是把旧 Node 的路径从 PATH 里删掉或者把它移到 NVM_SYMLINK 之后。如果 where.exe node 显示的就是 NVM_SYMLINK 路径但版本还是旧值那就是链接没有创建成功。去 NVM_SYMLINK 目录里看一眼确认它是不是一个带箭头的链接目录。如果不是用管理员权限重新执行 nvm use。我碰到过一次很奇怪的情况目录存在但里面没有 node.exe原因是之前安装 nvm 前没卸载干净链接被一个残留的空目录挡住了。把那个空目录删掉再 nvm use 就好了。5.2 坑二nvm install 报 “not yet released or is not available”第二个坑就是标题里的那个经典报错我把它完整写出来Error installing 24.20.0: Node.js v24.20.0 is not yet released or is not available这个报错字面意思是“这个版本还没发布或不可用”。网上能看到这个报错原因通常是两种版本号打错了或者输入了一个当前远程列表里不存在的版本。比如 Node 24 的版本线里根本没有 24.20.0自然装不了。遇到就执行 nvm list available 看真实版本号再重新执行 nvm install 就解决了。另一个隐藏原因是 nvm install 后跟大版本号这种写法比如 nvm install 24nvm-windows 不一定支持这种简写它可能去找一个完整版本号找不到就报错。所以我的建议是永远写完整的小版本号比如 24.2.0。还有一点nvm-windows 缓存了一份远端版本列表如果你本地列表太旧刚发布的新版本可能看不到。常规操作就是更新 nvm-windows 到最新版或者在 settings.txt 里配好 node_mirror 指向国内镜像源然后重新执行 install。5.3 坑三切换版本后 npm 没了全局命令也找不到第三个坑切换了 Node 版本之后npm 命令直接没了或者全局命令行工具找不到了。npm 是随 Node 一起走的理论上切了 Node 版本npm 也会跟着切换。如果 node -v 正常但 npm -v 报错先检查 NVM_SYMLINK 指向的目录里有没有 npm.cmd。如果没有可能是安装了精简版 Node 或者解压不完整重新执行一次 nvm uninstall、nvm install 就行。如果 npm 还在但全局命令找不到了那就是我前面说的全局 prefix 路径问题。用 npm prefix -g 看一眼当前全局前缀再对照 PATH 里有没有这个路径。如果你之前没有按 4.2 配置固定 prefix那切换版本后默认前缀跟着变了之前全局安装的工具自然就“消失”了。解决方法就是统一配置 prefix 并加入 PATH一次性解决问题。5.4 坑四在 Git Bash 里切版本为什么不生效第四个坑比较隐蔽在 Git Bash 里执行 nvm use 后版本切换不完全生效。Git Bash 是很多 Windows 开发者必备的终端但 nvm-windows 是通过修改链接目录来切版本的而 Git Bash 对 Windows 路径有一套自己的转换规则加上 MSYS 环境变量处理方式不同经常出现“明明 use 了node -v 还是旧版本”的情况。遇到这种问题最直接的办法是在 Git Bash 里新开一个窗口或者临时用 cmd /c nvm use 20.19.0 node -v 来执行。我个人更建议Windows 下用 nvm-windows 时日常操作还是以 PowerShell 或 Windows Terminal 为主Git Bash 用来跑 shell 脚本就好了两边工具各干各的别硬凑。最后再分享一个我个人的小习惯每接一个新项目第一件事是看 package.json 里的 engines 字段、根目录的 .nvmrc、以及包管理器声明确认 Node 版本范围然后 nvm install 加 nvm use。这套流程跑顺之后nvm 的存在感会变得很低——基本就是一条命令的事。工具的意义也正在于此不是让你天天研究它而是让它安静地待在背后你要用的时候它一直在。如果你现在还在用卸载重装的方式折腾 Node 版本我真的建议花十几分钟把 nvm 装好这个投入的回报率太高了。