wangjs-jacky CLI 工具链故障排查助手，擅长定位 npm/node 全局包的安装、二进制执行、平台依赖等问题。 用系统化诊断流程快速定位 CLI 工具故障根因，给出最短修复路径并完成验证。
触发词：
- CLI 工具安装后运行报错
- spawnSync 错误 / Unknown system error
- command not found 但已安装
- npm 全局包二进制损坏
- optional 依赖缺失导致运行失败
- postinstall 脚本失败但安装显示成功
- binary / bin 文件为空或损坏
示例：
- "opencode 运行报 spawnSync error -88"
- "安装了 xxx 但运行报 command not found"
- "npm install -g xxx 成功但二进制文件损坏"
CLI 工具故障排查指南
本 skill 帮助快速诊断和解决命令行工具安装、运行中的常见问题。 覆盖 npm 全局包、二进制文件、optional 依赖、postinstall 脚本等场景。
快速诊断流程
CLI 工具运行报错
↓
1. 定位错误类型（spawnSync / ENOENT / EACCES / 其他）
↓
2. 检查二进制文件完整性（大小、架构、签名）
↓
3. 检查 optional 依赖是否完整安装
↓
4. 检查 postinstall 脚本执行情况
↓
5. 应用修复 → 验证
一、错误类型分类
1.1 错误类型速查
| 错误关键词 | 大概率原因 | 诊断路径 |
|---|---|---|
spawnSync ... Unknown system error -88 |
二进制文件损坏或为空 | → 二进制完整性检查 |
spawnSync ... ENOENT |
二进制文件不存在 | → 安装路径检查 |
EACCES permission denied |
权限不足 | → 权限修复 |
command not found |
PATH 未包含 / 未安装 | → PATH 和安装检查 |
invalid or unsupported format |
架构不匹配 | → 架构检查 |
SIGKILL / Killed |
内存不足或安全策略 | → 系统资源检查 |
| 安装成功但功能异常 | postinstall 静默失败 | → 依赖完整性检查 |
1.2 诊断步骤模板
# Step 1: 确认工具是否在 PATH 中
which <tool-name>
# Step 2: 检查二进制文件信息
file $(which <tool-name>)
ls -la $(which <tool-name>)
# Step 3: 检查实际二进制（非 wrapper 脚本）
file <npm-global>/lib/node_modules/<package>/bin/.<binary>
ls -la <npm-global>/lib/node_modules/<package>/bin/
二、二进制完整性检查
2.1 检查二进制文件状态
# 找到实际二进制路径（通常在 node_modules 下）
BINARY_PATH=$(npm root -g)/<package>/bin/.<binary>
# 检查文件类型和架构
file "$BINARY_PATH"
# 检查文件大小（正常应为 MB 级别，空文件为 0 bytes）
ls -la "$BINARY_PATH"
# macOS: 检查扩展属性（quarantine 标记会阻止执行）
xattr "$BINARY_PATH"
# macOS: 检查代码签名（Go 二进制可能无签名，但不应报格式错误）
codesign -vvv "$BINARY_PATH"
2.2 常见异常和修复
| 异常现象 | 说明 | 修复方案 |
|---|---|---|
| 文件大小为 0 或异常小（如 33MB 应为 118MB） | postinstall 未正确写入 | 重装 + 手动补依赖 |
empty file 或 data |
损坏或为占位文件 | 删除后重装 |
quarantine 属性 com.apple.quarantine |
macOS 安全限制 | xattr -d com.apple.quarantine <path> |
Non-executable |
缺少执行权限 | chmod +x <path> |
三、optional 依赖缺失
最常见的静默故障源：npm 会静默跳过安装失败的 optional 依赖。
3.1 识别 optional 依赖缺失
# 查看包的 optionalDependencies
cat $(npm root -g)/<package>/package.json | grep -A20 '"optionalDependencies"'
# 检查对应平台包是否存在（以 opencode-ai 为例）
ls $(npm root -g) | grep <package-prefix>
# 期望：opencode-darwin-arm64
# 实际：可能缺失
3.2 根因：为什么会缺失？
| 场景 | 原因 |
|---|---|
| 网络波动 | npm 在 optional 依赖下载超时时静默跳过 |
| npm 版本差异 | 不同 npm 版本对 optional 依赖策略不同 |
| registry 不稳定 | 私有 registry 可能缺少特定平台包 |
| Node 版本过新 | 新版 Node/npm 可能有行为变更 |
3.3 修复方案
# 方案 A：手动安装缺失的平台包（推荐）
npm install -g <platform-package>
# 例如：npm install -g opencode-darwin-arm64
# 方案 B：重装主包（确保网络稳定）
npm uninstall -g <package>
npm install -g <package>
# 方案 C：强制安装所有 optional 依赖
npm install -g <package> --install-strategy=nested
# 修复后手动运行 postinstall（如果需要）
cd $(npm root -g)/<package> && node postinstall.mjs
四、postinstall 脚本静默失败
高危模式：安装显示成功，实际二进制文件损坏。
4.1 识别方法
# 1. 查看 postinstall 脚本内容
cat $(npm root -g)/<package>/postinstall.mjs
# 2. 检查是否有 process.exit(0) 吞错误
grep -n "process.exit(0)" $(npm root -g)/<package>/postinstall.mjs
# 3. 手动运行 postinstall 观察输出
cd $(npm root -g)/<package> && node postinstall.mjs
# 正常：无输出或成功信息
# 异常：报错但之前被 exit(0) 吞掉
4.2 典型故障模式
// 危险模式：吞掉所有错误
try {
main() // ← 如果依赖缺失会 throw
} catch (error) {
console.error(error.message)
process.exit(0) // ← npm 认为安装成功！
}
4.3 修复策略
- 先修复根因（补依赖、修复路径等）
- 手动运行 postinstall
- 验证二进制文件是否正确生成
五、架构不匹配
5.1 检查架构
# 当前系统架构
uname -m
# arm64 = Apple Silicon
# x86_64 = Intel Mac
# 二进制文件架构
file <binary-path>
# Mach-O 64-bit executable arm64 ← 应与系统匹配
# Mach-O 64-bit executable x86_64 ← 在 Apple Silicon 上需要 Rosetta
5.2 常见问题
| 系统架构 | 二进制架构 | 结果 |
|---|---|---|
| arm64 | arm64 | 正常 |
| arm64 | x86_64 | 需要 Rosetta，可能运行缓慢 |
| x86_64 | arm64 | 无法运行，需要重新安装对应架构版本 |
六、权限问题
6.1 检查和修复
# 检查全局 npm 目录权限
ls -la $(npm root -g)/<package>/bin/
# 修复执行权限
chmod +x $(npm root -g)/<package>/bin/*
# 如果使用 nvm，确保 npm 全局目录在用户空间
npm root -g
# 应该在 ~/.nvm/versions/node/... 下（用户空间）
# 不应该在 /usr/local/lib/node_modules/ 下（系统空间）
6.2 nvm 环境 vs 系统 Node
# nvm 环境（推荐）— 权限通常没问题
which node
# /Users/<user>/.nvm/versions/node/v24.9.0/bin/node
# 系统 Node — 可能有权限问题
which node
# /usr/local/bin/node → 需要 sudo，不推荐
七、实战案例库
案例 1：opencode-ai spawnSync error -88
症状：
spawnSync /path/.opencode Unknown system error -88
诊断过程：
# 1. 检查文件
file .opencode → Mach-O 64-bit executable arm64 # 架构正确
ls -la .opencode → 33MB # 异常小（应为 118MB）
# 2. 检查签名
codesign -vvv .opencode → invalid signature # 签名无效
# 3. 检查平台依赖
ls $(npm root -g) | grep opencode → 只有 opencode-ai # 缺少 opencode-darwin-arm64
# 4. 查看包配置
cat package.json → optionalDependencies 包含 opencode-darwin-arm64
# 5. 查看 postinstall
cat postinstall.mjs → process.exit(0) 吞错误
根因：opencode-darwin-arm64 optional 依赖未安装 + postinstall exit(0) 静默吞错
修复：
npm install -g opencode-darwin-arm64
cd $(npm root -g)/opencode-ai && node postinstall.mjs
预防建议：
- 安装后验证二进制文件大小
- 关注 npm 安装日志中的 optional dependency 警告
案例 2：全局包安装成功但 command not found
症状：
npm install -g xxx → added 1 package
xxx → command not found
诊断：
# 检查安装位置
npm root -g
# 检查 bin 链接
ls $(npm bin -g) | grep xxx
# 检查 PATH
echo $PATH | tr ':' '\n' | grep nvm
常见原因：
npm bin -g不在 PATH 中（nvm 未正确加载）- bin 链接未创建（package.json 缺少 bin 字段）
- 多个 Node 版本混用
八、通用排查清单
遇到 CLI 工具问题时，按顺序执行：
# 1. 基本信息
node --version
npm --version
uname -m
# 2. 工具位置
which <tool>
# 3. 二进制完整性
file $(readlink -f $(which <tool>)) # Linux
file $(npm root -g)/<pkg>/bin/.<binary> # 通用
# 4. 平台依赖
ls $(npm root -g) | grep <pkg-prefix>
# 5. 重装测试
npm uninstall -g <pkg>
npm install -g <pkg>
# 6. 验证
<tool> --version
九、预防建议
| 场景 | 建议 |
|---|---|
| 新安装全局包 | 安装后立即运行 <tool> --version 验证 |
| optional 依赖 | 检查 npm ls -g 输出，确认平台包已安装 |
| postinstall 脚本 | 关注 npm install 输出中的 postinstall 日志 |
| 版本升级 | 升级后重新验证二进制文件完整性 |
| CI 环境 | 使用 npm ci 替代 npm install 确保一致性 |