做前端或者写 Node 服务端的人Windows 上最绕不开的一个问题就是 Node.js 多版本共存。项目一多今天这个要 Node 16明天那个要 Node 18再老一点的还得切回 Node 14每次升级都靠“卸载重装”硬扛npm 全局包也跟着废掉装回来又得一小时。我后来在 Windows 下装了 nvm-windows大家习惯直接叫 nvm之后这套折腾才算彻底消停。这篇文章就把从安装到日常使用的完整流程写清楚包括镜像源配置、全局包管理、各种报错排查都是实测踩过坑之后整理出来的。1. 为什么要在 Windows 上折腾 nvm1.1 多版本 Node 的真实痛点很多刚接触 Node 的朋友可能觉得电脑上装一个 Node.js 不就行了为什么要折腾版本管理工具等你同时维护两三个项目就明白了。比如我之前维护的一个老后台系统跑在 Node 14 上用了不少旧依赖一升级到 Node 18 直接各种 C 插件编译失败而新写的前端工程默认要求 Node 20有的还要求 npm 版本不能太低。这种冲突靠人工切换几乎无解卸载旧版本、清理目录、安装新版本、重装全局包一套流程下来大半小时没了还不一定能恢复正常。更麻烦的是有些项目锁定了 node_modules你从 Node 18 环境生成的模块在 Node 14 下就是跑不起来。没有版本管理工具就得忍受这种来回折腾。nvm 的意义就是让你在同一个 Windows 系统里安装多个 Node.js 版本一条命令切换各个版本互不干扰。1.2 nvm-windows 不是 Linux 那个 nvm这里必须澄清一个非常容易混淆的点。Linux 和 macOS 上大家常用的 nvm 是 GitHub 上nvm-sh/nvm这个项目它是用 shell 脚本实现的不支持 Windows 原生运行。Windows 下我们安装的“nvm”实际上是一个叫 nvm-windows 的独立项目作者是 Corey Butler地址是coreybutler/nvm-windows。它用 Go 语言编写工作机制跟 Linux 版完全不一样但命令设计尽量保持了一致。所以你在网上搜教程的时候看到一堆nvm install、nvm use的用法两边大致通用但底层实现和配置文件完全不同。Windows 下不要尝试去装 Linux 版的 nvm 源码也不要问为什么curl -o- ... | bash这种命令跑不了。nvm-windows 的核心原理也不复杂它把每个 Node.js 版本下载到自己的目录里然后通过创建一个符号链接symlink指向当前要用的版本。切换版本的时候只需要改这个链接指向即可Windows 上的node、npm命令实际是通过这个链接找到真正的可执行文件的。1.3 谁适合用 nvm-windows前端开发尤其是维护多个工程、多个技术栈的必装。写 Node.js 服务端、Electron 桌面应用、自动化脚本的也会遇到依赖版本兼容问题。需要测试自己的开源项目在不同 Node 版本下表现是否正常的开发者。用过 Docker 但不想每次都在容器里跑 Node想直接在宿主机切换版本的人。Windows Server 做 CI 节点的场景同样适用不过说明一下nvm-windows 主要用于本机开发环境服务器还是更推荐 Docker 隔离两种场景不冲突。2. 安装前的准备工作环境清理与路径规划2.1 先彻底卸载系统里现有的 Node.js很多教程跳过这一步直接让装 nvm结果装完之后node -v显示的还是老版本问题就出在旧版 Node 还在 PATH 里。如果你电脑上已经装了 Node.js务必备份好自己需要的全局包列表npm list -g --depth0可以查看然后去“控制面板”或“设置 → 应用”里卸载它。卸载完之后还有两个残留目录要手动清理因为它们不会自动删除C:\Program Files\nodejs—— 旧 Node 的主目录卸载后可能残留几 MB 到几十 MB 文件。%APPDATA%\npm和%APPDATA%\npm-cache—— npm 全局包安装目录和缓存目录里面有旧全局命令和大量缓存。环境变量里也要检查一下。打开“系统属性 → 环境变量”看用户变量和系统变量的 PATH 中有没有C:\Program Files\nodejs或C:\Users\你的用户名\AppData\Roaming\npm这类路径有的话全部删掉。如果之前手动加过NODE_HOME、NODE_PATH这样的变量同样删掉后面 nvm 会自己管理。2.2 检查符号链接是否残留旧版 Node.js 卸载后有可能在C:\Program Files\nodejs目录下留了一个空的符号链接文件。怎么判断在资源管理器里看到那个文件夹带一个小箭头图标或者命令行执行dir C:\Program Files时该目录标注了SYMLINKD。有这种情况先手动删除这个符号链接目录否则后面 nvm-windows 创建自己的 symlink 时会报“文件已存在”错误。删除方式很简单管理员权限打开 CMD执行rmdir C:\Program Files\nodejs注意这是删除符号链接不是删除文件不会误删其他数据但如果你有不确定的残留还是谨慎一点先确认里面没有重要资料再删。2.3 安装路径规划与管理员权限nvm-windows 安装时会让你填两个路径nvm 安装目录存放所有 Node 版本和 nvm 自身文件的地方比如D:\nvm。symlink 目录也就是将来node、npm命令实际解析到的入口默认是C:\Program Files\nodejs可以改成D:\nodejs。先说结论两个路径都不要用带空格的目录尤其不要装到默认的C:\Program Files\nodejs下面当 nvm 根目录。nvm-windows 对空格路径的支持一直有历史问题虽然现在的版本好了一些但没必要拿自己环境去赌。我自己是装在D:\nvmsymlink 指到D:\nodejs用了几年没出过路径问题。第二个关键点是从安装 nvm 到日常使用几乎每一步建议都用管理员权限。因为 nvm 需要创建和修改符号链接而 Windows 对创建符号链接操作有权限限制。普通权限下经常出现安装成功但nvm use不生效的情况反而排查半天都不知道问题在哪。所以安装时右键安装包选“以管理员身份运行”后续命令行建议也以管理员方式打开 CMD 或 PowerShell。3. 正式安装 nvm-windows 的完整过程3.1 获取安装包与版本选择打开 github.com/coreybutler/nvm-windows 的 Releases 页面下载最新版的nvm-setup.exe。这个页面提供三种安装包安装包说明适用场景nvm-setup.exe图形化安装向导自动写环境变量、自动建 symlink绝大多数人选这个nvm-noinstall.zip免安装便携版解压后手动配环境变量喜欢自己控制配置的nvm-setup.zip安装向导的原始压缩包包含源码构建产物一般用不上我的建议是直接选nvm-setup.exe。便携版虽然看起来干净但手动配环境变量容易漏项官网 README 写的操作步骤还分散在好几个文件里对新手不太友好。而且安装向导也就是让你点几次“下一步”不会额外塞东西。下载的时候如果 GitHub 访问速度不理想这个问题在国内经常遇到可以尝试从 npm 镜像站或一些镜像仓库找转发文件只要能找到对应 Release 的 exe 就可以安装包本身不区分地区。但我不建议花太多时间在下载渠道上实在不行挂个离线包也是办法但注意下载完校验一下文件大小和哈希避免拿到被改过的文件。3.2 安装向导的关键选项双击nvm-setup.exe同意协议之后就进入路径选择页面。这里每一步都有讲究第一步是选择 nvm 安装目录默认是C:\Users\你的用户名\AppData\Roaming\nvm。我强烈建议改成D:\nvm或E:\nvm这种非系统盘路径。理由一是 AppData 目录隐藏在用户目录下需要时不好找二是系统盘空间紧张Node 版本装多了每个版本都占几十 MB 到上百 MB日积月累也不少。第二步是选择 symlink 目录默认C:\Program Files\nodejs。这里有两个坑Program Files带空格历史上会让一些工具在解析路径时出错。symlink 目录不要放在 nvm 安装目录里比如不要填D:\nvm\nodejs因为 nvm 清理目录时可能连带把链接目标删掉逻辑上会乱。所以 symlink 目录我填的是D:\nodejs跟D:\nvm平级清晰直观。第三步之后安装向导会自动帮你配置NVM_HOME和NVM_SYMLINK两个环境变量并往 PATH 里追加 nvm 目录和 symlink 目录。这一步是自动完成的不需要手动操作。安装完成后按提示勾选“打开命令行窗口”也行不勾也行下一步自己手动开一个即可。3.3 验证安装是否生效以管理员身份打开一个新的 CMD 窗口注意一定要“新开”因为关掉旧窗口再开新的环境变量才会重新加载。先看看 nvm 本身是否可用nvm version能输出类似1.1.12这样的版本号就算装好了。接着检查环境变量echo %NVM_HOME% echo %NVM_SYMLINK%两个都应该有值。然后查一下当前系统的 Node 状态。因为刚装完 nvm 还没有任何 Node 版本node -v按理说应该提示“不是内部或外部命令”。如果还能打印出旧版本号说明上一部分的清理工作没做干净回到第 2 节再检查一遍。验证完先不用急着往下走下一步是安装第一个 Node 版本。可以先执行nvm list available查看远程可用的版本列表但因为现在还没有配置镜像这一步可能很慢甚至超时。别急先把镜像配置好再操作。4. 多版本 Node 管理与全局配置实操4.1 核心命令速查与典型流程nvm-windows 的命令不多但日常高频用到的就这几个nvm list available # 查看远程可安装的 Node 版本 nvm list # 查看本地已安装的版本 nvm install version # 安装指定版本如 nvm install 18.20.4 nvm install lts # 安装最新的 LTS 版本 nvm install latest # 安装最新的 Current 版本 nvm use version # 切换当前使用的版本 nvm uninstall version # 卸载某个本地版本 nvm arch # 查看当前使用的是 64 位还是 32 位典型使用流程是先用nvm install lts装一个长期支持版再用nvm install 18.20.4这类命令装项目需要的特定版本然后nvm use 18.20.4切换之后node -v和npm -v验证都正常就可以开始干活了。这里有两个细节容易踩坑。第一nvm install是下载后自动解压不需要手动配置什么但如果你在安装某个版本时卡住多半是网络问题先看第 4.2 节的镜像配置。第二nvm use切换后如果当前命令行窗口之前已经运行过node进程新开的 CMD 窗口一定是你再次确认版本时的标准姿势因为旧窗口可能缓存了路径解析结果。4.2 配置国内镜像源彻底解决下载慢的问题nvm-windows 默认从 Node 官网和 npm 官网下载文件在国内网络环境下经常出现两种情况nvm list available加载半天只出来几行或者nvm install下载到一半直接超时。解决办法是配置镜像源。nvm-windows 支持两个镜像相关的设置命令nvm node_mirror https://npmmirror.com/mirrors/node/ nvm npm_mirror https://npmmirror.com/mirrors/npm/node_mirror负责下载 Node.js 本体npm_mirror负责下载对应的 npm 压缩包。两个都要配只配一个的话另一个环节还是会卡在官方源上。这条命令执行完配置会写入 nvm 安装目录下的settings.txt文件里。你也可以直接手动编辑这个文件效果一样。配置完后我建议的文件内容长这样root: D:\nvm path: D:\nodejs node_mirror: https://npmmirror.com/mirrors/node/ npm_mirror: https://npmmirror.com/mirrors/npm/配完之后再执行nvm list available版本列表基本上秒出nvm install lts也能顺畅下载。注意镜像源配置只会影响之后新下载的版本已经装好的版本不会自动改变。4.3 npm 全局目录与缓存配置Node 装好后npm 的默认全局安装目录和 npm 缓存目录默认都依附在当前 Node 所在的 symlink 路径下。如果你觉得每次切换版本后全局包都乱糟糟可以参考下面的方式做一个自定义的全局目录。先创建两个文件夹比如D:\npm-global和D:\npm-cache然后执行npm config set prefix D:\npm-global npm config set cache D:\npm-cache配置会写入用户主目录下的.npmrc文件。这时再把D:\npm-global添加到 PATH 环境变量里之后执行npm install -g 包名安装出的全局命令都放在这个目录里。但我必须说明一个权衡在 nvm-windows 环境下是否自定义全局目录是有讲究的。不自定义npm 全局包装在当前 symlink 指向的 node 版本目录下切换版本后全局包随版本隔离不会出现 A 版本装的全局命令跑去 B 版本用的情况。缺点是每个版本都要重新装一遍你常用的全局包。自定义 prefix所有版本共用一套全局包省空间、省安装时间。缺点是如果某些全局工具跟 Node 版本有绑定关系切到新版或旧版可能报兼容性错误。我目前的建议是如果只是装npm-check-updates、rimraf、nodemon这类跟版本关系不大的工具可以自定义全局目录如果是node-gyp、原生模块编译链这种强绑定环境的还是让每个版本自己管理更好。新手我建议先不自定义等体会过各版本隔离的感受再做选择。4.4 全局包与多版本共存的逻辑讲一个很多 nvm-windows 用户早期都懵过的点为什么我在 Node 18 下npm install -g装好的命令切到 Node 16 之后就发现找不到了这其实是正常现象不是 nvm 坏了。前面说过nvm-windows 是通过 symlink 切换当前 Node 目录的。你在 Node 18 下安装全局包时安装目标实际是 nvm 目录中 Node 18 对应版本文件夹里的node_modules。切换 symlink 到 Node 16 后当前路径已经变成 Node 16 的目录自然也就找不到 Node 18 下面装的东西。这是一个很合理的隔离机制理解了就不会慌。所以如果你发现切了版本之后某个全局命令消失了不要急着重装 nvm先nvm list确认当前在用哪个版本再判断那个命令是在哪个版本下装的切回去就能继续用。需要跨版本使用的工具要么在目标版本重新装一次要么用自定义全局目录的方式共享。5. 常见问题排查与避坑实录5.1 现象一nvm 不是内部或外部命令刚装完 nvm 就报这个通常是环境变量没生效或者安装路径有问题。先检查NVM_HOME有没有正确指向 nvm 安装目录PATH 里有没有包含%NVM_HOME%。如果环境变量正确那就关掉所有命令行窗口重新打开一个新的再试。还不行的话检查settings.txt里的root字段是否和实际安装目录一致不一致就改过来。5.2 现象二nvm use 之后 node -v 还是老版本这种情况在网友的提问里出现频率极高原因通常有三个当前 CMD 不是管理员权限符号链接没有成功切换。环境中存在旧版 Node 路径且它的优先级高于 nvm 的 symlink 路径。开着旧的node进程进程句柄把目录锁住了。优先用管理员权限重新执行nvm use version然后开新窗口验证node -v。如果还是老的用where node查看当前解析出的 node 到底在哪如果输出里有C:\Program Files\nodejs以外的路径就是 PATH 顺序问题去环境变量里把旧路径删掉。5.3 现象三nvm list available 报错或加载不出列表大部分是网络问题。确认nvm node_mirror和nvm npm_mirror已经配置成可访问的镜像然后重新执行nvm list available。如果还是不行可以手动打开镜像源的地址确认浏览器能正常访问。极少数情况是 nvm 版本太旧去升级到最新版再试。5.4 现象四npm 不是内部或外部命令nvm install成功node -v有输出但npm -v报找不到命令。这个现象常见于使用了比较冷门的 Node 版本或者镜像源没配对。nvm-windows 在安装 Node 时会根据命令行配置的npm_mirror去下载对应版本的 npm 压缩包如果这一步失败npm 就不会被解压到版本目录里。解决方法是重新设置 npm 镜像源nvm npm_mirror https://npmmirror.com/mirrors/npm/然后对这个 Node 版本执行重新安装nvm uninstall 18.20.4 nvm install 18.20.4安装完成后立刻执行nvm use 18.20.4再验证npm -v。如果还是一样那可能是该版本比较特殊可以考虑换一个常见的 LTS 版本比如 18.20.4、20.11.1、22.3.0这类版本的 npm 映射都比较完整。5.5 现象五切换版本后全局命令丢了这个我在第 4.4 节解释过属于预期行为不是故障。如果你需要使用某个全局工具切换到目标版本后重新执行一次npm install -g 包名即可。如果工具在各个版本下都要用可以用自定义全局目录的方案做共享但要注意版本兼容风险。5.6 其他高频坑汇总问题原因解决办法安装路径带空格导致 nvm 命令异常nvm-windows 历史兼容问题重新装到无空格路径如D:\nvmPowerShell 执行 nvm 提示禁止运行脚本执行策略限制Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser卸载 Node 版本时提示文件被占用有 node 进程正在运行切换版本、关闭所有 node 进程后再卸载nvm install 版本号一直停在进度条网络或源的问题配置镜像源后重试安装高版本 Node 后旧项目起不来项目依赖不支持高版本用 nvm 切换到项目要求的版本我在实际使用中还有一个习惯每次切换完 Node 版本第一件事永远是执行node -v和npm -v两个都确认正常再开始跑项目。这个习惯帮我省掉了太多“为什么刚才还能跑现在报错”的排查时间。nvm 本身不复杂但 Windows 下的环境变量、符号链接、权限这些底层机制会带来很多隐蔽问题配置好一次后面就是稳的。
