起因是一件很小的事：同一个脚本，我在终端里手动跑一切正常，丢进定时任务里却开始报错。打印运行时路径才发现，脚本命中的 node 跟我日常终端用的那个根本不是同一个二进制——一个 v22.22.1，一个 24.x。那一刻我忍住了「再装一个新 node 盖过去」的冲动，决定先给这台 Apple Silicon Mac 的开发环境做一次全量归因：把所有运行时点名、把两套 shell 的解析结果摆在一起对比、把全局包的家底盘清楚，然后才动手。
这台机器的来历不短：最早用官方案 pkg 装过 node，后来上了 nvm 管项目版本，中途又图省事 brew install 过 node 和 pnpm，几年下来谁也没管过谁。多运行时共存本身不可怕，可怕的是它们各自服务的场景不一样，而没有任何一处文档写清楚「哪个环境用哪个」。
这篇文章记录我盘点和整合多 Node 共存的完整踩坑过程。每个坑都按「现象 → 排查 → 解法 → 复盘」的顺序写，命令都是我实际敲过的原样（下文为便于阅读，把家目录统一写成 ~，真实输出里是完整绝对路径）。
坑一：一台机器上躺着三套 node
现象：node -v 在终端里是 v22.22.1，脚本里却是 24.x。第一次全面点名，问题就藏不住了：
$ which -a node npm npx pnpm yarn bun deno
~/.nvm/versions/node/v22.22.1/bin/node
/opt/homebrew/bin/node
/usr/local/bin/node
~/.nvm/versions/node/v22.22.1/bin/npm
/opt/homebrew/bin/pnpm
~/.bun/bin/bun
~/.deno/bin/deno
三条 node 来自三个安装渠道：nvm（default 是 v22.22.1）、Homebrew（node@24）、以及当年官方案 pkg 装进 /usr/local/bin 的旧版（node 20）。npm/npx 也跟着重复。谁先出现在 PATH 里谁说话，而 PATH 的顺序在两种 shell 里还不一样。
排查：关键一步是分别对比登录 shell 和交互 shell 的解析结果：
$ zsh -lc 'which node'
/opt/homebrew/bin/node
$ zsh -ic 'which node'
~/.nvm/versions/node/v22.22.1/bin/node
两条命令输出不同——这就是整套环境分裂的核心病灶：nvm 是在 .zshrc 里加载的，只有交互式终端会读到它；而 launchd、cron、脚本走的是登录环境的 PATH，直接命中了 brew 装的 node。再顺手看 PATH 全貌：
$ zsh -lc 'echo $PATH' | tr ':' '\n' | cat -n
能翻出不少重复段，典型来源是 .zprofile、.zshrc 和 brew shellenv 互相叠加，同一个目录出现两三次。
解法：不是去卸某个 node 碰运气，而是把脚本环境的 PATH 统一。在 .zprofile 顶部把 nvm default 版本的 bin 目录加进 PATH，版本号从 ~/.nvm/alias/default 动态读取，绝不写死（写死了下次 nvm 切版本又是一轮新的分裂）：
# 改配置前先备份，删除/修改类操作全走可恢复
cp ~/.zprofile ~/.zprofile.bak-$(date +%Y%m%d)
# .zprofile 顶部加入：
NVM_DEFAULT="$(cat "$HOME/.nvm/alias/default")"
export PATH="$HOME/.nvm/versions/node/v${NVM_DEFAULT#v}/bin:$PATH"
改完验证，两条命令必须输出同一个路径：
$ zsh -lc 'which node' && zsh -ic 'which node'
~/.nvm/versions/node/v22.22.1/bin/node
~/.nvm/versions/node/v22.22.1/bin/node
复盘：npm 包的 engines 字段只约束包本体；CLI 的 shebang 是 #!/usr/bin/env node，实际跑在哪个 node 上完全由调用方的 PATH 决定。所以「统一 PATH」比「装某个版本的 node」更关键——只要登录和交互两种环境的解析不一致，装多少遍都会再分裂。这也是为什么排查的第一步永远是 zsh -lc 与 zsh -ic 各跑一遍对比，而不是盯着终端里的 node -v 发愣：终端看到的只是交互环境那半张脸，报错的脚本看到的是另一半。
顺带一提，动态读版本还有个细节：~/.nvm/alias/default 里写的可能是具体版本号，也可能是 lts/* 这类别名，拼 PATH 前要按文件实际内容处理 v 前缀和别名解析，别天真地直接字符串拼接。我的做法是确认 default 固定为一个具体版本号，让 .zprofile 的拼接逻辑保持简单可预测。
坑二：全局 npm 包散落在三个 prefix
现象：PATH 统一了，全局命令却还是乱。同一个工具，~/.npm-global 里一份、nvm 目录里一份、brew 里还有一份，版本各自漂移，升级其中一个，另一个纹丝不动；更糟的是 command -v 指到哪份全看 PATH 运气，出问题时你根本说不清此刻执行的是哪个版本。
排查：三处 prefix 逐一列全再归口：
ls ~/.npm-global/bin # 用户约定的 prefix
ls ~/.nvm/versions/node/v22.22.1/lib/node_modules # nvm 自己的一份
ls /opt/homebrew/lib/node_modules # brew 的一份
brew 那份最难查，因为软链在 /opt/homebrew/bin，包体在 lib 下。我是从每个包的 package.json 读 name/version/bin 生成了一份清单，才把所有命令对上了号。
解法：全部迁到约定的 ~/.npm-global（直接往 /usr/local 装会报 EACCES）：
npm install -g --prefix ~/.npm-global --ignore-scripts <各旧包>@latest
迁完逐个 --version 实测，不能只信安装回执。有个坑：个别 bin 不在包的 package.json 里声明（比如 typescript 的 tsserver），npm 不会为它建软链，要手动补：
ln -sf ../lib/node_modules/typescript/bin/tsserver ~/.npm-global/bin/
还有一个坑：某个已装工具自带 update 子命令，它不认自定义 prefix，升级时会把包装到别处去。这类工具升级一律绕开自带命令，回到 npm 正路：npm i -g --prefix ~/.npm-global <pkg>@latest。
复盘：--ignore-scripts 既是供应链卫生，也应该当默认参数用；只有项目 README 明确要求执行安装脚本时才例外。全局包一旦分散，排查成本远大于当初「随手装」省下的那几秒。
坑三：卸载 brew 版 node 之后，留下断链和孤儿目录
现象：确定 brew 的 node 不再被需要后动手卸载，结果 /opt/homebrew/bin 里若干命令报 no such file，/opt/homebrew/lib/node_modules 下还躺着一堆旧包目录——brew 卸载运行时并不清理这些。你以为卸载是终点，其实它只是把烂摊子从「隐藏」变成了「可见」。
排查：卸载前先确认依赖关系，返回空才敢动手——这一步绝不能省，否则级联卸载会顺带走掉别的包还在用的库：
$ brew uses --installed node node@24
# 空输出，说明没有其他包依赖它们
$ brew uninstall pnpm node@24 node
卸载过程会级联清理依赖库，输出里出现旧版本残留提示属正常。之后用这条命令审计全量断链：
find /opt/homebrew/bin -maxdepth 1 -type l ! -exec test -e {} \; -print
解法：断链本身按审计结果逐个清理。但有一条比清理更重要：我扫出来的断链里，有一部分在我这次卸载之前就已经存在了——上游包早年被删，软链一直挂着。核实了归因再动手，剩下的不确定项只报备、不擅删。
复盘：「谁弄坏的」这个问题必须回答，否则清理动作会变成新的事故源。先备份、再操作、后审计，每一步都留得下证据。
坑四：二进制换了位置，写死旧路径的地方会分批炸
现象：整合告一段落后没几天，定时任务发来一条失败通知。报错原因：某个任务里写死了 ~/.local/bin/uv，而 uv 在这次整合里已经归口到 brew 版 /opt/homebrew/bin/uv，旧路径没了。node 归口后同理——任何引用旧绝对路径的下游，都会在你以为「已经改完了」之后陆续冒出来。
排查：如果只修这条报错的任务，我就输了——第一个报错永远只是冰山一角。必须对旧绝对路径做全量扫描：
grep -rl "/.local/bin/uv" ~/scripts ~/cron定义目录 ~/知识库目录
扫描结果里最隐蔽的一类是：定时任务的 prompt 正文里也嵌着解释器绝对路径，这种藏在任务定义文件（如 jobs.json）里，不在任何脚本里，单跑脚本测试根本发现不了。而且这类文件不要直接编辑，要走定时任务管理工具提供的编辑命令替换整段 prompt，保持任务元数据一致。
解法：改路径时优先用探测，而不是换成另一个写死值——否则下次搬家原样复发：
UV_BIN="$(command -v uv || true)"
[ -z "$UV_BIN" ] && for cand in /opt/homebrew/bin/uv ~/.local/bin/uv; do
[ -x "$cand" ] && UV_BIN="$cand" && break
done
每条改动都要实跑验证：脚本直接 bash <script> 跑一遍，任务用管理工具手动触发一次、确认状态成功，才算修完。
复盘：「二进制换位置」是一种破坏性变更，影响面 = 所有写死旧路径的地方，而不是「报错了的那几处」。修第一个报错只花一分钟，漏掉第九个报错会在三周后的半夜把你叫醒。
盘点守则：先呈报表格，再动手删
四个坑讲完，再回头说一条贯穿全程的守则：先盘点后动手。我把每条运行时的来源、版本、谁在用、占用体积列成一张表，用 du -sh 给各个运行时目录量了体积，给卸载项标上收益。「谁在用」这一列才决定取舍——只被某个早停用的项目引用的，才能进删除候选；说不清来源的，宁可留下报备。表格摆出来后由我自己勾选确认，未选中的项一律列为「遗留」，不擅动。所有删除类操作全走可恢复路径：改配置文件前先 cp 一份带日期后缀的备份，出问题能一键回滚。
这套守则在每个坑里都被反复用到：PATH 统一前要先看全貌，卸 brew 前要先查依赖，清断链前要先核实归因，改路径后要先全量扫描再逐条实跑。盘点不是形式主义，它把「凭感觉删」变成「有据可查地删」，回滚时才知道退到哪里。
收尾：验证清单与遗留项
整合完成的判定标准很简单：zsh -lc 与 zsh -ic 双环境的 which node 一致；全部迁移过的 CLI 用 command -v 检查都指向新 prefix，且各自 --version 实测通过。
顺手盘点的另外两项，结论是「不动」：Java 用 /usr/libexec/java_home -V 列出多 JDK（8/11/17）按项目共存是常态，不该强行归口；Python 侧 pipx list 里有 invalid interpreter，是 brew python 升版后遗留的断链，用 pipx reinstall 修即可，与本次 node 整合无关——又一次先核实再归因。
真正留下的遗留项只有一个：/usr/local/bin 里官方 pkg 装的 node 20 属 root，删除要走系统授权弹窗。由于新 PATH 排在前面，它已经不再被任何环境命中，我选择列为遗留报备，没有擅动。遗留不是失败，把「不确定的东西」明确地圈出来、写进报告，本身就是整合的一部分——最怕的是你以为它没了，其实它只是暂时没被 PATH 命中，哪天 PATH 顺序一变它就复活。
最后我把整合结论——node 归口版本、全局包前缀、遗留项清单——写进了一条长期记忆，下次会话不用重复盘点。机器是自己的，环境文档却只存在于自己的脑子里，这正是分裂的起点。折腾一圈最大的体会是：多运行时共存本身不可怕，可怕的是两套 PATH 各说各话。先归因，再归口，最后清查下游，顺序别乱。
评论