🚀 省流助手
PNPM_HOME已配置，终端也能运行claude，仍可能执行到 nvm 目录里由 npm 安装的另一份。第一步先查type -a pnpm claude。- 入口绑定 Node、同名安装遮挡，以及安装后原生程序未就绪，都可能让命令无法按预期运行。相似症状需要沿不同路径排查。
- 迁移时把 pnpm 本体、全局命令入口和 CLI 运行时分别验证；
--version成功只证明能启动，不代表登录与业务功能已经验收。 - 已有项目的 pnpm 版本继续由项目声明约束，整理全局环境不等于顺便升级所有项目。
ⓐ 同样装了 pnpm，问题可能出在不同位置
终端里能运行 pnpm，包列表也能找到某个 CLI，切换 Node 后却可能出现另一种结果。整理排查记录时，需要把 pnpm 本体、全局命令入口和 CLI 运行时分别看待。
之前的全局包与 nvm 篇讨论过命令位置与运行时，Corepack 篇介绍了 shim 与版本选择。这里进一步检查：配置落到已有开发环境后，究竟有没有按预期生效。
| 检查对象 | 记录中的问题类型 | 排查重点 |
|---|---|---|
| pnpm 入口 | Corepack shim 位于某个 Node 前缀中 | 切换 Node 后，入口是否仍可见 |
| 全局 CLI | npm 与 pnpm 同时安装了同名命令 | 当前 shell 到底命中了哪一份 |
| 程序启动 | 入口存在，但运行时要求或安装阶段未满足 | 检查版本要求、包结构与安装日志 |
以下按问题类型整理已有排查记录，路径及与结论无关的版本细节已简化。Node 16／18 仅用于说明兼容性检查结果，不作为新环境的版本建议。
ⓑ 先排除 shell 启动方式造成的观察偏差
一类容易误判的记录来自非交互检查：通过 SSH 执行命令时，PNPM_HOME 显示为空，但 .zshrc 已写入相关设置。
换成交互式 zsh 后，变量和命令入口才出现。对于 zsh，是否交互会影响 .zshrc 是否加载；"配置文件里有"和"这次执行加载了"不能画等号。zsh 启动文件说明
检查最好先放在平时实际使用的终端中：
bash
printf '%s\n' "${PNPM_HOME-}"
type -a node pnpm claude
node --version
pnpm --version
pnpm bin -g
npm prefix -g这组输出把变量、命令候选、版本和全局前缀放在一起。远程自动化需要显式加载怎样的环境，则另行约定；不要拿不加载交互配置的 SSH 命令，直接断言用户终端也没有配置。
ⓒ which claude 有结果，却不是预期的那份
同名安装遮挡的检查结果很直接。下面仅保留 Node 大版本与路径关系，<version> 代表对应的安装版本：
text
Node 22
pnpm ~/.local/share/pnpm/pnpm 可启动
claude ~/.nvm/versions/node/<version>/bin/claude 可启动
Node 18
pnpm ~/.local/share/pnpm/pnpm 可启动
claude 找不到pnpm 的全局包列表中虽然有 Claude，当前 shell 命中的却是 npm 安装的那一份。此时重新安装 pnpm 包，不一定改变终端实际执行的程序。
先查所有候选，再核对各自归属：
bash
type -a claude
npm list -g --depth=0
pnpm list -g --depth=0如果存在别名或函数，也会在排查范围内。确认命中的是文件后，再检查链接和文件类型。PATH 决定先发现哪个入口；包列表只能证明某个管理器记录了某份安装。nvm 全局包说明
处理这个案例时，先调整目标目录的 PATH、确认 pnpm 管理的 Claude 可用，再清理对应 Node 前缀下重复的 npm 安装。复验结果是：切换 Node 后，命令都指向了同一份预期安装。
ⓓ 全局 CLI 没丢，pnpm 本体却丢了
另一个案例里，全局 CLI 与 pnpm 本体的入口已经分开。简化后的检查结果是：
text
切换 Node 后
pnpm 找不到
全局 CLI 仍在固定用户目录中全局 CLI 已经移到固定目录，但管理它们的 pnpm 仍装在之前的 Node 前缀中。切换 Node 后，CLI 入口还在，pnpm 入口却不再可见。
这里要区分两种"独立"：
| 检查对象 | 要确认什么 |
|---|---|
| 命令入口 | 是否位于随 nvm 切换的前缀、是否被其他安装遮挡 |
| 程序运行 | 是 JavaScript、shell 启动脚本，还是原生可执行程序；需要哪个运行时 |
pnpm 12 的本体运行不依赖系统 Node，但经 npm 安装它仍有安装环境要求；不能把这句话推广到所有历史 pnpm 发行物。pnpm 安装说明、Homebrew formula
对于文件入口，可以先查看：
bash
command -v pnpm
file -L "$(command -v pnpm)"显示为 shell 脚本时，还要继续追踪它调用的目标。文件路径固定，并不能证明程序不再需要 Node；记录中就有 pnpm 路径不变、却在 Node 16 下报最低版本要求的情况。
ⓔ 安装完成，不代表原生程序已经就绪
原生程序未就绪的案例中，Claude 的版本检查出现：
text
Error: claude native binary not installed.排查没有直接归因于 Node，而是继续查看该版本的包结构和安装脚本。Claude Code 2.1.312 的包中有 postinstall: node install.cjs，平台包也已存在。脚本负责把平台可执行文件安装到命令实际使用的位置。
按该安装的构建策略处理后，日志中出现：
text
postinstall$ node install.cjs
postinstall: Done
2.1.312 (Claude Code)最终目标文件也被识别为 Mach-O 可执行程序。这里支持的判断是：这一例需要完成安装阶段的处理，不能仅凭"原生程序缺失"推断 Node ABI 不兼容。 这是特定版本的记录，不保证未来 Claude 的发行结构相同。
遇到类似问题，先查看安装输出和审批状态：
bash
pnpm help approve-builds
pnpm approve-builds -g批准构建会让所选包执行代码，应先核对包来源、版本和脚本用途。不同 pnpm 版本的审批与重建行为存在差异，以实际帮助和输出为准；不要把"手工跑 install.cjs"当成通用捷径。pnpm 构建批准说明
其他工具出现 pty.node 等原生依赖缺失时，也需要单独核查。一个 CLI 恢复启动，不能证明其他包的原生依赖都已就绪。
ⓕ 迁移后的验证，要保留失败项
历史检查里，既有切换 Node 后路径与版本命令均通过的结果，也有入口稳定、业务 CLI 在旧 Node 下仍失败的结果。失败项包括 JSON import 语法和正则标志兼容问题，反映了依赖对运行时的要求。
| 检查结果 | 能证明什么 | 还不能证明什么 |
|---|---|---|
| 切换后入口保持一致 | 命令的可发现性符合预期 | 程序与所选 Node 一定兼容 |
| 版本命令成功 | 程序至少能启动 | 登录、网络与业务功能均正常 |
| 旧 Node 下仍报语法错误 | 当前程序或依赖存在兼容性限制 | 重新固定 PATH 就能解决 |
把命令放进固定目录，不会消除运行时要求。
因此，验收表必须分别记录入口、版本输出和退出状态。下面的示例只切换子 shell 中的已安装 Node，不改当前终端和默认版本：
bash
(
for node_version in 22 24; do
nvm use "$node_version" || exit 1
node --version
for tool in pnpm claude; do
if command -v "$tool"; then
if "$tool" --version; then
result=0
else
result=$?
fi
printf '%s exit=%s\n' "$tool" "$result"
else
printf '%s missing (exit=127)\n' "$tool"
fi
done
done
)版本号应换成实际已安装的版本，测试前确认这些命令都是可信的预期程序。--version 不是登录和业务验收；真正需要访问账号或执行工作的 CLI，还要单独测试对应功能。
ⓖ 整理全局环境，不顺便升级所有项目
全局 pnpm 与旧项目要求的版本可能不同。全局入口稳定与项目版本一致性，是两个独立目标。
进入项目后，检查 package.json 的 packageManager、团队约定和实际 pnpm --version。Corepack 与具备版本管理能力的 pnpm，其选择行为都要结合具体版本和配置确认，不能只看项目外的版本号就下结论。
清理旧环境也按实际归属进行：先记录安装来源和版本，备份配置，验证新入口，再用原管理器移除已确认不用的旧包。旧全局目录、store 与项目 node_modules 分别处理，不根据目录名猜测用途后整批删除。
最后重新打开终端复验。旧终端和 tmux 中仍在运行的 shell 不会因为磁盘上的配置改了，就自动使用新 PATH。排查时可以在实际使用环境中回答三个问题：命令命中了哪里，启动了什么程序，实际验证到了哪一步。