安装失败排查：Node 版本 / pnpm / npm 缓存

你会遇到什么

skills CLI 或安装过程报 Node 版本不支持、pnpm 相关错误、或 npx 下载卡住/失败。装个技能包，前置环境先卡三道。

本文路径：快速修复（30 秒一段命令）→ 一步步排查（可跳读）→ 原理与变体（症状/原因/证据）。赶时间直接跳到「快速修复」。

为什么会这样

npx 是一条“下载即执行”的链：先从 registry 拉包（网络层）→ 解包后核对 engines 声明的 Node 版本（运行时层）→ 再执行 CLI（执行层）。

三层任何一层断了，用户看到的都是“安装失败”，但报错位置完全不同：Node 版本报错来自 engines 检查，说明网络是通的、卡在运行时；下载卡住/超时发生在拉取层，通常是官方 registry 直连不稳；pnpm/缓存报错发生在解包与写缓存阶段，说明包已下载、但本地状态坏了。

这就是排查顺序固定的原因：先 node --version 排除运行时 → 再用环境变量方式换 registry（只对当前命令生效，不污染全局配置）→ 最后才清缓存。顺序反了会反复撞同一堵墙：比如网络不通时清十次缓存也没用。

一步步来

1. 确认 Node 版本 — 必做

node --version

<18 用 nvm 升级到 18+。

2. registry 换国内镜像 — 必做

npm_config_registry=https://registry.npmmirror.com npx -y skills ...

环境变量方式只对当前命令生效，不污染全局配置。

3. 清缓存重试 — 必做

npm cache clean --force

或换隔离 HOME 重试（本市场实测用隔离 HOME /tmp/agsk-home）。

怎么确认修好了

npx 下载与 CLI 执行正常（实测形态）：

npm_config_registry=https://registry.npmmirror.com npx -y skills ...
→ CLI 正常下载并执行，安装流程走到 clone/复制阶段

node --version 输出 ≥18（实测 v22.22.1 可用）。

其它环境的表现

症状

skills CLI 或安装过程报 Node 版本不支持、pnpm 相关错误、或 npx 下载卡住/失败。

原因

CLI 需要 Node >= 18（本环境 v22.22.1 实测可用）；npm 官方 registry 国内直连不稳；缓存损坏/权限问题会中断 npx 下载。

解法

1. 确认版本：node --version（<18 用 nvm 升级）。
2. registry 换国内镜像：npm_config_registry=https://registry.npmmirror.com npx -y skills ...（本环境实测 npmmirror PONG 0.32s）。
3. 清缓存重试：npm cache clean --force 或换隔离 HOME。