装 Node.js 这件事很多人第一次做的时候觉得「官网下个包下一步下一步就完事了」等到手上同时维护两三个项目、每个项目锁的 Node 大版本还不一样才发现整台机器只有一个全局 node 有多难受——老项目跑不起来提示语法不认识新项目又要求某个较新的运行时来回卸载重装装完还忘了当时装的是哪个版本全局装的命令行工具也一并没了。这篇 nvm 下载与安装全指南就是把 Windows 和 macOS 两条线上的安装、配置、切版本、踩坑全部摊开讲一遍。nvm 全称 Node Version Manager是一个纯粹的版本管理工具它干的事情很单一让你在同一台机器上装多个 Node.js 版本并且能在一条命令之内切换。它适合刚配环境的新手也适合手上挂着多个仓库、需要在不同运行时之间来回跳的老手只要你写前端、写 Node 服务、或者维护一些带历史包袱的构建脚本这个工具基本属于必备件。下面按我自己的实际配置顺序走一遍中间会穿插一些只能靠踩坑才记得住的细节。1. 先搞清楚两条产品线nvm 在 Windows 和 macOS 上根本不是同一个东西这是新手最容易栽的第一个坑。搜「nvm 安装」出来的教程一半是 macOS/Linux 的 shell 脚本方案一半是 Windows 的 exe 安装包方案两边的命令长得像但行为不一样配置文件格式也完全不同。照着 A 的教程在 B 的机器上敲报错能让你怀疑人生。所以动手之前先把这几件事分清楚后面能省掉一大半排查时间。1.1 同一个名字两套实现macOS 和 Linux 上通用的那个叫nvm-sh本质是一个纯 shell 脚本源码 clone 到~/.nvm目录靠在你的 shell 配置文件里 source 一个nvm.sh来注入函数。它的切换原理是修改 PATH 环境变量把~/.nvm/versions/node/vX.Y.Z/bin顶到最前面去所以切换是「逻辑切换」磁盘上多个版本是并存的互不干扰。Windows 上那个叫nvm-windows是另一个作者用 Go 语言重写的独立项目跟 nvm-sh 没有代码关系。它的切换原理完全不同它在你指定的位置建一个叫nodejs的目录符号链接指向具体的版本目录然后把nodejs这个目录塞进系统 PATH。切版本的时候它其实是在删掉旧链接、建一个新链接。理解这一点非常关键后面 Windows 上那一堆「拒绝访问」「权限不足」的报错根子全在这儿。Windows 上还有个叫nvs的项目功能相近但生态小得多公司内部如果没统一要求我一般不建议选社区问答里能搜到的解决方案少一大截。1.2 和另外几种方案的横向对比知道有别的选择才能在团队里说服别人。下面这张表是我在几个不同规模的项目里实际用过之后的体感对比方案跨版本切换是否改 PATH项目级版本文件典型适用场景nvm-sh / nvm-windows支持命令切换是支持.nvmrcWindows 需借助插件多项目并存、需要频繁切大版本n支持是不支持单人 Mac 环境追求简单Volta支持且能锁工具链是支持写进 package.json团队统一工具链、CI 一致性要求高官网安装包直装不支持是不支持只跑一个固定项目、临时验证我为什么最终还是回到 nvm它出现得早资料最多几乎每个报错都能搜到现成答案.nvmrc虽然简单但约定俗成配合nvm use就够了。Volta 的方案更优雅把 node 和 npm 版本一起锁进package.json但它的自动切换依赖 shell hook某些远程终端或容器里会失灵排查起来比较绕。所以这篇只讲 nvm不铺开。1.3 一个必须先确认的判断标准动手之前问自己一个问题我是不是只需要一个 Node 版本如果答案是需要两个以上装 nvm如果只是临时跑个 demo用完就删那直接下官方安装包装一次反而更省事装 nvm 属于杀鸡用牛刀还得额外清一遍残留。还有一点要强调nvm 和你系统里已经装过的 Node.js 是冲突的。不是「可能冲突」是必然冲突。因为两者都想往 PATH 里塞自己的 node 可执行文件谁排在前面谁生效结果就是版本显示乱跳、node -v和npm -v对不上号。所以第二步永远是先清场再装。2. 安装前的清场卸载旧 Node 和清理残留跳过这一步的人十个里至少有六个会在装完之后遇到「nvm 显示切到了 A 版本但node -v还是 B 版本」的鬼故事。原因就是旧的安装包把node.exe或node留在了系统目录里PATH 里它排在前面。清场这一步花不了五分钟能省掉后面两小时。2.1 Windows 卸载顺序Windows 上正确的顺序是按下面的步骤顺序错了容易留下残渣打开「应用和功能」找到所有名字里带 Node.js 的条目逐个卸载。如果之前装过多个版本会看到多条记录全部卸掉。手动检查并删除残留目录C:\Program Files\nodejs、C:\Program Files (x86)\nodejs、%APPDATA%\npm、%APPDATA%\npm-cache。打开系统环境变量设置检查用户变量和系统变量两个地方的Path把任何指向nodejs、npm的条目删掉。这一步最容易被忘因为有的人装 Node 时勾了「加入 PATH」卸载程序并不会把它清干净。打开新的命令行窗口旧的不会重新加载环境变量执行where node如果还能输出路径说明还没清干净回到第 3 步继续找。where这个命令比node -v有用得多因为它会把所有同名可执行文件的路径全列出来你能一眼看出是哪一个在捣乱。macOS 上对应的是which -a node。2.2 macOS 卸载与全局包备份macOS 上旧版 Node 通常是 pkg 安装的卸载方式不太直观按这个顺序来# 列出所有 node 相关文件先看清楚再删 ls -l /usr/local/bin/node ls -l /usr/local/bin/npm # 如果是 pkg 装的删掉这些 sudo rm -rf /usr/local/lib/node_modules sudo rm -rf /usr/local/bin/node sudo rm -rf /usr/local/bin/npm sudo rm -f /usr/local/share/man/man1/node.1卸载前先把全局安装的包记下来这步非常值得做。执行npm ls -g --depth0把输出存到一个文本文件里。后面重装完 Node靠这份清单重新装一遍全局工具比凭记忆一个个想去靠谱得多。我自己吃过这个亏某次重装后忘了装某个命令行脚手架隔了两周项目编译才报错翻日志翻了半天才想起来是全局包没了。2.3 目录规划上的两个硬性要求无论哪套系统nvm 的安装目录都有两个不能碰的红线路径里不能有中文和空格。Windows 默认把 nvm 装在C:\Users\你的用户名\AppData\Roaming\nvm如果你的用户名里有中文直接改成D:\dev\nvm这种纯英文短路径。空格同理C:\Program Files\nodejs这个默认值经常会引发一些工具脚本的解析问题能改成C:\dev\nodejs就改。不要放在需要管理员权限才能写的位置。nvm 每次装新版本都要往这个目录里写文件如果目录归 root 或 SYSTEM 所有普通权限的命令行会直接失败。至于权限本身Windows 上首次安装建议右键「以管理员身份运行」装完之后的日常nvm install、nvm use也建议在管理员终端里做原因后面 6.1 会展开。macOS 上则相反不要用 sudo 跑安装脚本脚本会在你的家目录下建~/.nvm用 sudo 建出来的目录属主是 root后面每次nvm install都要 sudo非常难受。3. Windows 实装从安装包到第一个可用版本Windows 这条线的步骤比 macOS 多主要是多了一层配置文件要改。但改完之后体验很省心值得花十分钟配好。3.1 获取安装包去项目的 Release 页面下载nvm-setup.exe即可不要下nvm-noinstall.zip那个是给需要绿色部署的场景准备的要手动配环境变量对新手不友好。下载完成后如果有校验值就顺手对一下文件哈希命令行里用certutil -hashfile nvm-setup.exe SHA256就能看虽然这一步很多人跳过但下载大文件时我习惯性会看一眼尤其是从第三方镜像站点拿包的时候。3.2 安装向导里两个必须改的地方安装向导会问你两个路径这两个都不能无脑点下一步nvm 的安装目录也就是存放各个 Node 版本和配置的地方。建议改成D:\dev\nvm这类短路径。nodejs 的符号链接目录安装向导里显示为「Node.js Symlink」默认是C:\Program Files\nodejs。建议改成D:\dev\nodejs理由同上避开空格。为什么这个 symlink 目录要单独设因为 nvm-windows 的切换逻辑是把D:\dev\nodejs这个链接指向D:\dev\nvm\v18.20.4而系统 PATH 里只有D:\dev\nodejs一条。这样无论你装多少版本PATH 都只有一条记录永远不用改环境变量。理解了这一层你就能明白为什么不能在这两个目录里手动放任何文件——会被链接覆盖或者覆盖链接导致切换失败。安装完成后务必关掉所有已经打开的终端窗口重新开一个新的。安装程序改的是系统环境变量已存在的终端进程读的还是旧快照。这一点我在第一次装的时候没注意对着新窗口敲nvm version死活没反应折腾了半小时才发现是老终端的问题。3.3 settings.txt整个 Windows 方案里最值得改的文件打开 nvm 安装目录会看到一个settings.txt。默认内容大概是两行root和path我一般会把它补成下面这样root: D:\dev\nvm path: D:\dev\nodejs arch: 64 node_mirror: https://npmmirror.com/mirrors/node/ npm_mirror: https://npmmirror.com/mirrors/npm/逐行解释一下为什么这么写。root和path必须和安装时选的一致写错了会导致nvm use找不到版本目录。arch: 64是明确指定拉 64 位包虽然默认也是 64但写死可以避免在某些老机器上误判。后面两行node_mirror和npm_mirror是官方支持的镜像配置项作用是把下载地址指向一个响应更快的公共源——国内网络环境下直接连官方源下载大版本经常卡在百分之几然后超时改完这两个地址下载速度通常能快一个数量级。注意settings.txt的格式对空格很敏感冒号后面要有一个空格路径里不要带引号也不要加任何注释行。改完保存后重开终端才生效。另外这个文件在老版本里的字段名略有差异如果写了不生效先执行nvm version确认版本再去对应版本的文档里核对字段名。3.4 装第一个版本并验证# 查看当前 nvm 版本确认装好了 nvm version # 列出远端可安装的版本这一步会联网拉取列表 nvm list available # 安装一个 LTS 版本 nvm install 20.11.1 # 切换过去 nvm use 20.11.1 # 验证三件套 node -v npm -v nvm listnvm list的输出里当前正在使用的版本前面会带一个*这是 nvm-windows 独有的标记方式很好认。如果node -v报「不是内部或外部命令」别急先看nvm list里有没有星号再看D:\dev\nodejs这个链接目录是否存在。这两步能定位掉八成问题。还有一个细节值得提醒nvm list available拉的列表里有LTS和Current两栏日常开发优先选 LTS。Current 线上的版本生命周期短一些构建工具的原生模块还没跟上装完可能编译报错。我自己的习惯是新项目起步用最新 LTS等真正需要某个新特性时再单独升。4. macOS 实装两种装法各有取舍macOS 上的选择更多我常用的有两种官方脚本安装和 Homebrew 安装。两者都能用但后续维护方式不一样选之前先看清楚差异。4.1 脚本安装的完整流程这是最贴近官方的做法也是最不容易出玄学问题的# 方式一直接执行安装脚本 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash如果你所在的环境对直接从远端执行脚本比较谨慎这其实是好习惯可以改成先下载再检查再执行curl -o install_nvm.sh https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh less install_nvm.sh # 先看一眼内容 bash install_nvm.sh脚本做三件事把仓库 clone 到~/.nvm在~/.zshrc或~/.bash_profile取决于你的 shell末尾追加一段 source 代码提示你重开终端或手动 source。追加的那段代码长这样export NVM_DIR$HOME/.nvm [ -s $NVM_DIR/nvm.sh ] \. $NVM_DIR/nvm.sh [ -s $NVM_DIR/bash_completion ] \. $NVM_DIR/bash_completion第一行定义目录变量第二行判断文件存在才 source避免目录被误删后每次开终端都报错第三行是可选的命令补全加上之后敲nvm ins按 Tab 能自动补全成nvm install日常用起来很顺手。如果脚本执行完重开终端后nvm仍然提示 command not found先执行echo $SHELL看当前用的是哪个 shell。zsh 读~/.zshrcbash 读~/.bash_profile或~/.bashrc两者不通用。当年我换了默认 shell 却没转移配置卡了很久才反应过来。4.2 Homebrew 安装的差异与清理注意brew install nvm mkdir ~/.nvmHomebrew 装完之后不会自动帮你写 source 配置必须手动在~/.zshrc里加一行export NVM_DIR$HOME/.nvm [ -s /opt/homebrew/opt/nvm/nvm.sh ] \. /opt/homebrew/opt/nvm/nvm.sh路径要注意区分Apple Silicon 机器上前缀是/opt/homebrewIntel 机器上是/usr/local。写错了就是找不到文件。两种方式怎么选我的实际经验是如果你不是重度使用 Homebrew 管理一切的人优先选脚本安装。原因是 brew 装的 nvm 在升级时可能被brew upgrade一并动到而 nvm 的版本升级本身很轻量未必需要跟着 brew 走更麻烦的是一旦哪天决定改回脚本安装~/.nvm目录和 brew 版本会互相干扰得先brew uninstall nvm再清掉残留的配置行把.zshrc里两段 source 都删干净否则一个终端里可能出现两个 nvm 函数。4.3 装第一个版本与默认版本设置macOS 这边命令和 Windows 略有差别尤其是「默认版本」这个概念# 直接装最新 LTS nvm install --lts # 设为默认新开终端自动生效 nvm alias default 20 # 查看本地已装版本 nvm ls # 查看远端可安装版本 nvm ls-remote --lts # 查看当前正在用哪个 nvm currentnvm alias default 20这一步千万不能省。nvm-sh 的机制是每次新开终端自动激活default别名指向的版本。如果不设某些配置下会变成没有默认版本新开终端敲node直接 command not found得手动nvm use一次才行。这也是从 Windows 迁过来的人最容易踩的坑——nvm-windows 有nvm on的概念帮你启用nvm-sh 没有靠的就是别名。顺便说一句nvm ls-remote的输出可能很长几百行刷屏。我一般配合管道过滤nvm ls-remote --lts | tail -20只看最近的几个 LTS 版本号比在一堆数字里找眼球舒服得多。5. 日常使用命令对照与项目级版本锁定装完之后真正的日常操作其实就五六条命令但两套实现的命令名有细微差别混着记容易出错。下面这张表是我贴在笔记里的对照表建议存一份。5.1 两套实现的命令差异速查用途nvm-windowsnvm-shmacOS/Linux查看 nvm 自身版本nvm versionnvm --version列出已安装版本nvm listnvm ls列出可安装版本nvm list availablenvm ls-remote安装指定版本nvm install 20.11.1nvm install 20.11.1切换版本nvm use 20.11.1nvm use 20.11.1设置默认版本无直接命令nvm alias default 20查看当前版本nvm list带*nvm current卸载某版本nvm uninstall 18.0.0nvm uninstall 18.0.0启用/停用nvm on/nvm off无此概念全局包迁移不支持nvm reinstall-packages version注意nvm list available这个写法老版本的 nvm-windows 用的是nvm ls available两个都能用但新版本推荐前者。如果你敲了没反应换另一种写法试试。5.2 用 .nvmrc 把版本写进仓库这是团队协作里性价比最高的一个小习惯。在项目根目录放一个.nvmrc文件内容就一行版本号20.11.1然后nvm use不带参数执行它会自动往下找最近的.nvmrc并切换过去。macOS 上这个能力是原生的Windows 上 nvm-windows 本身不读.nvmrc需要借助一个叫nvm-use的 PowerShell 脚本或第三方包或者干脆在package.json里加一个脚本{ scripts: { node:version: node -v } }我在跨平台团队里推的做法更朴素.nvmrc照放README 里写一句「Windows 用户请手动执行nvm use 20.11.1」。虽然不够自动化但零依赖、零成本比强上一个团队里一半人跑不起来的自动切换方案务实。另外记得把.nvmrc提交进版本库不要在.gitignore里把它排掉。我见过有项目把它当本地配置文件忽略掉的结果新人拉下来跑构建直接报 Node 版本不匹配还得在群里问一句「你们用的哪个版本」。5.3 全局包的跨版本迁移nvm 的一个设计取舍是每个 Node 版本有独立的全局包目录。你在这个版本下装的命令行工具切到另一个版本后就没了。这个设计从隔离性上说是对的但从使用体验上确实烦人。macOS 上有现成的解法# 把旧版本下的全局包全部重装到新版本 nvm reinstall-packages 18.20.4Windows 上没有对应命令只能手动来nvm use 18.20.4 npm ls -g --depth0 # 记下清单 nvm use 20.11.1 npm install -g 包名1 包名2 包名3这个流程我优化过一版用npm ls -g --depth0 --json输出成 JSON再用一个几行的脚本提取包名批量重装。虽然一次性工作但如果你经常切版本这十几行脚本能省掉不少重复劳动。写不写脚本另说养成切完版本后确认一次npm ls -g --depth0的习惯比什么都管用。5.4 npm 自身的版本也要管Node 大版本切换的时候npm 版本也会跟着变npm 是跟着 Node 一起分发的。有些项目对 npm 版本有要求比如锁文件格式lockfileVersion在不同 npm 大版本间会变混用会导致npm ci报错或者包解析结果不一致。简单做法是在项目里用一个包管理器的字段声明或者干脆记录在 README 里。如果你希望更严格地控制可以在package.json里加上{ engines: { node: 20.0.0 21, npm: 10.0.0 } }engines字段默认只是警告不阻断配合.npmrc里的engine-stricttrue才会变成硬性检查。这个开关要不要开看团队情况开了之后 CI 上能提前暴露版本不一致的问题但也会让一些临时调试变得麻烦。6. 报错排查实录那些文档里不会写的坑下面这些是我自己和同事在实际配置过程中真实遇到过的问题按平台归类整理每条都写了排查路径遇到时可以直接对号入座。6.1 Windows 上的高频问题问题一nvm use报exit status 1: 拒绝访问或者exit status 145。这是出现频率最高的一条。根因是创建目录符号链接需要权限普通终端没有。解法有三个一是用管理员身份运行终端二是去「本地安全策略」里给当前用户授予「创建符号链接」的权限三是临时关掉系统的开发者模式限制。我通常直接用第一种最省事。如果管理员终端也报错那多半是nodejs这个链接目录被某个进程占用着——比如你开着 VS Code它的终端或者某个插件正持有该目录下的文件句柄把编辑器全关掉再试。问题二切完版本node -v还是老版本。按这个顺序查先where node看输出里有几条路径。如果出现两条以上说明旧的 Node 没卸干净回到第 2.1 节重做。如果只有一条但路径不对检查系统环境变量里是不是还留着旧的nodejs路径。还有一种隐蔽情况你在某个终端里手工set PATH过那个终端会一直用旧快照重开才行。问题三nvm install卡在下载进度条半天不动。先确认settings.txt里的两个 mirror 字段写对了。改完还是慢的话可以临时用命令行参数指定nvm install 20.11.1 --insecure跳过证书校验仅用于排查是不是证书链问题。如果排查下来确实是源的问题把 mirror 换一个公共镜像地址再试。这里提醒一句镜像地址会变动写进文档的固定地址过一段时间可能失效遇到 404 时先去项目主页确认当前可用的地址。问题四安装时提示路径包含空格。回头改安装目录C:\Program Files这种路径能不用就不用。已经装完的可以重装一次或者在settings.txt里把路径改成不含空格的再把旧目录内容整体挪过去。6.2 macOS 上的高频问题问题一装完重开终端nvm命令找不到。九成是 shell 配置文件没对上。echo $SHELL确认当前 shellzsh 看~/.zshrcbash 看~/.bash_profile。还有一种情况是配置写进去了但没生效手动source ~/.zshrc一次看报什么错。如果 source 时报nvm.sh: No such file or directory说明~/.nvm目录不存在脚本可能中途失败了重新跑一遍安装脚本。问题二nvm install编译原生模块失败。这在 Apple Silicon 机器上装较老的 Node 版本时常见。原因是老版本没有预编译的 arm64 包nvm 会退回到源码编译而编译需要 Xcode 命令行工具。先执行xcode-select --install装好工具链再重试。如果还是失败装个稍新的版本通常就绕过去了因为 Node 16 之后的版本对 arm64 的支持是完整的。问题三nvm use之后新开终端又变回去了。没设默认别名。执行nvm alias default 版本号即可。另外检查一下.zshrc里有没有别的地方在改 PATH比如某些工具安装时会往配置文件里追加自己的路径把 nvm 的 source 挤到了后面导致顺序错乱。这种情况把 nvm 的 source 段落挪到文件末尾通常能解决。问题四Homebrew 和脚本安装混用之后行为诡异。which nvm看指向哪里type nvm看是函数还是可执行文件。如果两条 source 配置同时存在删掉其中一段重开终端。6.3 排查思路速查表现象优先检查常见根因切换后版本不变where node/which -a node旧版 Node 未卸干净PATH 残留命令找不到echo $SHELL 配置文件source 段落写错文件或未生效安装卡住/超时settings.txt的 mirror 字段源地址不可达权限拒绝是否管理员 / 目录属主符号链接权限不足新终端版本回退nvm alias default未设默认别名全局包消失npm ls -g --depth0各版本全局目录独立属正常行为原生模块编译失败xcode-select -p缺少编译工具链7. 几条只能靠踩坑记住的经验配环境这件事文档能教你的部分是有限的剩下全靠自己撞过几次。下面几条是我在不同机器、不同团队里反复验证过的心得写下来省得你再走一遍。第一永远不要在项目目录里装 nvm。有些人图省事把 nvm 装到项目文件夹下结果提交代码时把整个~/.nvm里几百兆的 Node 运行时一起推上去了。nvm 的目录必须是全局的、独立于任何仓库的。第二版本号的写法要统一。nvm install 20、nvm install 20.11、nvm install 20.11.1三种写法都能用但它们装出来的东西在不同版本上行为不完全一致——早期版本对20这种大版本号的支持不好可能报找不到。我的习惯是永远写全三位.nvmrc里也写全三位避免解析歧义。第三切版本之前先想清楚有没有后台进程在跑。特别是 Windowsnvm use需要重建符号链接如果此时有一个node进程正在运行比如某个 dev server 没关链接删不掉命令就会失败。养成切版本前先停掉所有 dev server 的习惯。第四LTS 不等于「永远安全」。LTS 版本之间也会有破坏性变更尤其是跨大版本升级时原生模块需要重新编译、部分 API 被废弃。升级前把项目的锁文件保留一份出问题能快速回滚。第五把配置过程写进团队文档。这一条听起来像废话但真的有用。我自己维护的团队文档里有一页「环境初始化」把 nvm 安装、镜像配置、.nvmrc约定、常见报错都写进去了新人 onboarding 的时间从半天压缩到二十分钟。文档不用写得多漂亮把命令和坑列清楚就够。第六别急着追最新版本。每次新 Node 大版本发布总有人第一时间升上去然后发现某个构建插件不兼容回滚。我的做法是新版本发布后观察一两个月等主流工具链都跟上了再切中间用 nvm 装一个临时版本验证一下即可反正多装一个版本的成本几乎为零。最后分享一个我自己一直在用的小技巧在.zshrc里加一个别名nvm-lts内容是nvm install --lts nvm alias default lts/*需要换到最新 LTS 的时候一条命令搞定Windows 上则在 PowerShell 的 profile 里加一个函数做类似的事把nvm install、nvm use、npm ls -g三步串起来。这类小封装不起眼但每天省下的十几秒一年下来也是实实在在的时间。