Windows下NVM安装配置指南：解决Node多版本管理难题

我最早在 Windows 上被 Node 版本折磨是从接手一个老项目开始的。仓库里明确写着引擎要求 Node 12我电脑上装的是 14一跑构建就报错同时新项目又要 16 以上。于是我把 Node 卸载、重装、配源、装全局包折腾一下午最后还是不行。后来换成 NVM 管理 Windows 上的 Node 版本一条命令就能在两个版本之间来回切才算真正解决了这个问题。这篇教程就围绕 NVM 在 Windows 下的安装和配置来写包含安装前的准备、安装步骤、换源、npm 全局包和 pnpm 的配合、多版本工作流以及我踩过的一些坑。适合刚开始用 NVM、或者装完总是出现各种奇怪报错的人看完能少走不少弯路。1. 为什么 Windows 上的 Node 版本管理这么让人头疼1.1 多版本并存不是矫情是项目现实很多人一开始不理解Node 不是越新越好吗装个最新版不就行了真不是。老项目锁版本是常态。公司内部系统、外包交付项目经常锁定在某一个 Node 大版本上比如 Node 12 或 Node 14。不是团队不想升级而是项目里依赖的某个老框架、某个原生模块在新版本 Node 下根本编译不过。新项目则不一样上来就用 Node 18 甚至 20因为新特性、新工具链都要求高版本。两边同时都要做的时候你本地只有一个 Node就只能反复卸载重装。手动卸载重装这个过程有多反人类试过一次就知道先从控制面板卸载再去 Program Files 检查有没有残留装的时候要重新配镜像源装完还得把 npm 全局包一个个装回来。遇到 npm 版本还变了某些全局命令执行方式都不一样。一个下午基本就耗进去了。这种重复劳动完全可以靠工具解决这也是 NVM 存在的理由。1.2 NVM-Windows 和 Linux/macOS 上的 nvm不是同一个软件这里必须先说清楚一个关键点你在网上搜 nvm搜出来的很多教程是 Linux 或 macOS 的直接拿到 Windows 上照抄大概率会失败。Linux 和 macOS 上的 nvm 是一个 shell 脚本它通过修改当前 shell 的 PATH 环境变量来切换 Node 版本不同终端窗口甚至可以同时使用不同版本。而 Windows 上大家常说的 NVM实际上是 coreybutler 维护的 nvm-windows 项目。它跟 Linux 版不是同一个代码库原理也完全不同。nvm-windows 的做法是把所有 Node 版本都装在同一个目录下然后通过生成一个符号链接目录默认叫 nodejs来指向当前要使用的 Node 版本。这个 nodejs 目录被加进了系统 PATH所以你执行 node -v 时实际走的是这个软链。切换版本本质就是把软链指向另一个版本目录。这个差异带来的后果很明显nvm-windows 的配置文件是安装目录下的 settings.txt不是 Linux 版的 shell 配置它也不支持终端级别隔离切换是全局生效的。后面所有操作我都会按 nvm-windows 的规则来讲。2. 安装前先把老环境清干净再决定安装姿势2.1 旧 Node 到底要不要卸我建议卸。如果你电脑上已经装了 Node.js不建议直接装 nvm-windows原因很简单nvm-windows 管理 nodejs 软链目录时会跟已有的 Node 安装目录抢 PATH。两个 node 同时在 PATH 里到底执行哪一个完全看 PATH 顺序非常容易出现装了 nvm 之后node -v 还是旧版本的情况。正确做法是先卸载旧 Node。打开控制面板找到 Node.js卸载。卸载完成后去检查这几个位置C:\Program Files\nodejs 是否还有残留目录%APPDATA%\npm 和 %APPDATA%\npm-cache也就是 C:\Users\你的用户名\AppData\Roaming 下的 npm、npm-cache环境变量 PATH 里是否还有 Node 相关的路径有残留就手动删掉。这里有个提醒不要一上来就把 npm 全局目录删了先备份。执行 npm ls -g --depth0 看一下你装过哪些全局包列个清单。等 NVM 装好之后需要哪个再装回来省得到时候拍大腿。2.2 安装包版和压缩包版怎么选nvm-windows 在 GitHub releases 里提供两类文件我见过很多人第一次接触时不知道选哪个。nvm-setup.exe安装向导版双击一路下一步自动帮你创建环境变量 NVM_HOME 和 NVM_SYMLINK对环境变量不熟的朋友选这个最省事。nvm-noinstall.zip绿色解压版下载后自己解压手动配环境变量。适合公司电脑没有管理员权限、或者想把工具做成绿色版随身带的人。我自己的建议是能选安装包版就选安装包版。手动配环境变量不难但步骤多一个出错概率就高一分。而且 nvm-noinstall.zip 解压后不会自动生成 settings.txt第一次运行前还得手动建对新手不友好。如果你在 GitHub 下载速度很慢可以换个思路等网络好的时候再下或者让同事把下载好的 exe 传给你。安装包本身不大几 MB 到十几 MB只要拿到文件后续不需要联网也能完成安装。2.3 安装目录怎么规划nvm-setup.exe 安装过程中会问你两个路径一个是 NVM 的安装目录一个是 Node 版本软链目录。默认值分别是 C:\Users\用户名\AppData\Roaming\nvm 和 C:\Program Files\nodejs。这两个默认路径能用但有两点不舒服一是装在 C 盘用户目录下路径层级深找起来麻烦二是 Program Files 中间有空格虽然 nvm-windows 处理得了但某些老项目脚本遇到带空格的路径会出幺蛾子。我建议规划成这样NVM 安装目录D:\nvmNode 软链目录D:\nodejs两个目录都要满足三个条件纯英文路径、没有空格、不在用户目录下被各种权限限制。尤其不要装到中文用户名目录下面比如 C:\Users\张三\很多编译工具遇到中文路径会直接罢工。这里再提醒一个细节NVM 安装目录和软链目录不要互相嵌套。比如 D:\nvm 下面再建 D:\nvm\nodejs 这样符号链接关系会变得很绕我遇到过切换版本时链接指向错乱的情况。两个目录平级放各管各的最清爽。3. 跑起来安装、换源与第一个 Node 版本3.1 nvm-setup 安装步骤拿到 nvm-setup.exe 之后安装过程本身没多少技术含量但有几个注意点。运行安装向导到选择目录那一步把默认路径改成 D:\nvm把软链目录改成 D:\nodejs。继续下一步安装完成。装完先别急着用打开一个全新的 CMD 窗口执行nvm version如果能打印出版本号说明安装成功。如果提示“nvm 不是内部或外部命令”一般是环境变量没生效。新开的命令行窗口会重新读取环境变量所以记得 CMD 要新开旧的窗口里看不到新配置。nvm-windows 装好后会自动配两个环境变量NVM_HOME指向 D:\nvmNVM_SYMLINK指向 D:\nodejs同时PATH 里会增加 %NVM_HOME% 和 %NVM_SYMLINK%这就是为什么你可以在任意目录直接执行 nvm、node 命令。这个机制后面排查问题时会用到先记住。3.2 最重要的换源settings.txtnvm-windows 安装完成后D:\nvm 目录下会生成一个 settings.txt默认内容大概是这样的root: D:\nvm path: D:\nodejs arch: 64 proxy: none如果你想用国内镜像下载 Node必须在这个文件里补充两行node_mirror: https://npmmirror.com/mirrors/node/ npm_mirror: https://npmmirror.com/mirrors/npm/为什么必须配这个因为 nvm-windows 安装 Node 时默认从官方地址 https://nodejs.org/dist 拉取安装包。国内网络访问这个地址经常慢到怀疑人生甚至直接失败。npmmirror 是阿里做的 npm 镜像里面同步了 Node 的所有发行版本速度非常稳定。有人会问我只配 node_mirror 行不行建议两个都配。node_mirror 负责下载 Node 本体npm_mirror 负责下载 Node 自带的 npm 包。只配第一个下载 Node 快了但 npm 部分可能还走官方源。两个一起配整个安装过程都走国内镜像。改完 settings.txt 保存不用重启电脑。这个文件是运行时读取的重新执行 nvm 命令就生效。3.3 下载安装并切换 Node 版本换源之后先看一下远程有哪些版本可以装nvm list available这个命令会列出一大串版本号从上到下排。如果你不想看列表可以直接装指定版本。以 Node 18.20.4 为例我通常用这个命令nvm install 18.20.4等进度条走完再用nvm list查看本机已经装了哪些版本。你会发现版本号前面有的标了星号有的没标标星号的就是当前正在使用的版本。第一次安装完nvm-windows 不一定会自动切换过去你需要手动执行nvm use 18.20.4如果输出 “Now using node v18.20.4”说明切换成功。这时候再看node -v npm -v应该分别打印 v18.20.4 和对应的 npm 版本号。这个 use 命令背后做了什么事呢它会删除 D:\nodejs 这个软链再重新创建一个指向 D:\nvm\v18.20.4 的新软链。全部用户级不需要反复装 npm干净利落。3.4 扩展装一个 LTS 版本备用除了项目要求的版本我强烈建议再装一个当前 LTS长期维护版本备用。比如你主要用 18可以顺手再装一个 20nvm install 20.15.0 nvm use 20.15.0为什么要备一个 LTS因为你保不齐什么时候要临时跑一个新项目或者某个全局工具要求高版本 Node。到时候不用联网再下载直接从本地版本列表里切换就行。有一点要注意LTS 版本会随着时间推移更新不要死守某一个具体版本号不放。建议每隔几个月上 npmmirror 看下当前 LTS 是哪个装一个最新的长期版用着。4. 全局软件包与 pnpm别忘了 prefix 和 PATH 的关系4.1 把 npm 全局安装目录从 C 盘迁出去Node 装好之后默认的 npm 全局目录在 C:\Users\用户名\AppData\Roaming\npm。这个位置有俩问题一是装在 C 盘系统盘被各种依赖塞得越来越大二是路径太长偶尔会碰到工具链解析路径出错。我习惯把所有跟 Node 相关的文件都放到 D 盘包括 npm 全局包。操作方式很简单先建两个目录mkdir D:\node_global mkdir D:\node_cache然后设置 npm 的全局目录和缓存目录npm config set prefix D:\node_global npm config set cache D:\node_cache执行完之后需要改环境变量。把 PATH 中原来指向 %APPDATA%\npm 的条目删掉改成 D:\node_global。改完重开 CMD再执行npm config get prefix npm config get cache确认输出的路径是 D:\node_global 和 D:\node_cache就成功了。这个操作的意义不只是“节省 C 盘空间”。当全局包集中在一个目录后NVM 切换 Node 版本时全局包的依赖关系更可控排查问题也更容易。后面讲 pnpm 时你会体会更深。4.2 npm 镜像源配置npm 默认的官方源 registry.npmjs.org在国内访问速度时好时坏。改镜像源是顺手的事npm config set registry https://registry.npmmirror.com验证一下npm config get registry看到输出是 npmmirror 的地址就说明生效了。如果你只希望某个项目用特殊源可以在项目根目录建立一个 .npmrc 文件写入 registry 配置这样只有当前项目走这个源。这个技巧在公网源和公司私有源之间切换时特别有用不用反复全局改。另外提一句npm 的配置是跟着用户走的全局配置存放在 C:\Users\用户名.npmrc。NVM 切换 Node 版本不会改变这个文件所以镜像源配置是一次性的换版本后依然有效。4.3 在 NVM 环境下安装 pnpm很多人搜“nvm 安装 pnpm”因为实际操作时会踩坑。pnpm 是现在很流行的包管理器安装其实不复杂npm install -g pnpm装完执行pnpm -v能输出版本号就行。但这里有几个细节经常让人莫名其妙。第一个问题是 pnpm 高版本对 Node 有最低版本要求。比如 pnpm 9 要求 Node 18 以上如果你的 NVM 当前切在 Node 16执行 pnpm -v 会直接报错。这时候不是 pnpm 装坏了而是 Node 版本太老。第二个问题是 pnpm 的全局命令目录。pnpm 会创建一个全局 bin 目录默认跟 npm 的 prefix 有关。既然前面已经设置了 D:\node_global那 pnpm 的全局命令也会落到 D:\node_global 下面只要这个目录在 PATH 里就没问题。如果你发现 pnpm 的全局命令找不到执行pnpm config get global-bin-dir查看当前 bin 目录在哪确认它加进 PATH 没有。第三个问题是切换 Node 版本后pnpm 偶尔会提示找不到 Node。我遇到过的典型场景是在 Node 18 下装了 pnpm切换到 Node 20 后直接执行 pnpm install报 Node 路径相关的错。这种情况别慌执行 npm install -g pnpm 重装一次把 pnpm 重新挂到当前 Node 版本下基本就恢复了。4.4 切换版本后全局命令失效的三种情况要分清NVM 多版本环境下全局命令失效这个问题几乎人人都会碰到但原因不同处理方式完全不同。第一种命令提示“不是内部或外部命令”。这是 PATH 里没有包含 npm 全局目录或者包含了但路径不对。去环境变量检查 D:\node_global 是否在 PATH 中。第二种命令能执行但报 Node 版本不兼容。比如某个 CLI 工具要求 Node 18你切换到 Node 16 执行它就崩了。可以给每个 Node 版本都装一份该工具或者干脆用 npx 临时调用。第三种原生模块报错比如执行某个全局命令时说 node-gyp 编译失败。因为全局包里的原生模块是跟着安装时的 Node 版本编译的切版本后 ABI 变了需要重新编译。最省事的办法是把对应全局包卸载再重装。弄明白这三点你就不会一遇到报错就怀疑 NVM 装坏了。5. 多版本共存工作流固定版本、团队协作和自动切换对比5.1 用 .nvmrc 把版本锁进项目NVM 用顺了之后我发现最影响效率的不是切换命令本身而是“每次进入项目都要想一下当前该用哪个 Node 版本”。项目一多脑子根本记不住。解决方法是把版本号写进项目根目录的 .nvmrc 文件。这个文件内容非常简单就一行18.20.4进入项目目录后手动读这个文件再切换nvm use $(cat .nvmrc)PowerShell 里语法不一样用nvm use (Get-Content .nvmrc)nvm-windows 对 .nvmrc 的自动读取支持在不同版本上行为不太一样我不依赖它的自动逻辑而是用上面这种“手动触发但自动读版本号”的方式到哪个项目就执行一下既简单又不会意外切错版本。5.2 团队协作中的 Node 版本约定如果你在团队里写 Node 项目光自己锁版本还不够最好把版本约定写进项目文档。README 里加一段“本项目使用 Node 18请使用 nvm 安装并切换。项目根目录已添加 .nvmrc。”这句话能省掉很多 “我这跑得好好的你那边怎么报错” 的扯皮。更严谨的团队可以在 package.json 里声明 engines 字段engines: { node: 18 19 }再配合 .npmrc 里的 engine-stricttrue让 npm 在 Node 版本不满足时直接报错而不是带病运行。这个组合拳比口头约定有效得多。我个人的体会是团队开发环境统一很多诡异问题会自然消失。很多所谓 “环境问题”说白了就是有人用 Node 14有人用 Node 20行为不一致导致的。5.3 顺带聊两句 Volta 和 fnm如果你看到这里想偷懒连 nvm use 都不想敲那我会给你推荐两个替代方案看一眼Volta 和 fnm。Volta 的特点是自动切换。你用 volta pin node18 指定项目版本后进入这个项目目录Node 自动就是 18不需要手动执行任何命令。fnm 也支持基于目录的自动识别速度很快还有 Windows 原生版。既然有这么方便的工具为什么我还是用了 nvm-windows因为同事装了它之后经常被环境变量和 shell 配置搞到头大而 nvm-windows 对大多数人来说学习成本最低出问题也好排查。工具这东西没有绝对最好适合团队现状最重要。如果你团队整体对命令行不熟老老实实用 nvm-windows 反而是最稳的。6. 踩坑合集安装完成后那些常见报错的排查链路6.1 node 不是内部或外部命令怎么办这个报错我见过太多次了而且不止新手会遇到老手清理环境变量时也容易翻车。排查链路是这样先执行 echo %NVM_HOME% 和 echo %NVM_SYMLINK%看两个环境变量有没有值。如果没有说明安装时环境变量没写进去手动补上 NVM_HOMED:\nvm、NVM_SYMLINKD:\nodejs。再看 PATH 里有没有包含 %NVM_HOME% 和 %NVM_SYMLINK%。如果 NVM_HOME 有值但 PATH 里没有手动加。最后检查 D:\nodejs 是否存在。如果这个目录不存在很可能 NVM 安装成功后你还没有执行过任何一个 nvm use 命令。没有当前 Node 版本时nodejs 软链是不会创建的。记住这个顺序环境变量是不是在PATH 里有没有软链到底有没有生成。按这个思路查90% 的问题都能解决。6.2 nvm use 一直报错exit code 1有人在执行 nvm use 18.20.4 时会遇到类似这种报错exit code 1这个坑的根源基本都出在权限上。nvm-windows 创建和替换 D:\nodejs 符号链接这个操作在系统目录或者权限受限的目录下执行时需要管理员权限。解决方法很简单右键 CMD 或 PowerShell选择“以管理员身份运行”再执行一次 nvm use 18.20.4基本就好了。如果以管理员身份运行还报错接着查 D:\nodejs 是不是一个损坏的链接。用这个命令看一下dir D:\如果 nodejs 这一项显示类似 “JUNCTION” 但指向的目录不存在先手动删掉这个节点再重新 use。删结点不要直接在资源管理器里删用管理员 CMDrmdir D:\nodejs然后重新 nvm use 版本号让它重建软链。6.3 安装 Node 慢得像蜗牛或者直接卡死装了 nvm-windows执行 nvm install 20.15.0进度条一直不不动或者下载到一半失败。十有八九是 settings.txt 里的镜像没生效。排查步骤先打开 D:\nvm\settings.txt确认文件里确实有 node_mirror 和 npm_mirror 两行且地址是 https://npmmirror.com/mirrors/node/ 和 https://npmmirror.com/mirrors/npm/。再确认 root 和 path 的路径跟你实际的安装目录一致。有时候你改过 settings.txt 但保存的不是 UTF-8 编码或者加了奇怪的 BOMnvm-windows 读取时可能不认。改完保存重开一个 CMD再执行安装命令。注意 CMD 窗口要重新打开因为 nvm-windows 读配置的时机在命令启动时。还有种情况是首次安装时 nvm-windows 需要下载 npm 包而下载地址还是官方源。如果你只改了 node_mirror 没改 npm_mirror就会卡在 npm 下载阶段。这就是为什么我一直强调两行要一起配。6.4 杀毒软件把 Node 软链给拦了这个坑比较隐蔽。现象是你安装、切换都显示成功但打开项目一执行 npm run dev提示找不到模块要么就是 node -v 能通但 npm 有问题。有一次我帮同事排查折腾了很久最后发现是 Windows Defender 把 nvm-windows 创建软链接的行为拦截了导致 D:\nodejs 指向的目录里文件不完整。如果你基础排查都做了还是不对可以临时关掉杀毒软件的实时保护再重新 nvm use 版本号看能不能恢复正常。但我不建议为了跑项目长期关闭安全软件确认是软链被拦之后去杀毒软件的排除项里把 D:\nvm 和 D:\nodejs 两个目录加进白名单然后重新执行 use这样既安全又省心。6.5 升级 NVM 之后旧配置失踪nvm-windows 更新不算频繁但一旦更新偶尔会遇到老版本装的 Node 列表还在但镜像源配置被重置成官方源的情况。因为新版安装器会重新生成 settings.txt覆盖你之前手动加的 node_mirror 和 npm_mirror。解决办法不是去骂工具而是养成习惯把 settings.txt 中自定义的镜像配置记下来更新后检查一下装完新版本后执行 nvm list确认本地已安装的版本还在再执行 node -v确认当前指向的版本没变如果你发现当前版本指向没了重新 nvm use 一次就行。最后再分享一点实际体会NVM 这东西真正用起来之后你会觉得它特别朴素核心无非就是一个下载器加一个软链管理工具。但就是这个小工具能让人从反复卸载重装的泥潭里解放出来。我用它的这几年最大的感受是环境管理这件事越早自动化后面省下的时间越多。日常使用我有两个习惯一个是电脑上常驻两个 Node 版本一个 LTS 一个项目指定版本几乎覆盖了所有开发场景另一个是任何全局装的东西能少则少能用 npx 临时调用就不全局装这样切换 Node 版本时踩到全局包兼容问题的概率会低很多。如果你按照前面的步骤装完还遇到别的奇怪问题建议先看一下 NVM_HOME 和 NVM_SYMLINK 这两个环境变量再看 settings.txt 和 D:\nodejs 软链状态。NVM 在 Windows 上的大部分毛病最后都能归到这三样东西上。