npm 装完 Codex 找不到命令的 7 个修复

这篇文章整理了 7 种修复 npm 全局安装后找不到 codex 命令的方法。

如果你已经装过 npm 版 Codex，却还是报 “codex: command not found”，通常不是安装失败，而是 PATH、shell 配置或全局目录没对上。下面这 7 种办法能帮你快速定位问题，文中还会用到一个真实例子：把全局目录加入 PATH 后，再用 which codex 和 codex --version 验证。

项目	主要检查点	适用场景
PATH	全局 bin 是否已加入	最常见的命令找不到
shell 配置文件	.zshrc / .bashrc 是否写对	切换 shell 后失效
真实路径	是否用了占位符路径	照抄教程后仍报错
npm prefix	全局前缀与 bin 位置	安装目录和预期不一致
终端会话	是否重新打开窗口	source 后仍不生效
全局安装状态	包是否真装到全局	安装被中断或装成本地
最终验收	which 与 version 是否通过	确认修复是否完成

1. 把 npm 全局 bin 目录加进 PATH

这是最常见的修复。npm 把全局可执行文件放在一个 bin 目录里，如果这个目录没进 PATH，系统就算装好了也找不到 codex。你需要把实际的全局路径写进 shell 配置文件，而不是照抄别人的路径。

在 macOS 和 zsh 里，常见做法是把命令追加到 ~/.zshrc，然后重新加载配置。关键点是先查出你的真实 npm 全局目录，再把它拼到 PATH 前面。

• npm root -g 查看全局包目录
• npm bin -g 查看全局可执行文件目录
• echo 'export PATH="/your/path/bin:$PATH"' >> ~/.zshrc
• source ~/.zshrc 立即生效

2. 确认你改的是当前 shell 的配置文件

很多人把 PATH 写进了 .bashrc，但实际打开的是 zsh；或者在登录 shell 里改了 .zprofile，却在交互 shell 里测试。结果就是配置看起来没错，命令还是找不到。先确认你当前用的是哪种 shell，再改对应文件。

macOS 默认常见是 zsh，Linux 上可能是 bash 或 zsh。只要配置文件没对上，which codex 就不会返回预期路径。这个问题在新装系统、切换终端应用、远程登录时尤其常见。

• zsh 常改 ~/.zshrc 或 ~/.zprofile
• bash 常改 ~/.bashrc 或 ~/.bash_profile
• echo $SHELL 查看默认 shell
• ps -p $$ 查看当前 shell 进程

3. 用真实路径替换示例路径

文章里最容易踩坑的一点，是把示例里的 /Users/you/.npm-global 原样复制了。这个路径只是占位符，不能直接用。你的机器上可能是 /opt/homebrew、/usr/local，也可能是某个自定义目录。

正确做法是先打印真实值，再写入配置。只要路径错一个字符，终端就不会找到 codex。这也是为什么很多人“明明按教程做了”，结果还是报错。

npm config get prefix npm bin -g which node which npm

4. 检查 npm 全局 prefix 是否指向你想要的位置

npm 的全局安装位置由 prefix 决定。若 prefix 指向一个你没有加进 PATH 的目录，或者目录本身权限不对，安装后就会出现“装上了但找不到”的情况。把 prefix 查出来，能快速判断问题是在安装阶段还是环境变量阶段。

如果你曾经改过 npm 配置，或者用过 nvm、fnm、Volta 之类的 Node 管理工具，prefix 可能会和你预期不一样。此时不要急着重装，先把 prefix 和 bin 目录核对清楚。

• npm config get prefix 查看全局前缀
• npm config list -l | grep prefix 进一步确认
• 确保 prefix/bin 在 PATH 中

5. 重新打开终端，别只停留在 source 之后

有些终端应用在当前窗口里读不到最新环境变量，尤其是在图形界面启动的终端、iTerm2、Terminal.app、VS Code 集成终端之间切换时。你执行了 source ~/.zshrc，但当前会话仍然没刷新完整环境，这时重开一个新窗口最直接。

如果重开终端后 which codex 仍然为空，再去看配置文件是否被其他脚本覆盖。很多时候问题并不在 npm，而在终端启动链路。

• 关闭当前终端窗口后重新打开
• 在新窗口里运行 echo $PATH
• 再运行 which codex 和 codex --version

6. 检查 codex 是否真的安装到了全局

有时你以为自己做了全局安装，实际装成了本地依赖，或者安装过程被代理、权限、网络错误打断。先确认包本身存在，再去看命令是否暴露出来。这样能避免把时间浪费在 PATH 上，而真正的问题其实是安装没成功。

如果包没装好，先重装；如果包装好了但命令还是不见，再回到前面的 PATH 和 prefix 排查。把“安装成功”和“命令可用”分开验证，效率会高很多。

npm list -g --depth=0 npm install -g codex npm uninstall -g codex npm install -g codex

7. 用 which 和 version 做最终验收

修复之后不要只看“没报错”，要让终端明确告诉你命令已经可用。which codex 能返回可执行文件路径，codex --version 能确认程序真的能跑。两步一起做，能把“环境变量生效了”和“程序可执行了”同时验证掉。

如果 which codex 仍然没有输出，就说明 PATH 还没对上；如果能找到路径但版本命令失败，说明可能是安装文件损坏或权限有问题。这个收尾检查能帮你把问题锁定到最后一层。

• which codex 验证路径
• codex --version 验证可执行性
• echo $PATH 验证环境变量内容

哪种适合你

如果你刚装完就报错，先做第 1 条和第 3 条，通常最快见效。如果你是在 macOS 上用 zsh，第 2 条和第 5 条也很值得优先排查，因为 shell 配置和终端会话经常是根因。

如果你已经确认 PATH 没问题，再看第 4 条和第 6 条，重点查 npm prefix 和全局安装状态。最后用第 7 条收尾，确保 which codex 和 codex --version 都能正常返回。