做前端做过一段时间的人基本都遇到过同一个尴尬老项目锁死 Node 12新项目上来就要 Node 20有时候不同组件库还互相打架。去官网卸了装、装了卸折腾半天最后还得对着“npm install 报错”怀疑人生。后来我换到 Windows 上工作第一件事就是把 Node 的版本管理工具 nvm 装好。这篇就把我在 Windows 下用 nvm 安装、切换、配置 Node.js 的完整过程写出来包括踩过的坑和那些官方文档里不会告诉你的事情。先说结论Windows 下的 nvm指的是 nvm-windows它和 Linux 下的 nvm 并不是同一个软件作者和维护者都不同命令习惯也不完全一样。但这并不影响它在 Windows 上是目前最主流的 Node 版本管理方案之一。你只需要记住它能在系统里装多个 Node.js 版本并能随时快速切换项目需要哪个版本就切到哪个版本。这篇文章适合谁如果你刚接触 Node.js还在为“安装 Node.js”这件事发愁或者你已经被十几个项目的不兼容版本折腾到崩溃想找一个一劳永逸的版本管理方案甚至是你只是想搞明白 nvm 和 node 之间到底存在什么关系这篇都能帮你把思路理清。我尽量不堆概念直接用命令和实操去讲。1. 为什么要在 Windows 上用 nvm 管理 Node.js1.1 多版本并存的日常刚需Node.js 的版本迭代速度非常快而且大版本之间经常有不兼容的破坏性变更。最典型的就是 Node 16 之前和之后很多第三方库对异步 API 的处理都不一样Webpack 5、Vite 这些构建工具对 Node 版本下限有着明确要求还有一些老旧的 CLI 工具只能在 Node 12 里跑拿到 Node 18 环境里直接给你抛出一堆找不到模块的错误。我遇到的一个实际案例是公司有个维护了四年的后台管理项目锁的是 Node 14.17.0因为用了某个老版本的 node-sass换个高版本编译那一步直接挂掉而新做的报表系统用的脚手架要求 Node 18。如果机器上只装一个 Node这就没法搞了。你不可能反反复复卸载重装那效率太低而且卸载不干净还会留下一堆环境变量、缓存目录和全局包残留。所以 nvm 解决的就是这个问题一台电脑N 个项目需要 N 个不同的 Node 版本装一次工具永久按需切换。1.2 Windows 下 nvm 的特殊性这事儿必须说清楚网上教程标题都写“nvm 安装教程”但很多人跟着操作之后发现对不上就是因为没分清楚两个东西Linux/macOS 下的 nvm 是 nvm-sh 维护的脚本github.com/nvm-sh/nvm它是一个 shell 函数不产生独立进程。Windows 下的 nvm 是指 nvm-windows 这个独立程序github.com/coreybutler/nvm-windows它是用 Go 写的采用 exe 安装包 环境变量的方式来接管 node 路径。两者不是一个东西命令也有差别。比如 Linux/macOS 的 nvm 版本管理靠nvm install、nvm usenvm-windows 也差不多但实际体验下来它比原版少了一些更细粒度的功能比如直接切换时重新加载当前 shell 环境等。所以在 Windows 上你不该去执行curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/... | bash那套那是在 WSL 里用的。正确姿势就是下载 exe 安装或者解压 zip干净利落。1.3 和其他工具怎么选除了 nvm-windows市面上还有几个方案可以管理 Node 版本Volta由 Rust 编写理念是不需要手动切换它会在你进入项目目录时自动读取 package.json 里的 node 版本约束并切换。速度很快但本质是“自动”而非“显式”你需要习惯它的规则。fnm也是 Rust 写的性能好支持自动切换但它更多是给终端重度用户准备的。手动更换 PATH 变量最原始的方式就是下载 Node 的 zip 包解压后自己改环境变量。可用但太容易出错而且多版本切起来痛苦。如果非要我排序Windows 日常开发我更推荐 nvm-windows。理由非常简单用户量最大教程最多出问题搜索时好找答案明文管理符号链接你随时可以看看C:\Program Files\nodejs到底指向了什么切换版本是显式行为不会在你不知情的时候悄悄换掉全局环境。2. 安装前准备先把环境收拾干净2.1 确认当前 Node.js 状态安装 nvm 之前先打开终端PowerShell 或者 CMD 都行执行一下node -v npm -v如果你看到了版本号说明电脑里已经装过 Node.js。这时候要注意nvm-windows 官方明确建议先卸载已存在的 Node.js再安装 nvm否则环境变量存在冲突的可能装完后 nvm 创建的符号链接可能无法生效。是的我见过有人的 Node 是手动解压的压缩包连 PATH 里都没写那没影响可以忽略但如果你是通过官方安装包装的就按下面的步骤卸载。2.2 正确卸载旧版 Node.js别图省事直接删文件夹那个清理不干净。正确的卸载路径打开控制面板的“程序和功能”找到 Node.js右键卸载。手动删除残留目录C:\Program Files\nodejs、C:\Users\你的用户名\AppData\Roaming\npm、C:\Users\你的用户名\AppData\Roaming\npm-cache。检查环境变量进入系统设置 - 高级系统设置 - 环境变量把 Path 里和 nodejs、npm 相关的条目删掉。这样做是为了避免 nvm 装好后出现“两个 node.exe 争夺路径”的诡异问题。实测下来不清理残留直接装 nvm最容易翻车的就是nvm use之后node -v依然显示旧版本。2.3 准备好一个干净的终端环境后面的所有命令我都建议你用管理员身份打开 PowerShell 或 CMD。原因后面细说这一条先记下来。注意管理员权限和普通权限在 nvm 使用过程中有很大区别。nvm 切换 Node 版本的本质是修改一个系统级的目录符号链接普通权限下容易遇到“拒绝访问”的报错。所以装完 nvm 后日常使用最好固定用管理员终端执行nvm use操作。3. 正式安装 nvm for Windows3.1 下载渠道辨析去 GitHub 下载 nvm-windows 的最新 release地址是 github.com/coreybutler/nvm-windows/releases。不要点那些乱七八糟的下载站也不要用别人网盘传好的版本GitHub 上官方 release 里的安装包是最靠谱的。下载的时候注意选对文件nvm-setup.exe是图形界面安装版适合一般人nvm-noinstall.zip是免安装版需要自己配环境变量nvm-setup.zip是安装版的压缩包形式其实本质一样。如果没有科学的手段访问 GitHub这里只讨论正常的网络环境下如何获取资源可以考虑用 gitee 上的镜像仓库或者等网络好了再下载。总之一个原则校验文件签名和版本号别下到旧版本或者被改过的包。安全提醒下载任何安装包都要注意来源可靠性。GitHub 官方 release 页面是最稳妥的渠道不要轻易运行从不明网站下载的 exe。3.2 安装版的具体操作双击nvm-setup.exe安装过程会问两个路径nvm 安装目录存放 nvm 程序本体和已下载的各个 Node.js 版本默认是C:\Users\你的用户名\AppData\Roaming\nvm我建议保持默认。Node.js 符号链接目录默认是C:\Program Files\nodejs保持默认就好。这里有个关键点安装路径中一定不要有空格和中文。如果度盘或者安装目录里有空格后面 nvm 操作 node 时容易出现路径解析问题。默认路径在用户名下只要你的 Windows 用户名不是中文一般都没问题。安装结束后打开终端输入nvm version能输出版本号就说明安装成功。如果提示找不到命令重开一个终端再试还不行就检查环境变量里有没有 NVM_HOME 和 NVM_SYMLINK 两个变量并且 Path 里是否加入了 nvm 安装目录。3.3 免安装版的配置如果你下的是nvm-noinstall.zip把压缩包解压到C:\dev\nvm最好放一个没有空格、路径不要太深的位置然后在环境变量里手动添加NVM_HOME C:\dev\nvmNVM_SYMLINK C:\Program Files\nodejs同时在 Path 中加入%NVM_HOME%和%NVM_SYMLINK%。之后在 nvm 目录下新建一个空的settings.txt文件写入以下内容root: C:\dev\nvm path: C:\Program Files\nodejspath就是那个将来会被 nvm 管理的符号链接路径。设置好以后管理员终端里输入nvm version验证。3.4 关键原理nvm 是怎么“骗”过 Node 的nvm-windows 的核心机制是创建目录符号链接。它会提前生成一个C:\Program Files\nodejs的符号链接安装一个 Node 版本时就把对应版本的目录文件复制或者链接到这个符号链接下面。当你在终端里执行nvm use 18.20.2实际上是用管理员权限重新指向了符号链接。这样你的 PATH 环境变量永远写的是C:\Program Files\nodejs这一个入口不需要在每次切换时修改系统环境变量只需要修改链接的指向。这就解释了为什么切换 Node 版本必须用管理员权限。普通用户没有权限去修改C:\Program Files目录下的符号链接所以 nvm 会报错。理解了这层机制你以后遇到奇奇怪怪的“切换不掉版本”的问题第一反应就应该是去看看那个 nodejs 文件夹是不是还连着旧版本。4. 用 nvm 安装和管理 Node.js核心实操4.1 查看可用的 Node.js 版本nvm 安装好以后先查一下远端有哪些版本可以安装nvm list available这个命令会列出一大串版本号分几列显示分别对应 LTS长期维护版、Latest Releases 等。如果你不需要看这么多只想装某个大版本的最新版也可以直接指定大版本号例如nvm install 20这样会安装 20.x.x 中最新的一个版本。如果你想查看本地已经安装了哪些 Node 版本nvm list刚装好的 nvm 应该是空的或者只有一个 system 占位符。system 表示“当前 PATH 里的 Node”如果你还没让 nvm 管理任何版本这个幽灵项可能不存在或显示为 no system version。4.2 安装指定版本要装 Node.js 20.11.1执行nvm install 20.11.1正常情况下会看到进度条下载的是 Node 官方发行版然后 nvm 自动解压到自己的目录里。装完后可以再执行nvm list能看到本地版本列表里多了一条。想装最新 LTS 版本其实这里主动贴合很多新手的习惯写清版本号更稳妥nvm install 20这个命令会自动匹配 20 大版本下的最新 LTS。实际体验中nvm 对“大版本号”的支持不错但如果网络比较差还是建议指定具体版本号因为下载失败时重试的粒度会更明确。4.3 切换并使用指定版本安装完成不等于立即生效你还需要执行nvm use 20.11.1看到输出Now using node v20.11.1 (64-bit)就表示切换成功。然后验证一下node -v npm -v这里有一点需要注意nvm use之后同样一个终端窗口里 node 命令能生效但你新开一个终端也需要等环境变量重新加载。Windows 的终端环境变量在启动时读取所以如果你在执行完 nvm use 后新开窗口理论上没问题因为 PATH 指向的符号链接已经变化了但如果你在旧窗口里执行命令顺带还有一些 npm 全局包缓存的影响可能不会立刻感知到全局包变化。最稳妥的做法是切换版本后新开一个终端窗口再开始干活。4.4 版本切换时全局包去哪了这是 nvm-windows 比较折磨新人的地方。在原生 Linux 的 nvm 下每个 Node 版本有独立的全局 node_modules切换后全局包完全隔离。但在 Windows 的 nvm-windows 里默认情况下所有版本共享一个全局 npm 包目录C:\Users\你的用户名\AppData\Roaming\npm。这意味着如果你在 Node 16 下全局安装了某个 CLI 工具切到 Node 20 后这个工具依然在 PATH 里。大多数时候没问题但如果那个工具依赖了特定 Node 版本的 ABI比如编译型原生模块跨版本用就会崩。经验之谈对一些需要原生编译的全局包比如node-gyp参与构建的工具切换 Node 版本后如果运行报错直接在对应版本下重新npm install -g 工具名一次就好不用想太多。4.5 卸载不需要的版本版本太老或者占空间了可以移除nvm uninstall 14.17.0如果你要卸载的正好是当前正在用的版本nvm 会提示不允许卸载当前使用中的版本需要先切换走再卸。实测中还有一个问题如果那个版本的目录里有正在运行的 node 进程卸载时可能因为文件被占用而失败先关掉相关进程再卸载。5. 全局配置与日常使用的几个要点5.1 设置默认版本每次开一个新的终端nvm 并不会自动记住你上次用的是哪个版本。如果你希望终端一打开就默认使用某个 Node 版本执行nvm alias default 20.11.1这个操作会写一个配置默认值之后新开的终端里 node -v 会直接显示你指定的版本而不用每次手动 nvm use。这个配置非常实用尤其是你主要用一个大版本时装好后设置一下省心很多。5.2 配置 npm 镜像加速npm 官方源的下载速度在国内一直是个老大难问题。nvm 只是管理 Node 版本npm 用的源需要在 npm 层面配置。nvm 安装好 Node 后终端里执行npm config set registry https://registry.npmmirror.com这条命令会修改用户级别的.npmrc之后 npm install 默认走国内镜像。关于镜像是否选择看个人网络环境推荐使用阿里维持的 npmmirror 镜像存储完整同步频率也还行。顺带一提nvm 下载 Node 本身用的也是 Node 官方源如果你nvm install时卡在下载或者速度极其慢可以在 nvm 安装目录下的settings.txt里配置镜像node_mirror: https://npmmirror.com/mirrors/node/ npm_mirror: https://npmmirror.com/mirrors/npm/配置后重新执行nvm install下载速度会有明显改善。这是我给很多同事推荐过的办法实测有效。5.3 项目级 .nvmrc 配合使用如果你希望项目成员统一用同一个 Node 版本可以在项目根目录创建.nvmrc文件内容就一行版本号20.11.1切换到这个项目时先执行nvm usenvm 会读取.nvmrc里的版本号并自动切换。但注意nvm-windows 对用.nvmrc自动切换的支持没有原生 nvm 那么丝滑如果你在目标版本没安装的情况下直接nvm use它会报错。所以建议流程是先nvm install 20.11.1再nvm use。5.4 终端选择建议Windows 自带的 CMD 能用PowerShell 更顺手一点但还是建议装 Windows Terminal。它配合 nvm 使用起来体验更好多标签页、主题自定义而且不干扰环境变量加载。在 Windows Terminal 里使用管理员模式运行 PowerShell一切 nvm 命令的执行体验都会顺畅很多。6. 常见问题与排查技巧实录6.1 “nvm 不是内部或外部命令”这个几乎是最常见的报错。原因分三类环境变量没配好、安装目录有空格导致命令解析出错、终端没重启导致环境变量未加载。排查思路先打开“环境变量”面板确认NVM_HOME和NVM_SYMLINK都存在并且 Path 里包含%NVM_HOME%。然后新开一个终端再试。如果还是没有检查 nvm 的安装目录下有没有nvm.exe文件没有就是安装过程被安全软件拦了或者在免安装版里没有正确解压。6.2 “Could not find” 或 “not yet released”出现error installing 24.20.0: node.js v24.20.0 is not yet released or is not available这种提示原因也很简单你所写的版本号在远端仓库根本还没有发布。可能是因为版本号打错了或者过于超前。nvm 的list available展示的是远端源里已经存在的版本如果你手动指定了一个未来版本自然就报错了。解决办法是回到nvm list available里挑一个真实存在的版本号安装。6.3 切换版本时提示“access denied”或“无法创建符号链接”这是权限问题。nvm 切换版本需要修改C:\Program Files\nodejs这个符号链接普通终端权限不够。解决办法就是以管理员身份重新打开终端再执行nvm use 版本号。如果管理员模式下还是报错检查是不是杀毒软件锁定了目录或者之前手动创建了同名的真实 nodejs 文件夹。遇到同名真实目录时nvm 无法覆盖需要手动删掉那个文件夹。这里面有个细节如果删除时提示“正在使用”打开任务管理器结束掉 node.exe 相关进程再删。6.4 切换版本后 npm 命令失效症状是nvm use之后node -v 显示正确但 npm -v 报错或者直接“命令不存在”。出现这个问题的核心原因一般是这个 Node 版本的 release 包里不包含 npm或者 npm 目录损坏。解决方法是手动补装npm install -g npmlatest如果你切到一个老版本比如 Node 12而之前装了太新的 npm老版本可能跑不动此时需要装一个和版本匹配的 npm比如npm install -g npm6。6.5 某个版本下全局包是乱的Windows nvm-windows 全局包目录是共享的所以切换版本后经常出现某个命令行工具找不到了或者行为怪异。原因不是丢了而是它依赖的 Node ABI 和当前版本不兼容。解决办法在目标版本下重新装全局包npm install -g 工具名如果是原生模块优先选择带 prebuild 的版本避免本地编译有些工具支持通过npx跑就尽量别全局装这一条我建议所有想在 Windows 下“用 nvm 快乐切版本”的人都要心里有数。很多人以为装好 nvm 就能所有版本全局包通用显然不行。6.6 常见问题速查表症状可能原因解决方案nvm 命令不存在环境变量未配置/终端未重启检查 NVM_HOME、Path重开终端nvm install 很慢默认官方源网络受限settings.txt 配置镜像nvm use 切换失败非管理员终端 / 目录被占用管理员权限执行、关掉 node 进程npm -v 报错npm 未集成或版本不兼容重新 npm install -g npm版本卸载不了版本正在使用中/文件被占用切换其他版本、结束进程后卸载新终端仍旧版本未设置 default 别名nvm alias default 版本号6.7 踩坑总结与独家建议经过多轮折腾我总结了几条在 Windows 下用 nvm 最实用的小经验你的系统可能有多个终端CMD、PowerShell、Windows Terminal 各开一个。nvm 切换版本后尽量在新开的标签页里继续工作旧标签页的环境变量不一定刷新完整。在项目里一定要配合.nvmrc文件使用你在新机器上拉项目后照着眼睛看它装的 node 是哪个版本。装某个 Node 版本时如果下载卡在 99%那大概率是网络问题直接 CtrlC 重试nvm 有断点续传吗实测没有但它会快速跳过已下载的部分时有时无所以别傻等。注意 32 位和 64 位的区别。如果公司里的老机器是 32 位系统nvm install 18.20.2 32要指定 32 位。判断是否是 32 位 Node看nvm list里显示的字样即可。nvm-windows 更新频率不算高但也不代表它出了新版你就要立刻升。只要当前版本用着稳定就别折腾升级。我见过一次升级后旧符号链接全部失效的情况重新nvm use一遍就恢复了虽然不严重但白花时间。我个人在实际操作中的体会是nvm 的价值不仅仅在于“可以装多个版本”更在于它把版本切换从“修改环境变量 重启终端”这种思维变成了“一条命令立刻切换”。对于经常要在多个项目之间横跳的前端/Node 开发者来说这套机制真的是省了不少事。装好之后它就在后台默默干活真正需要你记住的其实只有nvm install、nvm use、nvm list这几个高频命令其他的遇到问题再去查完全来得及。如果你刚开始在 Windows 下配置 Node 环境照着上面的思路走基本能帮你绕开八成以上的坑。