posts/npm-broken-cli-fix.md
npm 全局包救活记：opencode 崩溃 3 小时复盘
npm 全局包救活记：opencode 崩溃 3 小时复盘
那天晚上 opencode 突然彻底罢工：终端里输入 opencode 提示"无法识别"，VSCode 扩展也拉起不了会话，直接运行可执行文件则报"不是有效的应用程序"。
#一、症状清单
| 症状 | 直接原因 |
|---|---|
opencode 命令找不到 | npm 全局目录里启动器（opencode.cmd）缺失 |
| exe 被系统拒绝执行 | 二进制文件损坏，Windows 加载器直接拒绝 |
| VSCode 扩展起不来 | 扩展通过终端执行 opencode --port xxx，依赖上面的命令 |
#二、排查思路（三级递进）
第一级：看全貌。 先确认"该装的装了没"——npm ls -g 显示包里确实存在，但启动器文件没了，还留下一个 .opencode.cmd-HL4jbKan 的残留临时文件——这是安装中断的经典痕迹。
第二级：验二进制。 发现 bin\opencode.exe 只有 479 字节，内容是一段报错脚本：Error: opencode-ai's postinstall script was not run.。原来 npm 主包只是包装器，真正的二进制在平台包（opencode-windows-x64，约 180MB）里，由 postinstall 脚本拷贝过来。对照官方 tarball 的哈希，确认已安装的三份 exe 全部损坏——最终结论：安装中断，不是配置、不是网络、不是镜像、不是安全策略。
第三级：换装。 从官方源重新拉取平台包，提取完好二进制替换三处损坏文件，重建启动器，一条命令验证：
powershellopencode --version # → 1.18.25，恢复正常
#三、自愈命令速查
powershell# 自愈①：重建二进制（安装中断后最常用）
cd "C:\Users\22971\AppData\Roaming\npm\node_modules\opencode-ai"
node postinstall.mjs
# 自愈②：彻底重装（重建二进制 + 全部启动器）
npm install -g opencode-ai@1.18.25 --force
# 验证
opencode --version
opencode models # 能看到 opencode-go/deepseek-v4-flash 即一切正常
#四、防复发清单
- 更新后 10 秒验证：
opencode --version能打印版本号 = 二进制完好。 - 见到残留临时文件就是警报：
.opencode.cmd-XXXXX这类文件 = 上次安装中断的铁证。 - 安装期间别中断：平台包 150–180MB，更新时保持网络稳定，先把正在运行的 opencode 会话退出。
- 日志是最后的证人：
~/.local/share/opencode/log/opencode.log记录了一切，遇到 API 类问题先看它。
这次 3 小时的折腾，浓缩成上面四条，希望你的下一次"崩溃"只需要 10 分钟。