做前端和后端开发这些年我见过太多人被 Node 版本折腾到崩溃老项目锁在 Node 10新项目要求 Node 20直接升级新版旧代码跑不起来装回老版本又没法用新语法。更别说不同项目还要搭配不同 npm、不同 CLI 工具链光靠手改环境变量能把人逼疯。这时候就需要 nvm——Node Version Manager也就是 Node.js 版本管理工具。它能在同一台机器上安装、管理、切换多个 Node 版本彻底解决“一个项目一个版本”的兼容问题。这篇教程把我自己从 Windows 到 macOS 都用过的 nvm 安装、全局配置、版本切换、pnpm 安装、以及各种报错排查经验完整整理出来保姆级到什么程度呢每一步点哪里、每个命令输什么、报错怎么解决都写清楚。适合刚入门 Node 开发的小白也适合被版本兼容问题反复锤的同学直接对着操作。先说明一下这里的 nvm 指的是 Node 版本管理工具不是汽车电子领域常说的 NVM 非易失性存储器后面我会再单独提醒这个区分。1. 动手装之前先把 nvm 的原理和坑位搞清楚1.1 nvm 到底是什么、能解决什么问题nvm 全称 Node Version Manager和它类似的还有 Windows 平台的 nvm-windows、用 Rust 写的 fnm、更轻量的 n。它的核心思想很简单把多个 Node 版本安装到同一个目录下通过修改环境变量或符号链接symlink的方式让系统里node和npm命令指向你当前选中的那个版本。理解这一点特别重要。很多同学误以为 nvm 是在“安装不同的 Node 环境”实际上它只是 Node 版本的“遥控器”。你在终端敲node -v时系统去 PATH 里找到一个叫node的可执行文件nvm 的工作就是让你指定的版本“顶上去”让命令正确地指向它。我在 Windows 上第一次用 nvm 的时候也没整明白直到自己观察了安装目录结构才恍然大悟nvm 目录下有一堆以版本号命名的文件夹比如v16.20.2、v20.11.1还有一个像快捷方式一样的nodejs目录。当你执行nvm use 20.11.1的时候nvm 其实就是在操作这个指向关系。这个认知能帮你省掉后面 90% 的排查时间。1.2 安装前先清理旧的 Node 环境这是整篇教程里最容易跳过、但跳过后最容易出事的一步。如果你电脑上已经装过 Node.js不管是用安装包、Homebrew 还是其他工具装的请先卸载干净再上 nvm。否则后面会出现极其迷惑的现象明明nvm ls显示当前版本是 v20但node -v输出的却是老版本或者 npm 全局命令全都失灵。Windows 上的清理步骤我建议按这个顺序来打开“控制面板 - 程序和功能”卸载所有 Node.js 相关程序包括用 nvm 以后可能残留的旧版本目录。删除残余目录C:\Program Files\nodejs、%APPDATA%\npm、%APPDATA%\npm-cache这几个是重灾区。打开系统环境变量把 PATH 里所有指向 Node.js 安装路径的条目全部删掉尤其是C:\Program Files\nodejs和C:\Users\你的用户名\AppData\Roaming\npm这两条。在命令行执行where node如果还能找到路径说明没删干净继续清理。macOS 上也有类似的残留问题。用 Homebrew 安装过 Node 的执行brew uninstall --ignore-dependencies node、brew cleanup再把/usr/local/lib/node_modules和/usr/local/include/node手动删除。我之前有台旧 Mac 就因为没清理 Homebrew 装的 node装了 nvm 之后nvm use成功了但node -v永远是旧版本查了半小时才发现是 PATH 里 Homebrew 的链接排在了前面。2. Windows 平台安装 nvm-windows 保姆级步骤2.1 下载安装包时的版本选择Windows 上用的其实是 nvm-windows不是官方 nvm-sh 那个版本。官方原版 nvm 只支持 Linux 和 macOSWindows 用户需要去 coreybutler/nvm-windows 这个仓库下载。打开仓库的 Releases 页面找最新稳定版下载nvm-setup.exe这个文件。这里有个细节页面里会同时提供nvm-noinstall.zip和nvm-setup.exe别图省事下免安装版本。nvm-setup.exe 会在安装阶段自动帮你配置好环境变量和目录结构而 noinstall 版本需要手动建目录、手动改 PATH、手动写配置对新手来说每多一步手动操作就多一个踩坑点。我见过不少同学下载 noinstall 版本后装完发现nvm命令找不到其实都是环境变量没配好。我不建议下载超过一年以上的旧版本。nvm-windows 更新不算频繁但老版本在 Windows 11 和新版 PowerShell 下偶尔会有些兼容问题直接选最新正式版最安心。2.2 安装目录设置与两个关键勾选双击nvm-setup.exe后安装向导会要你设置两个路径这里是最多人出错的地方。第一个路径是 nvm 程序本身的安装目录比如D:\nvm建议不要用默认的C:\Users\你的用户名\AppData\Roaming\nvm。不是说默认路径不能用而是这个路径藏在用户目录里层级深、路径长后面你手动找版本目录、改 settings.txt 的时候特别费劲。我自己习惯在非系统盘建一个干净目录专门放 nvm。第二个路径是 Node.js 的符号链接位置默认是C:\Program Files\nodejs。这里有两条铁律第一这个路径不能和 nvm 目录在同一磁盘根路径下冲突第二尽量把它也放在同一个磁盘上避免跨盘符号链接在部分环境下出现奇怪的问题。我的建议是直接把第二个路径改成D:\nodejs一切清爽。安装过程中还会问是否给当前用户还是所有用户安装建议选当前用户避免权限问题。安装结束后打开一个新的终端窗口这一步很重要不重开终端可能读不到新的环境变量执行nvm version能输出版本号就是装成功了。装完之后如果执行nvm version报错“无法将‘nvm’识别为 cmdlet、函数、脚本文件或可运行程序的名称”先检查两点一是环境变量NVM_HOME和NVM_SYMLINK是否已经写入快捷键 WinR 输入sysdm.cpl能打开高级系统设置查看二是终端窗口是不是没有重新打开。2.3 安装后的目录结构说明安装完成后建议打开 nvm 目录看一眼。正常情况下里面会有settings.txt、elevate.cmd、v开头的版本文件夹如果没有装过 Node 就暂时没有。settings.txt是 nvm-windows 的配置文件里面内容类似这样root: D:\nvm path: D:\nodejs node_mirror: https://npmmirror.com/mirrors/node/ npm_mirror: https://npmmirror.com/mirrors/npm/其中root是 nvm 目录path是 Node.js 符号链接目录。后两行镜像配置建议手动加上能在国内网络环境下把下载速度提升好几倍这个我后面单独讲。如果你发现安装后没有D:\nodejs这个目录不用慌这是正常的。这个目录是 nvm 在第一次执行nvm use xxx时才创建的它的本质是一个软链接指向你当前使用的 Node 版本所在目录。理解了这个机制你就知道为什么 nvm 切换版本时 npm 全局包会出现各种“诡异”问题了。3. macOS / Linux 平台安装官方版 nvm3.1 curl 安装脚本与 shell 配置macOS 和 Linux 用户直接用官方安装脚本最省事。打开终端执行以下命令curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash脚本会自动把 nvm 仓库克隆到~/.nvm目录并在你的 shell 配置文件中追加几行环境变量导入代码。执行完后需要让配置生效source ~/.bashrc # 如果用的是 bash source ~/.zshrc # macOS 默认和多数 Linux 用户用的 zsh然后验证一下command -v nvm如果输出了nvm说明安装成功。注意这里是用command -v nvm而不是nvm --version因为 nvm 本身是一个 shell 函数不是可执行文件在非交互式终端里可能检测不到。macOS 上有些同学会同时装了 oh-my-zsh 之类的配置框架如果装了之后command -v nvm没输出多半是.zshrc里没有正确加载。手动检查一下文件末尾是否有一行export NVM_DIR$HOME/.nvm和对应的[ -s $NVM_DIR/nvm.sh ] \. $NVM_DIR/nvm.sh。3.2 网络下载不稳定时的另一种手动安装方式官方安装脚本本质上是执行两条命令先从 GitHub 克隆 nvm 仓库到本地再写入 shell 配置。如果克隆太慢或者直接失败可以手动分步操作。git clone https://github.com/nvm-sh/nvm.git ~/.nvm cd ~/.nvm git checkout v0.39.7然后手动把下面这几行加到 shell 配置文件的末尾export NVM_DIR$HOME/.nvm [ -s $NVM_DIR/nvm.sh ] \. $NVM_DIR/nvm.sh [ -s $NVM_DIR/bash_completion ] \. $NVM_DIR/bash_completion手动方式其实比跑一键脚本更利于理解 nvm 的工作机制以后出问题也知道去哪排查。两条路殊途同归最终实现的效果完全一样。4. 核心命令实操安装、切换、删除、默认版本设置4.1 nvm install 安装指定 Node 版本安装完成并清理好旧环境后第一件事就是装 Node。执行nvm install 20.11.1就会安装 Node 20.11.1 版本。如果你想装当前最新的 LTS长期支持版本或最新版nvm 也支持缩写nvm install --lts nvm install node我自己实际使用的命令和输出大致是下面这个效果$ nvm install 20.11.1 Downloading node.js v20.11.1 (64-bit) Complete Creating new symlink at D:\nodejs Now using node v20.11.1 (64-bit)注意看“Creating new symlink”这一句这就是 nvm 在创建符号链接建立D:\nodejs和D:\nvm\v20.11.1之间的对应关系。如果安装过程卡在 Downloading 阶段很久不动大概率就是默认下载源的问题去 settings.txt 配置镜像源就能解决。一次装好之后再装其他版本就很方便了。一个比较稳妥的策略是装一个 LTS 版本用于日常工作比如 20 系再装一个当前最新版用于尝鲜测试剩下的版本按项目需求再随时装、随时删。4.2 nvm list 与 nvm use 切换版本装好多个版本后用nvm list可以简写成nvm ls查看当前机器上所有已安装版本以及当前正在使用的版本。输出大概是这种风格$ nvm list 20.11.1 * 18.19.1 16.20.2 Current: 18.19.1 (18.19.1)前面带*号的就是当前正在使用的版本。切换版本执行nvm use 20.11.1切换到成功会输出Now using node v20.11.1 (64-bit)此时再执行node -v和npm -v终端里显示的版本应该就是 v20.11.1 了。这里有个重要提醒每切换一次 Node 版本你安装的 npm 全局包都不是“共享”的。这是因为 nvm 切换的是整个 Node 环境npm 全局包的安装目录默认跟随当前 Node 版本变化。很多同学发现nvm use之后pnpm或者vue命令找不到了就是这个原因不是没装成功而是装到了另一个版本的环境里。4.3 设置默认版本与 .nvmrc 项目级配置每次打开新终端nvm 默认会启用你在安装时设置的默认版本不nvm 不会自动记住你最后一次 use 的版本它会读取一个叫 default 的别名设置。设置默认版本nvm alias default 20.11.1设置之后下次打开终端node 版本自动就是 v20.11.1。这个步骤非常建议做否则每次开新终端都要手动nvm use一次非常影响体验。更专业一点的做法是给每个项目单独指定 Node 版本。在项目根目录创建一个.nvmrc文件里面只写版本号20.11.1然后在项目目录下运行nvm use如果当前目录有.nvmrc文件nvm 会自动读取其中的版本号并切换到对应版本。如果这个版本还没安装命令会提示你手动执行nvm install。这个习惯一旦养成团队协作时每个人跑同一套代码Node 环境完全一致很多“我本地能跑你本地不行”的问题就从根本上消失了。5. 全局配置npm 镜像源、全局包与 pnpm 安装5.1 配置 npm 仓库镜像源Node 装好后接下来第一件要配置的事就是 npm 镜像源。不配置的话安装依赖会非常慢有些包甚至装不上。这里建议把 npm registry 配置到国内镜像执行npm config set registry https://registry.npmmirror.com然后确认一下是否生效npm get registry输出应该是https://registry.npmmirror.com/。这个配置不影响任何项目代码它只管 npm 下载依赖包时去哪里拉取。同样地nvm 下载 Node 本身也是用默认的官方源如果装 Node 的时候一直卡住可以在 nvm 配置文件 settings.txt 里追加两行镜像配置这个我前面已经展示过。配置完之后下载 Node 版本的体验会顺畅非常多。5.2 用 nvm 环境安装 pnpm 的两种方式pnpm 是现在非常主流的包管理器相比 npm 的核心优势是磁盘空间占用小、安装速度快因为它是通过硬链接和内容寻址来复用依赖的。在 nvm 环境下pnpm 和 npm 全局包一样面临“版本切换后命令消失”的问题所以安装策略很重要。第一种方式直接通过 npm 全局安装npm install -g pnpm装完后执行pnpm -v验证。切换 Node 版本后如果pnpm命令找不到处理方式是在当前版本重新执行一次安装命令。第二种方式是使用 Node 自带的 corepack。Node.js 16.9 开始内置了 corepack是一个官方出的包管理器管理工具corepack enable corepack prepare pnpmlatest --activate启用后pnpm 会通过 corepack 来管理体验上会更顺滑一些。但要注意 corepack 本身也有版本在某些 Node 版本下会有兼容细节问题如果遇到报错可以回到第一种 npm 全局安装方式。关于“要不要在每个 Node 版本都装一遍全局包”我的建议是如果某个工具pnpm、vue-cli、vite、http-server是你每天都要用到的那就在你常用的 LTS 版本里统一装好偶尔用一次的工具建议用npx临时调用避免全局包数量失控。全局包装得越少版本切换后的“灵异事件”就越少。5.3 “nvm 安装及全局配置 node”的完整流程串一遍把前面所有内容连起来“nvm 安装及全局配置 node”其实是一条完整链路。我在新电脑上从零操作时顺序是固定的卸载电脑上所有旧 Node删除环境变量里的 Node 残留路径。安装 nvm-windows或 Linux/macOS 安装官方 nvm验证nvm version或command -v nvm。执行nvm install --lts安装 LTS 版本。执行nvm alias default 版本号设置默认版本。执行npm config set registry https://registry.npmmirror.com配置 npm 镜像。执行npm install -g pnpm安装包管理器。在项目根目录创建.nvmrc文件锁定项目版本。这条链路走完你的 Node 开发环境就是一套可以长期稳定使用的配置了后续不管接到什么老项目、新项目只要切版本就行不用再动系统。6. 高频踩坑与排查实录6.1 常见报错速查表我整理了自己和身边朋友最常遇到的几个 nvm 相关报错做成一个速查表方便你直接定位问题。报错现象根本原因解决办法无法将“nvm”识别为 cmdlet、函数、脚本文件或可运行程序的名称nvm 未安装成功或 PATH 环境变量未生效重开终端检查 NVM_HOME 环境变量重新运行 nvm-setup.exenvm use报错 “exit code 5”Windows 上符号链接创建需要管理员权限以管理员身份重新打开终端再执行nvm usenvm install卡住不动默认下载源网络缓慢在 settings.txt 配置 node_mirror 和 npm_mirror 镜像源node -v显示的还是旧版本系统 PATH 顺序里面旧 Node 路径排在前面检查并删除旧 Node 的所有环境变量路径切换版本后pnpm或全局 CLI 命令找不到npm 全局包是按版本隔离的在当前版本下重新执行npm install -g 包名无法将 F:\nvm\nodejs\node_modules\...\claude.exe 或类似路径的程序识别为命令某个全局 CLI 是在旧版本下安装的切换到新版本后路径失效重新安装该全局工具或切回原 Node 版本后先卸载再重装最后一行那个报错在热词里大家搜得比较多我单独说明一下。以F:\nvm\nodejs\node_modules\...这类路径为例它意味着你曾经在某个 Node 版本下通过 npm 全局安装了一个 CLI 工具这个工具实际被放到了当前 Node 版本的node_modules目录里。一旦nvm use把符号链接切换到另一个版本系统再去找原来的路径就找不到了。解决办法很简单在当前使用的 Node 版本下重新执行一遍全局安装命令让工具重新在当前版本的全局目录里生成一份可执行文件。6.2 settings.txt 手动配置镜像与目录字段nvm-windows 的settings.txt是整个 Windows 端 nvm 的核心配置文件它放在 nvm 安装根目录下。前面我给出的模板已经包含了最关键的四个字段。我建议在一开始安装完就顺手把镜像配置写好别等下载卡住了再临时改。root和path两个字段尤其重要。root是 nvm 本身的位置path是当前 Node 版本符号链接的位置。安装完如果发现手动改了目录记得两个字段要同步更新不然会出现 nvm 显示版本切换成功了但node命令实际指向的还是老地方这种情况。6.3 安装后 node、npm 命令不存在的排查思路有时候你明明执行了nvm install输出也显示下载完成了但node -v依然报错“不是内部或外部命令”。这种情况九成是符号链接没有被正确创建。Windows 上最常见的触发原因是权限不够用管理员身份执行一次nvm use创建出nodejs目录问题就会迎刃而解。macOS 和 Linux 上则多一个需要检查的点查看当前 shell 的启动配置文件.bashrc还是.zshrc里是否真的加载了 nvm 的初始化脚本。有些终端模拟器默认不会加载登录 shell 的配置导致 nvm 函数没有注入也会出现明明装了但命令不可用的情况。还有一个小细节Node 安装完成后node -v正常但npm -v找不到这种情况通常在 Windows 上更常见一些一般是因为 npm 的 cmd 脚本和 PATH 中某个旧路径冲突。执行where npm查看路径把不合理的项删掉就行。6.4 顺带提醒开发工具的 nvm 和汽车电子里的 NVM 不是一回事最后插播一个容易混淆的点。搜“nvm”的时候很多人会看到“Simulink NVM 读写”这类结果这里的 NVM 是 Non-Volatile Memory中文叫非易失性存储器是嵌入式系统和汽车电子比如 AUTOSAR 架构里的 NvM 模块中的概念负责 ECU 的数据存储管理和 Node Version Manager 完全是两个领域的东西。如果你在汽车电子或嵌入式开发相关岗位看到“NVM”的招聘术语和文档要把它当作“非易失性存储器”来理解别和前端开发里的 nvm 搞混。我在公司内部群里就不止一次看到有人问“nvm 怎么在 Simulink 里读写”其实对方需要的完全是另一套知识体系了。实操后的几点心里话整套 nvm 环境搭完最直观的感受就是省心。以前每接一个新项目都要折腾一遍 Node 环境现在只需要nvm use一下项目能跑起来版本切换的烦恼基本离我远去了。如果让我给刚开始用 nvm 的同学提三个建议我会说第一默认版本一定设好避免每次开终端都手动切换第二全局安装的包尽量精简只在最常用的 LTS 版本里装第三每个项目都习惯性地配上.nvmrc这是团队协作里成本最低、收益最高的规范之一。还有一个我一直保留的细节每次nvm install新版本后我会第一时间装一遍 pnpm 并配置好 npm 镜像源免得切换新版本后想起来要用工具才发现全局包是空的。把这个动作养成肌肉记忆你的 Node 工作流就会一直顺畅。