1. 为什么必须用 nvm 管理 Node.js 版本先聊个实际场景。你电脑里装了一个 Node.js 16项目 A 跑得好好的结果项目 B 必须用 Node 18 才能启动因为依赖了新版特性项目 C 更离谱锁定在 Node 14升级就报错。这时候如果你只有一个全局 Node只能在卸载重装之间来回折腾装一次十几分钟装完还不一定干净环境变量、npm 缓存、全局包残留一堆问题。用 nvmNode Version Manager就是干这个的。它是一个”多版本共存、随时切换“的工具能让同一台电脑装多个 Node.js 版本不同项目用不同版本切换过程只要一条命令。你不需要卸载现有的 Node也不用手动配环境变量nvm 统一管着所有版本改完立刻生效。从 2010 年 Node.js 出现到现在版本迭代非常快从 0.x 到 4、6、8、10、12、14、16、18、20、22每个大版本都有 breaking changes。尤其是 Node 18 开始原生支持 fetch、Test Runner 这些新特性很多老项目又停留在 14、16 上版本割裂问题越来越严重。作为前端或者后端开发者装 nvm 基本是标配就像 Python 开发者装 pyenv、Ruby 开发者装 rvm 一样属于开发环境的第一块基石。这个教程覆盖的内容包括nvm 在 Windows / macOS / Linux 下的下载安装方式、如何用 nvm 安装和切换 Node.js 版本、npm 的全局配置、以及我实际使用中踩过的各种坑和排查方法。无论你是刚入门的新手还是已经吃过版本切换亏的老手看完都能直接把环境搭好。2. nvm 下载与安装Windows 篇2.1 下载前先分清两个“nvm”这里有个容易懵的地方搜 nvm 会出来两个项目。一个叫nvmGitHub 上 creationix/nvm现在叫 nvm-sh/nvm是给 macOS / Linux 用的脚本安装不支持 Windows 原生运行。另一个叫nvm-windowsGitHub 上 coreybutler/nvm-windows这是专门给 Windows 做的版本安装包是 .exe 或 .zip功能类似但实现方式完全不同。所以你在 Windows 上第一步就是认准nvm-windows别拿 macOS 的安装命令往 PowerShell 里硬贴会直接报错。新版的 nvm-windows 也支持通过 winget 安装但为了稳定可控我更推荐手动下载安装包。2.2 下载安装包的具体步骤打开 GitHub 上 coreybutler/nvm-windows 的 Releases 页面找最新的 release。往下拉会看到 Assets安装资源区域通常有这几个文件文件用途nvm-setup.exe图形界面的安装程序适合大多数人一路下一步就行nvm-noinstall.zip绿色版解压就能用需要手动配环境变量nvm-setup.zip也是安装版但以 zip 形式提供我建议选nvm-setup.exe。它能自动把环境变量配好省去后面一堆手动操作。下载的时候注意看版本号比如 1.1.12 之类别下载到古老的 0.x 版本功能差很多。我自己习惯用稳定版不要追最新版的 beta因为 nvm-windows 的 beta 版本偶尔会有切换失效的问题。选最新的正式 release 就好。2.3 安装过程中的三个关键选择双击 nvm-setup.exe 之后安装向导会问几个问题这些选择直接决定你后面好不好用。第一个是nvm 的安装目录。默认是C:\Users\你的用户名\AppData\Roaming\nvm我建议改成D:\nvm或E:\nvm这种简单路径。原因有两个一是默认路径带空格和中文用户名的情况下某些老版本 Node 或 npm 工具解析路径会出问题二是改到其他盘之后重装系统或者清理 C 盘缓存都方便。路径里不要有中文、不要有空格这是铁律。第二个是Node.js 的安装目录。向导会让你选一个存放所有 Node 版本的文件夹默认是C:\Program Files\nodejs。这个路径比较微妙因为 nvm 切换版本的本质是改这个目录里的软链接。我实际测试下来把 Node 版本目录也放在非系统盘更省心比如D:\nodejs避免权限问题。安装完成后你可以看到这个目录的真实内容会被 nvm 不断替换成你正在使用的那个 Node 版本。第三个选择是在安装完成后是否允许 nvm 自动修改 PATH 环境变量。这个一定要勾选否则你得手动加很麻烦。2.4 安装完成后验证是否成功安装完以后打开一个新的命令行窗口PowerShell 或 CMD 都行输入nvm version如果正常会返回类似1.1.12的版本号。如果提示“nvm 不是内部或外部命令”说明环境变量没生效先关掉命令行窗口再重新打开还不行就手动检查系统环境变量里有没有 nvm 的安装路径。再输入nvm ls正常情况下会显示No installations recognized或空列表这表示现在还没有安装任何 Node 版本。到这里nvm 本身就算装好了。3. 使用 nvm 安装和管理 Node.js 版本3.1 查可用版本和安装指定版本nvm 装好后第一件事就是安装一个 Node.js 版本。先看一下远端有哪些可装的版本nvm list available这个命令会列出几百个版本号包括 LTS长期支持版、Current最新版、以及各种老版本。通常我不会直接装最新的 Current因为有些项目依赖的包还没来得及适配。开发环境首选 LTS 版本稳定、坑少。安装指定版本命令格式是nvm install 18.20.4这个版本号要写具体的小版本号。不像某些包管理器支持nvm install 18这种模糊匹配至少在我用过的 nvm-windows 版本里模糊匹配不一定好使。装的时候会下载对应的 zip 包并自动解压速度取决于网络。如果某个版本安装失败卡在下载阶段常见原因是网络问题。可以把 npm 镜像源换掉但注意这是换 npm 的源nvm 的下载源另说。nvm-windows 下载 node 是从 https://nodejs.org/dist/ 拉取的国内访问偶尔不稳定可重试几次或用 nvm 的设置文件指定镜像后面在常见问题部分我会详细讲。3.2 切换和查看当前版本装完多个版本后查看本机装了什么版本nvm ls输出会列出所有已安装的版本当前正在用的那个版本前面会标一个*。例如* 18.20.4 (Currently using 64-bit executable) 20.11.1 16.20.2切换版本用nvm use 18.20.4执行完后再运行node -v会发现 node 的版本立刻变成了 18.20.4。这个“立刻生效”的背后机制是这样的nvm-windows 并不是真的同时装着多个 node 可执行文件然后切换命令行入口而是把你指定的 node 版本映射到之前安装时设定的那个nodejs目录上。系统 PATH 里的始终是D:\nodejs这个目录nvm 只是把里面指向真实版本目录的快捷方式换掉。所以你打开任何一个新的命令行窗口它访问的都是D:\nodejs也就是你切换后的版本。这里有个小坑如果你在命令行窗口里执行了nvm use但接着运行node -v显示的版本没变大概率是那个命令行窗口是切换之前就打开的而且 node 的路径已经被解析到内存里了。不用纠结关掉窗口重新打开就正常。3.3 卸载不需要的版本版本装多了也占磁盘空间。到 node_modules 目录之外Node 本体大约几十兆到一百多兆装十几个版本就是好几个 G。清理用nvm uninstall 16.20.2如果你想卸载当前正在使用的版本会提示先切换到其他版本再卸载。这个设计是合理的防止你把自己正在跑的版本删了导致环境崩溃。3.4 nvm 常用命令速查表命令作用nvm install version安装指定版本 Node.jsnvm uninstall version卸载指定版本nvm ls查看本地已安装的版本列表nvm ls available查看远端可以安装的所有版本nvm use version切换到指定版本nvm current显示当前使用的版本nvm alias default version设置默认版本新开终端自动使用nvm node_mirror url设置 Node 下载镜像nvm npm_mirror url设置 npm 下载镜像alias default这个命令值得多说一句。如果你不设置默认版本每次打开新的命令行窗口node 命令可能是无效的因为 nvm 不知道该用哪个。设置一次nvm alias default 18.20.4之后每次打开终端node 自动就是 18.20.4。对于日常开发来说这是必须做的一步。4. 全局配置npm 镜像、全局目录和环境变量4.1 npm 默认源的问题Node.js 装好之后npm 是自带包管理工具。npm 官方源https://registry.npmjs.org/在国内速度很慢尤其装大型依赖的时候一个npm install卡个十几分钟很正常。解决办法是换成国内镜像。查看当前 npm 源npm config get registry永久换成淘宝镜像源npm config set registry https://registry.npmmirror.com这里说明一下淘宝原来源地址是https://registry.npm.taobao.org后来改名为 npmmirror新地址如上。如果你在网上搜到老的.taobao.org域名建议换成新版老的域名已停止服务。4.2 全局安装包的目录设置npm 默认会把全局安装的包放在 Node 安装目录下的node_modules里。因为 nvm 切换版本时D:\nodejs会被替换你在旧版本下全局装的包切到新版本后就会“消失”。这其实是理所当然的因为每个版本的 node_modules 是独立的。但为了管理和复用我建议把全局包的安装位置统一到自定义目录。具体做法分三步。第一步在某个盘符下建立一个全局目录比如D:\node_global和D:\node_cache。第二步设置 npm 的 prefix 和 cachenpm config set prefix D:\node_global npm config set cache D:\node_cache第三步把D:\node_global添加到系统环境变量的 PATH 里不然全局安装的命令行工具无法直接在终端中使用。设置完成后执行npm install -g yarn安装的 yarn 会出现在D:\node_global下不会受 nvm 版本切换影响。这个方案的收益在长期使用后非常明显你全局安装的pnpm、typescript、nodemon这些工具换 Node 版本后依然能用不需要重新装。4.3 为每个 Node 版本独立配置 npm 也是可行的如果你希望每个 Node 版本拥有自己独立的全局包就不做目录重定向直接用默认行为切版本后重装一次全局包也行。这种方式更干净但是麻烦。我个人的推荐是全局只装少量跨版本通用的工具如 pnpm、nodemon、typescript 这类对版本不敏感的项目级别的依赖一律通过项目内npm install安装不搞全局。这样 nvm 切换版本后项目进入目录重新安装依赖即可全局包往往不会引发兼容性问题。4.4 验证配置是否生效全局目录修改完执行npm prefix -g npm config get registry npm config get cache显示结果分别是你设置的D:\node_global、https://registry.npmmirror.com和D:\node_cache就说明一切正常。然后试着全局装一个小工具npm install -g http-server http-server -p 8080能正常启动说明全局命令的 PATH 也配好了。这一步没做好的话最常见的症状就是全局装完包却提示“xxx 不是内部或外部命令”。5. macOS 和 Linux 下的 nvm 安装方式5.1 脚本安装推荐macOS 和 Linux 上用的 nvm 是nvm-sh/nvm安装方式非常简单打开终端执行官方提供的安装脚本curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash或者用 wgetwget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash这段脚本会把 nvm 仓库克隆到~/.nvm目录下并自动往你的 shell 配置文件里写入几行加载 nvm 的命令。.bashrc、.zshrc、.profile都可能被修改具体取决于当前 shell。执行完后关掉终端重新打开输入nvm --version如果提示 command not found说明 shell 配置文件没有被正确加载。手动在~/.zshrczsh 用户或~/.bashrcbash 用户末尾添加以下几行export NVM_DIR$HOME/.nvm [ -s $NVM_DIR/nvm.sh ] \. $NVM_DIR/nvm.sh保存后执行source ~/.zshrc重新加载。5.2 安装指定版本 NodemacOS / Linux 下的 nvm 命令和 Windows 下很像但功能更强。比如nvm install --lts直接安装最新的 LTS 版本。也可以nvm install 20这里允许只写大版本号nvm 会自动帮你找这个系列下最新的版本。相比之下nvm-windows 的模糊匹配支持就不如这个好。切换版本和 Windows 一样nvm use 20设置默认版本nvm alias default 20macOS / Linux 下的 nvm 默认加载机制导致它在每个新终端都会自动激活 default 版本所以只要你设置了 alias default开箱即用的体验比 Windows 更好。5.3 卸载 nvm如果有需要macOS / Linux 下卸载 nvm 很简单把~/.nvm目录删掉然后清理 shell 配置里的 NVM_DIR 相关行即可。Windows 下则去“控制面板 → 程序和功能”找到 nvm 卸载或者重新运行 nvm-setup.exe 选择卸载。这里多提一句很多开发者在卸载旧的 Node 版本时发现系统里还有残留。手动装的 Node.js 卸载后注意清理这几个位置C:\Program Files\nodejs或自定义目录、%APPDATA%\npm、%APPDATA%\npm-cache、%USERPROFILE%\.npmrc。而 nvm 接管之后这些目录的实际数据都在 nvm 的管理范围内不需要手动清理避免了环境残留的问题。6. 常见问题与排查技巧实录6.1 “nvm 不是内部或外部命令”怎么办装完 nvm-windows 后终端输nvm version报错是最多人遇到的情况。先别急着重装按顺序排查看安装目录下的nvm.exe是否存在如果不存在说明安装没成功打开系统环境变量确认 Path 里有没有 nvm 安装目录如果 Path 里面有但终端还是找不到关掉终端重新开。环境变量是对之后启动的进程生效的已打开的终端不会刷新确认没有在 PowerShell 里开了管理员模式又用普通模式两者环境变量可能不一致。还有一个冷门坑nvm 被安装在带空格的路径比如C:\Users\John Doe\...某些命令解析会出问题。因此我一直坚持安装路径不用空格、不用中文。6.2 nvm install 下载很慢或直接失败这个问题在国内网络环境下尤其常见。nvm-windows 从 nodejs.org 拉取压缩包慢的话动辄几分钟到超时。一个方案是修改 nvm 的配置文件。找到 nvm 安装目录下的settings.txt添加或修改以下两行node_mirror: https://npmmirror.com/mirrors/node/ npm_mirror: https://npmmirror.com/mirrors/npm/这样 nvm 下载 Node 时就会从 npmmirror 拉取速度会快非常多。macOS / Linux 下的 nvm 可以用命令设置nvm node_mirror https://npmmirror.com/mirrors/node/ nvm npm_mirror https://npmmirror.com/mirrors/npm/如果修改后还是失败检查一下镜像地址是否有效不要用已经淘汰的旧地址。6.3 切换 Node 版本后 npm 不见了这个现象在 Windows 上很典型。切换版本前 npm 正常切完之后命令行输npm -v就提示找不到命令。原因是 nvm-windows 的版本管理逻辑和一些手动安装的 npm 全局配置冲突。常见情形是你之前手动装过 Node.jsnpm 的全局路径还指向旧目录或者 npm 的 prefix 被设置到了旧 Node 的目录下切换后那个目录里的 npm 也跟着变了。我推荐的解决办法是重新设置 npm 的 prefix 到统一目录具体操作参考前面的 4.2 节。然后把系统 Path 中所有指向其他 Node 相关目录的条目清掉只保留D:\nodejs和D:\node_global这类统一路径。6.4 “node:util does not provide an export named” 报错这个报错我看到不少人在网上搜尤其是 Node 16 升到 Node 18 之后。它通常是某个 npm 包使用了旧版本 Node 的模块导出方式而新版本里这个接口被移除了。解决思路也不是去降 Node而是检查是哪个包出现问题升级那个包到兼容版本。不过这里想提醒的是另一件事如果你发现项目在 Node 18 下面报这类错而项目本身指定了 engines 版本那最好直接用 nvm 切回项目要求的 Node 版本等依赖包修复后再回来。用 nvm 的好处就是这种切换只需要一条命令不用卸载重装。如果你还没装 nvm而是直接改系统 Node碰见不兼容就得手动重装耗时且容易出错。6.5 安装时提示“access is denied”或权限不足Windows 下权限问题主要集中在两个场景一是 nvm 安装目录在 C 盘系统保护目录下二是 Node 的安装目录在C:\Program Files里。解决方式就是安装 nvm 时选择非系统盘路径。如果已经装好了最简单的方式是卸载重装路径选D:\nvm和D:\nodejs。不是非得折腾权限设置。macOS / Linux 下如果遇到权限问题检查~/.nvm的归属用户是否是你当前用户sudo chown -R $(whoami) ~/.nvm6.6 卸载 Node.js 后重新用 nvm 安装还是报错这种情况通常发生在从手动安装 Node 迁移到 nvm 时旧的环境变量残留导致冲突。彻底的清理步骤卸载手动安装的 Node.js 应用删除C:\Program Files\nodejs或你手动安装时指定的目录删除%APPDATA%\npm、%APPDATA%\npm-cache检查并清理系统环境变量中所有含 node 和 npm 的 Path 条目确认.npmrc文件中的配置是否还引用旧目录。清理干净后再执行 nvm 安装新版本基本不会出幺蛾子。7. 我的实操心得和最终建议用 nvm 管 Node 版本这几年我最大的体会是开发环境的稳定性靠的不是记住一堆技巧而是从一开始就把目录规划好。一定要把 nvm 和 Node 版本目录放在非系统盘、无空格、无中文的路径下。很多人默认安装到 C 盘 AppData 里也能用但后来装全局包、配镜像、清缓存总会碰到路径解析的奇怪问题。我见过最离谱的案例是某位同事的用户名是中文npm 全局包里的某个工具因为路径编码问题直接无法启动换目录重装后一切正常。设置好默认版本和镜像源之后再花两分钟把全局包的 prefix 指到统一目录这套环境就能稳定用上很久。后续每次 Node 出新 LTS 版本你只需要nvm install 版本号和nvm alias default 版本号两步零成本升级。老项目需要旧版本时一条nvm use 16.20.2就切过去了完全不影响全局环境。另外再分享一个小技巧项目内最好加上.nvmrc文件里面只写一个版本号比如18.20.4。配合终端里的nvm use或avn自动切换工具进入项目目录就自动加载对应版本彻底告别“我这个项目用哪个版本来着”的困惑。nvm 本身是免费开源的工具GitHub 星星数量足以说明它的可信度放心用就是。