OpenSpec 安装后提示 “openspec: command not found“ 怎么排查？-平芜编程栈

OpenSpec 安装后提示 "openspec: command not found" 怎么排查？

【免费下载链接】OpenSpecSpec-driven development (SDD) for AI coding assistants.项目地址: https://gitcode.com/GitHub_Trending/op/OpenSpec

在终端输入openspec --version或openspec init时，shell 报openspec: command not found。按 Troubleshooting 文档的说法，这个报错只有两类原因：CLI 没有安装，或者装了但 shell 找不到它（全局 bin 目录不在PATH里）。本文按文档给出的顺序走完这两个分支：先装好并验证，再修 PATH，最后处理版本管理器导致的"装到了另一个 Node 版本下"的情况。适用前提是 Node.js 20.19.0 或更高，macOS、Linux 和 Windows 都覆盖。

先确认 Node.js 版本

OpenSpec 运行在 Node 20.19.0+ 上（见 Installation 的 Prerequisites 一节）。先检查当前版本：

node --version

如果 Node 缺失或低于 20.19.0，先解决 Node 本身的问题再继续——文档明确要求这种情况下不要靠安装 OpenSpec 绕过。另外注意一点：即使你用 bun 来安装 OpenSpec，OpenSpec 依然运行在 Node 上，所以无论用什么包管理器安装，PATH上都必须有 Node 20.19.0+。

第二步：全局安装并立即验证

全局安装会把包写到项目之外的系统全局目录，这是它后来"找不到命令"的根源之一。文档给出的主路径是 npm：

npm install -g @fission-ai/openspec@latest openspec --version

装完立刻跑openspec --version，这是 Installation 文档指定的验证方式。如果打印出版本号，问题就结束了；如果继续报command not found，进入下一步。

其他包管理器的等价命令（来自 Installation 的 Package Managers 一节，按你系统里已有的选一个）：

pnpm add -g @fission-ai/openspec@latest yarn global add @fission-ai/openspec@latest bun add -g @fission-ai/openspec@latest

两个文档写明的限制：

yarn global只在 Yarn 1.x 可用；Yarn 2 及以后（Berry）移除了global命令，文档建议这种情况改用 npm、pnpm 或 bun 安装——全局 CLI 不需要和项目的包管理器一致。
如果安装过程要求 sudo 或管理员权限，或报权限错误，Installation 的 AI 协助安装流程要求停下来先确认，不要带权限问题继续往下走。
如果你用 Nix 或 deno，Installation 有对应章节；本文主路径不展开。

第三步：安装成功但仍报 not found，检查全局 bin 目录是否在 PATH 上

这是 Troubleshooting 给出的核心判断：安装成功但 shell 找不到，通常是 npm 全局 bin 目录不在PATH里。用下面这条命令看全局包装在哪：

npm prefix -g

然后按平台确认二进制实际位置：

macOS 和 Linux：可执行文件在该目录的bin/子目录里；
Windows：可执行文件直接位于该目录中。

确认上述路径在PATH上即可。文档特别提醒：npm bin -g这个旧命令在 npm 9 中已移除，不要再用它定位。

修改PATH由你自己完成：按你的 shell（.bashrc、.zshrc、.profile、fish、PowerShell profile 等）把目录加进去。这一点在 Installation 的 AI 协助安装流程里是明确的设计边界——那个安装 prompt 会"停下来"，把PATH改动告诉你而不是替你编辑 shell 启动文件。如果你就是走的 AI 协助安装，停在"告诉你怎么改 PATH"这一步是预期行为，不是流程卡住。

版本管理器用户的特殊情况

如果你用 Node 版本管理器，Installation 的 PATH 一节给出了针对性说明，不要盲目把路径写死进PATH：

nvm / fnm：全局安装的 CLI 绑定在安装当时激活的那个 Node 版本下。切到别的 Node 版本后找不到命令，是因为你换了 Node 版本，CLI 还留在旧版本的全局目录里。
asdf / volta：升级或切换 Node 后，shim 可能需要重新生成。

文档的建议是先弄清"CLI 装到了哪个 Node 版本下"，再决定用哪个 Node 版本运行或重装，而不是绕着版本管理器改 PATH。

命令能找到了，但版本号不对：PATH 上有一份旧副本

Installation 还覆盖了一种相关现象：openspec --version打印出的版本比刚才安装时报告的版本旧。这说明PATH上靠前位置的旧安装（shim 或早先的全局副本）抢答了，新装的那份根本没被执行到。

判断办法：

记录两个版本号：安装命令报告的版本，和openspec --version实际打印的版本。
找出实际被加载的是哪一份。CLI Reference 说明：openspec update的升级提示会打印当前运行 CLI 的加载目录（文档示例中的Running from: /usr/local/lib/node_modules/@fission-ai/openspec一行），"升级后仍被旧 shim 占据 PATH"时就要看这一行；并且当 PATH 靠前位置的另一份安装仍在应答时，openspec update会直接告诉你，而不是假称升级成功。

处理方式就是修PATH顺序或删除旧副本，让新版本目录生效；确认方式是openspec --version打印出与新装版本一致的版本号。