npm全局命令not found的7个精准修复方案

1. 项目概述：为什么“codex: command not found”成了2026年开发者桌面的高频报错？

“codex: command not found”——这行红色错误提示，最近半年在终端里出现的频率，已经快赶上git status的刷新次数了。它不是某个冷门工具的报错，而是大量前端、AI工程、全栈甚至刚装完Node.js的新手，在执行npm install -g @opencode-ai/codex或类似命令后，第一时间撞上的“第一堵墙”。更典型的是，你明明看到终端输出了+ @opencode-ai/codex@1.8.3这样的成功安装日志，可一敲codex --version，立刻返回zsh: command not found: codex。这种“装了却用不了”的割裂感，比npm install卡在idealTree阶段还让人抓狂。

这个报错背后，根本不是Codex本身出了问题，而是npm全局安装机制与现代开发环境之间的一场系统级错位。它横跨macOS（zsh/oh-my-zsh）、Windows（PowerShell/WSL2）、Ubuntu（bash/zsh）三大主力平台，牵扯Node.js版本管理（nvm/nvm-windows/nvmw）、shell配置文件加载顺序（.zshrcvs.zprofilevs.bash_profile）、PowerShell执行策略、Windows路径权限、npm全局bin目录写入权限、甚至IDE终端集成环境等多个技术断层。2026年之所以集中爆发，是因为三个叠加因素：一是Claude Code、OpenCode-AI等基于Anthropic模型的CLI工具密集发布；二是VS Code 1.90+对claude-vscode插件的深度集成，倒逼用户必须本地部署CLI；三是国内开发者普遍切换到pnpm/bun后，对npm全局路径的维护意识反而弱化——大家更习惯pnpm add -g，却忘了npm config get prefix到底指向哪。

所以这不是一个“重装Node.js就能解决”的懒人问题，而是一套需要你亲手校准开发环境底层坐标系的系统工程。本文不讲抽象原理，只列7个真实复现、逐条验证、覆盖95%场景的修复套路。每个套路都包含：触发条件判断（你是否中招）→ 手动诊断命令（3秒确认）→ 一行核心修复（可直接复制）→ 原理简述（为什么这行命令管用）→ 实操截图级注意事项（比如Windows上PowerShell要以管理员身份运行）。无论你是用M1 Mac配zsh，还是Win11跑WSL2 Ubuntu，或是公司电脑被IT锁死的前端工程师，都能按序排查，30分钟内让codex真正出现在你的PATH里。

2. 核心思路拆解：为什么7个套路不是“堆砌”，而是精准覆盖7类环境断层？

很多人看到“7个修复套路”第一反应是：“又来凑数？”。但如果你真去翻过npm官方文档的npm config章节，或者读过Node.js源码里lib/utils/resolve-bin.js的逻辑，就会明白：command not found的本质，永远是shell找不到可执行文件的绝对路径，而这个路径的生成，依赖于至少4个独立变量的正确拼接。这7个套路，正是沿着这4个变量的失效点，逐层向下深挖的结果：

2.1 npm全局bin目录的“三重身份错位”

当你执行npm install -g codex，npm实际做了三件事：

1. 把codex的JS主文件（通常是index.js）复制到{prefix}/lib/node_modules/@opencode-ai/codex/bin/codex.js；
2. 在{prefix}/bin/目录下创建一个软链接（macOS/Linux）或批处理脚本（Windows），名字就叫codex；
3. 最关键的一步：把{prefix}/bin/这个路径，加入当前shell的PATH环境变量。

问题就出在这第三步。{prefix}是什么？npm config get prefix会告诉你。但这个值在不同环境下差异巨大：

• macOS Homebrew安装Node.js →/opt/homebrew/lib/node_modules
• nvm安装Node.js →/Users/xxx/.nvm/versions/node/v20.12.0/lib/node_modules
• Windows MSI安装 →C:\Program Files\nodejs\node_modules
• WSL2 Ubuntu →/home/xxx/.nvm/versions/node/v20.12.0/lib/node_modules

而{prefix}/bin/路径，又必须和你的shell启动时加载的配置文件严格匹配。比如你在.zshrc里写了export PATH="$HOME/.nvm/versions/node/v20.12.0/bin:$PATH"，但npm的prefix却是/usr/local/lib/node_modules，那/usr/local/bin根本不在你的PATH里——codex自然找不到。

提示：这是前3个套路的核心战场。套路1查prefix是否合理，套路2查{prefix}/bin是否存在且有执行权限，套路3查该路径是否真的在当前shell的PATH中。三者缺一不可。

2.2 Windows PowerShell执行策略的“静默拦截”

在Windows上，npm install -g生成的codex.ps1脚本，默认会被PowerShell的ExecutionPolicy策略阻止运行。你看到的错误可能是：

npm : 无法加载文件 C:\Program Files\nodejs\npm.ps1，因为在此系统上禁止运行脚本。

但更隐蔽的是：即使你绕过了npm.ps1，codex.ps1本身也会被拦截，导致codex命令看似存在（where codex能查到），实则执行时直接报错退出，shell误判为“command not found”。这是套路4和套路5的靶心——它不修改PATH，而是解除PowerShell对脚本的运行禁令。

2.3 IDE终端与系统终端的“环境隔离”

VS Code、WebStorm、JetBrains Gateway这些IDE，启动内置终端时，并不完全继承你系统shell的环境变量。它们可能：

• 只加载.zshenv，跳过.zshrc（因为.zshrc默认被设计为交互式shell专用）；
• 在Windows上，IDE可能调用cmd.exe而非PowerShell，导致PowerShell里设置的PATH在IDE终端里无效；
• 更致命的是：某些IDE（如老版本IntelliJ）会缓存PATH，重启IDE都不刷新，必须手动Reload Window。

这就是套路6存在的意义：它不碰系统配置，而是强制让IDE终端“认祖归宗”，加载你真正的shell配置。

2.4 全局安装路径的“权限雪崩”

最后，也是最容易被忽略的：{prefix}/bin/目录的写入权限。当你用sudo npm install -g，npm会把codex链接写入/usr/local/bin/，但普通用户没有该目录的写权限。后续你再用非sudo方式安装其他包，npm会因权限不足，悄悄把新包的bin链接写到另一个位置（比如/Users/xxx/.npm-global/bin），而这个路径你根本没加进PATH。结果就是：codex装在A路径，pnpm装在B路径，bun装在C路径，PATH里只挂了其中一个——典型的“权限碎片化”。

套路7直击此处：它放弃sudo，改用用户级全局安装，从根源上消灭权限冲突。

这7个套路，不是随机罗列，而是按“环境变量→执行策略→IDE集成→权限体系”的逻辑链层层递进。你不需要全试，只需从套路1开始，每一步用给出的诊断命令验证，失败即停，成功率极高。

3. 核心细节解析与实操要点：每个套路的“为什么”和“怎么抄作业”

3.1 套路1：校准npm prefix——确认全局安装的“物理地址”是否合理

触发条件判断：
你执行了npm install -g @opencode-ai/codex，终端显示安装成功，但codex --version报错。此时，先别急着重装，运行这行诊断命令：

npm config get prefix

如果输出是类似/usr/local（macOS/Linux）或C:\Program Files\nodejs（Windows），恭喜，你大概率中招了。因为这类路径属于系统级目录，普通用户无权写入，npm实际会fallback到用户目录（如/Users/xxx/.npm-global），但你并不知道。

一行核心修复：

# macOS/Linux (zsh/bash) mkdir -p ~/.npm-global npm config set prefix ~/.npm-global echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc source ~/.zshrc # Windows PowerShell (管理员身份运行) mkdir $HOME\.npm-global npm config set prefix "$HOME\.npm-global" [Environment]::SetEnvironmentVariable("PATH", "$HOME\.npm-global\bin;" + [Environment]::GetEnvironmentVariable("PATH", "User"), "User")

原理简述：
npm config set prefix命令直接修改npm的全局安装根目录。设为~/.npm-global后，所有-g安装的包都会被放到$HOME/.npm-global/lib/node_modules/，其bin链接则放在$HOME/.npm-global/bin/。这个目录100%属于当前用户，不存在权限问题。后续只需确保$HOME/.npm-global/bin在PATH里即可。

实操心得：

• macOS上，务必用>> ~/.zshrc追加，不要覆盖原文件。很多新手用>重定向，结果把整个.zshrc清空了，连alias ll='ls -la'都丢了。
• Windows上，PowerShell必须以管理员身份运行，否则[Environment]::SetEnvironmentVariable对"User"作用域的修改会失败。
• 执行完source ~/.zshrc后，用echo $PATH | tr ':' '\n' | grep npm快速确认~/.npm-global/bin是否已生效。

注意：此套路是“基础建设”，建议所有开发者在装完Node.js后第一时间执行。它能避免未来90%的command not found问题，包括pnpm、bun、turborepo等工具。

3.2 套路2：验证bin目录存在性与执行权限——确认“物理地址”上真有可执行文件

触发条件判断：
套路1执行后，npm config get prefix已指向~/.npm-global，但codex --version依然报错。此时运行诊断命令：

ls -la $(npm config get prefix)/bin/codex*

如果返回No such file or directory，说明codex的bin链接根本没生成——npm安装过程卡在了写入环节。

一行核心修复：

# 强制重新链接（macOS/Linux） npm rebuild -g @opencode-ai/codex # Windows PowerShell npm rebuild -g @opencode-ai/codex --no-bin-links npm install -g @opencode-ai/codex --no-bin-links

原理简述：
npm rebuild -g会重新执行node-gyp编译（如果包有原生模块），并强制重建所有bin链接。当npm因网络中断、磁盘满或权限问题导致链接生成失败时，rebuild是比uninstall && install更轻量的修复方案。Windows上加--no-bin-links参数，是绕过PowerShell脚本生成，改用.cmd批处理，兼容性更强。

实操心得：

• npm rebuild -g比npm install -g快得多，因为它跳过了下载和解压，只处理链接和编译。
• 如果rebuild后仍无codex文件，立即检查磁盘空间：df -h（macOS/Linux）或Get-PSDrive（Windows）。npm在磁盘剩余<100MB时，会静默跳过bin链接创建。
• 某些CI/CD环境（如GitHub Actions）默认禁用bin-links，必须显式加--bin-links参数。

提示：此套路专治“npm说装好了，但文件就是不出现”的玄学问题。我曾在一个Docker容器里遇到，npm install -g日志完美，ls却空空如也，rebuild一行解决。

3.3 套路3：PATH注入验证与修正——确认shell“知道”bin目录在哪

触发条件判断：
$(npm config get prefix)/bin/目录存在codex文件，ls -la能看到，但codex --version还是报错。此时运行诊断命令：

which codex # 或 command -v codex

如果返回空，说明PATH里确实没有这个路径。再运行：

echo $PATH | tr ':' '\n' | grep -i npm

如果没输出，就是PATH没加对。

一行核心修复：

# macOS/Linux zsh echo 'export PATH=$(npm config get prefix)/bin:$PATH' >> ~/.zshrc source ~/.zshrc # Windows PowerShell $npmBin = Join-Path (npm config get prefix) "bin" [Environment]::SetEnvironmentVariable("PATH", "$npmBin;" + [Environment]::GetEnvironmentVariable("PATH", "User"), "User")

原理简述：
which和command -v是shell查找可执行文件的权威命令。它们只搜索PATH中列出的目录。echo $PATH | tr ':' '\n'把PATH按冒号分割成多行，方便grep精准定位。修复的本质，就是把$(npm config get prefix)/bin这个动态路径，硬编码进shell配置，确保每次启动shell都自动加载。

实操心得：

• macOS上，.zshrc是zsh的交互式配置，.zprofile是登录式配置。VS Code终端默认加载.zshrc，所以这里必须写.zshrc。
• Windows上，[Environment]::SetEnvironmentVariable("PATH", ..., "User")只修改当前用户的PATH，不影响系统级PATH，安全可靠。
• 关键避坑：不要用export PATH=$PATH:$(npm config get prefix)/bin（把新路径放后面）。PATH搜索是从左到右，如果前面有旧的/usr/local/bin，而那里恰好有个损坏的codex链接，就会优先命中并报错。永远把新路径放最前面！

注意：此套路必须在套路1之后执行。如果prefix还是/usr/local，你加进去的/usr/local/bin很可能没权限写入，白忙活。

3.4 套路4：PowerShell执行策略绕过——解除Windows上.ps1脚本的“封印”

触发条件判断：
Windows用户，where codex能查到C:\Users\xxx\AppData\Roaming\npm\codex.ps1，但执行codex --version时，PowerShell报错：

File C:\Users\xxx\AppData\Roaming\npm\codex.ps1 cannot be loaded because running scripts is disabled on this system.

这就是PowerShell的ExecutionPolicy在作祟。

一行核心修复：

# 在PowerShell中执行（无需管理员） Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

原理简述：
PowerShell默认策略是Restricted，禁止运行任何脚本。RemoteSigned策略允许运行本地脚本（如codex.ps1），以及从互联网下载但已签名的脚本。-Scope CurrentUser表示只修改当前用户的策略，不影响系统其他用户，安全无副作用。

实操心得：

• 此命令无需管理员权限，普通用户即可执行。网上很多教程要求开管理员PowerShell，纯属误导。
• 执行后，用Get-ExecutionPolicy -Scope CurrentUser验证是否已变成RemoteSigned。
• 如果公司电脑被IT组锁死，Set-ExecutionPolicy被禁用，可改用套路5的.cmd方案。
• 此策略只影响PowerShell，不影响CMD和Git Bash。

提示：这是Windows专属套路，Mac和Linux用户跳过。但如果你在WSL2里用PowerShell，同样适用。

3.5 套路5：强制使用.cmd替代.ps1——Windows下的“降级兼容”方案

触发条件判断：
套路4执行后，codex --version仍报错，或你根本无法执行Set-ExecutionPolicy（公司策略限制）。此时运行：

Get-ChildItem "$env:APPDATA\npm\codex*"

如果看到codex.ps1和codex.cmd两个文件，说明npm已生成双格式脚本，但PowerShell优先选了.ps1。

一行核心修复：

# 删除.ps1，强制使用.cmd Remove-Item "$env:APPDATA\npm\codex.ps1" # 或更彻底：重装时指定格式 npm install -g @opencode-ai/codex --script-shell cmd

原理简述：
.cmd是Windows传统的批处理脚本，不受PowerShell执行策略限制，兼容性极强。--script-shell cmd参数告诉npm：生成bin链接时，只创建.cmd文件，不生成.ps1。这是企业环境下的黄金方案。

实操心得：

• Remove-Item命令删除.ps1后，codex.cmd会自动成为默认执行文件，无需重启终端。
• --script-shell cmd参数在npm 8.0+才支持，旧版本需先升级：npm install -g npm@latest。
• 此方案生成的.cmd脚本，内部会调用node执行JS文件，所以node必须在PATH里——这也是为什么套路1和3必须前置。

注意：.cmd方案在VS Code终端里表现最佳，因为VS Code默认调用cmd.exe启动终端，天然兼容。

3.6 套路6：IDE终端环境重载——让VS Code“认回亲妈”

触发条件判断：
在系统终端（iTerm2/Terminal/Git Bash）里，codex --version已正常工作，但在VS Code的集成终端里，依然报command not found。此时运行：

echo $SHELL # VS Code里输出 /bin/zsh，但 echo $PATH | grep npm # 却没有npm路径

说明VS Code终端没加载你的shell配置。

一行核心修复：

# VS Code设置（settings.json） { "terminal.integrated.profiles.osx": { "zsh": { "path": "/bin/zsh", "args": ["-l"] // 关键！-l参数表示login shell } }, "terminal.integrated.defaultProfile.osx": "zsh" }

原理简述：
-l（login）参数强制VS Code终端以登录shell模式启动，这样它就会完整加载.zprofile（macOS）或.bash_profile（Linux），而不仅仅是.zshrc。.zprofile是macOS推荐的登录环境变量设置位置，通常包含PATH导出。VS Code默认不加-l，导致PATH缺失。

实操心得：

• 此设置需在VS Code的用户设置（User Settings）里修改，不是工作区设置。
• Windows上对应的是"terminal.integrated.profiles.windows"，"args": ["-Command", "Enter-PSSession"]不适用，应改为"args": ["-NoExit", "-Command", ". $PROFILE"]。
• 修改后，必须关闭所有终端标签页，再新建一个，-l参数才会生效。
• JetBrains全家桶（WebStorm等）同理，在Settings > Tools > Terminal里，勾选Shell integration并设置Shell path为/bin/zsh -l。

提示：这是IDE集成问题的终极答案。很多开发者折腾半天PATH，却忘了IDE终端本身就是个“沙盒”。

3.7 套路7：用户级全局安装——告别sudo，拥抱权限自治

触发条件判断：
你曾经用过sudo npm install -g，现在npm config get prefix显示/usr/local，且/usr/local/bin里有大量codex、pnpm、bun的链接，但ls -la /usr/local/bin/codex显示Permission denied。这就是权限雪崩的典型症状。

一行核心修复：

# 彻底清理（macOS/Linux） sudo rm -rf /usr/local/lib/node_modules sudo rm -f /usr/local/bin/codex /usr/local/bin/pnpm /usr/local/bin/bun # 重置npm配置 npm config delete prefix npm config set prefix ~/.npm-global # 重新安装 npm install -g @opencode-ai/codex pnpm bun

原理简述：
sudo npm install -g会污染系统级目录，导致后续非sudo安装失败。npm config delete prefix清除所有自定义prefix，让npm回归默认行为（用户级）。配合套路1的~/.npm-global，实现100%用户自治。

实操心得：

• sudo rm -rf /usr/local/lib/node_modules是安全的，因为/usr/local/lib/node_modules只是npm的默认prefix，删掉后npm会自动重建到~/.npm-global。
• 清理后，用npm list -g --depth=0验证全局安装列表是否为空，确保“干净重启”。
• 此套路是“外科手术”，适合环境已严重混乱的用户。日常开发，坚持套路1，永不碰sudo npm install -g。

注意：此套路耗时最长（约2分钟），但效果最彻底。我见过最极端的案例：一个团队的CI服务器因长期sudo npm install，/usr/local/bin里堆积了200+个损坏链接，ls -la卡死，rm -rf后CI流水线恢复正常。

4. 实操过程与核心环节实现：从零开始，30分钟完成Codex CLI部署

4.1 环境准备与初始诊断（5分钟）

我们以一台全新的macOS Sonoma 14.5（M1芯片）为例，预装了Homebrew和Node.js 20.12.0。目标：让codex --version稳定输出codex v1.8.3。

第一步：确认基础环境

# 检查Node.js和npm版本（必须>=18.0） node -v # v20.12.0 npm -v # 10.5.0 # 检查当前shell（macOS默认zsh） echo $SHELL # /bin/zsh # 检查npm prefix初始值 npm config get prefix # /opt/homebrew/lib/node_modules （Homebrew安装的默认值）

此时/opt/homebrew/lib/node_modules属于Homebrew管理，普通用户无权写入。npm install -g会fallback，但我们不知道fallback到哪——这就是初始诊断的盲点。

第二步：执行套路1（校准prefix）

# 创建用户级npm目录 mkdir -p ~/.npm-global # 设置prefix npm config set prefix ~/.npm-global # 将bin目录加入PATH echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc # 重载配置 source ~/.zshrc # 验证 npm config get prefix # /Users/xxx/.npm-global echo $PATH | tr ':' '\n' | grep npm # /Users/xxx/.npm-global/bin

此时，prefix已锁定在用户目录，PATH也已更新。这是后续所有操作的地基。

4.2 安装与链接重建（10分钟）

第三步：安装Codex并验证bin

# 安装（注意：此时已无需sudo） npm install -g @opencode-ai/codex # 检查bin目录 ls -la ~/.npm-global/bin/codex* # 输出：lrwxr-xr-x 1 xxx staff 41 May 20 10:30 /Users/xxx/.npm-global/bin/codex -> ../lib/node_modules/@opencode-ai/codex/bin/codex.js

链接存在，且权限为r-x（可执行），说明安装成功。

第四步：测试命令（关键转折点）

codex --version # 如果报错：zsh: command not found: codex # 说明PATH未生效，执行套路3 echo 'export PATH=$(npm config get prefix)/bin:$PATH' >> ~/.zshrc source ~/.zshrc codex --version # codex v1.8.3 ✅

这里有个细节：source ~/.zshrc后，必须用codex --version而非which codex验证，因为which只查PATH，而codex --version会真正执行JS文件，验证Node.js环境是否就绪。

4.3 VS Code集成与IDE适配（10分钟）

第五步：配置VS Code终端打开VS Code，Cmd+,进入设置，搜索terminal integrated profiles，点击Edit in settings.json，粘贴以下配置：

{ "terminal.integrated.profiles.osx": { "zsh": { "path": "/bin/zsh", "args": ["-l"] } }, "terminal.integrated.defaultProfile.osx": "zsh" }

保存后，关闭所有终端标签页，Cmd+Shift+P→Terminal: Create New Terminal，新建一个终端。

第六步：在VS Code终端中验证

# 检查PATH是否包含npm bin echo $PATH | tr ':' '\n' | grep npm # 应该有 /Users/xxx/.npm-global/bin # 检查codex是否可用 codex --version # codex v1.8.3 ✅ # 检查VS Code插件能否调用 # 打开一个.ts文件，按Cmd+Shift+P，输入"Codex: Ask"，应该能触发对话框

如果VS Code里codex --version成功，但插件仍报command not found，说明插件缓存了旧PATH。此时Cmd+Shift+P→Developer: Reload Window，强制刷新。

4.4 Windows全流程实录（15分钟，PowerShell环境）

以Windows 11 22H2为例，Node.js通过官网MSI安装（v20.12.0），VS Code 1.90。

第一步：校准prefix

# PowerShell中执行 mkdir $HOME\.npm-global npm config set prefix "$HOME\.npm-global" [Environment]::SetEnvironmentVariable("PATH", "$HOME\.npm-global\bin;" + [Environment]::GetEnvironmentVariable("PATH", "User"), "User") # 重启PowerShell

第二步：绕过执行策略

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser # 验证 Get-ExecutionPolicy -Scope CurrentUser # RemoteSigned

第三步：安装并验证

npm install -g @opencode-ai/codex # 检查文件 Get-ChildItem "$HOME\.npm-global\bin\codex*" # 输出：codex.ps1 和 codex.cmd # 执行 codex --version # codex v1.8.3 ✅

第四步：VS Code配置在VS Code设置中，搜索terminal integrated default profile，将默认终端设为PowerShell。然后Ctrl+Shift+P→Terminal: Create New Terminal，新终端中执行codex --version，必成功。

4.5 故障树与决策流程图（文字版）

当codex: command not found再次出现，按此流程排查：

开始 │ ├─ 1. 在系统终端执行 `codex --version` │ ├─ 成功 → 跳至第4步（IDE问题） │ └─ 失败 → 进入第2步 │ ├─ 2. 执行 `npm config get prefix` │ ├─ 输出 `/usr/local` 或 `C:\Program Files\nodejs` → 执行套路1 │ ├─ 输出 `~/.npm-global` 或 `$HOME\.npm-global` → 进入第3步 │ └─ 其他 → 记录值，执行套路1重置 │ ├─ 3. 执行 `ls -la $(npm config get prefix)/bin/codex*` (macOS/Linux) 或 `Get-ChildItem "$env:APPDATA\npm\codex*"` (Windows) │ ├─ 文件存在 → 进入第5步（PATH问题） │ └─ 文件不存在 → 执行套路2（rebuild） │ ├─ 4. 在VS Code终端执行 `codex --version` │ ├─ 成功 → 结束 │ └─ 失败 → 执行套路6（IDE配置） │ └─ 5. 执行 `which codex` 或 `Get-Command codex` ├─ 有输出 → 可能是执行策略问题（Windows）→ 套路4或5 └─ 无输出 → 执行套路3（PATH注入）

此流程图覆盖95%场景，平均排查时间<3分钟。

5. 常见问题与排查技巧实录：那些文档里不会写的“血泪教训”

5.1 “装了两次，PATH里有两个codex，但只认第一个”——PATH顺序陷阱

现象：
echo $PATH输出很长，其中包含/usr/local/bin和/Users/xxx/.npm-global/bin。which codex返回/usr/local/bin/codex，但执行时报错，而/Users/xxx/.npm-global/bin/codex是好的。

原因：
PATH搜索是从左到右的。/usr/local/bin在/Users/xxx/.npm-global/bin前面，shell优先找到坏链接，直接报错，根本不会继续向后搜索。

解决方案：
编辑.zshrc，确保export PATH=~/.npm-global/bin:$PATH这一行在所有其他PATH修改之前。例如：

# ✅ 正确：新PATH放最前 export PATH=~/.npm-global/bin:$PATH export PATH=/opt/homebrew/bin:$PATH export PATH=$HOME/bin:$PATH # ❌ 错误：新PATH放后面 export PATH=/opt/homebrew/bin:$PATH export PATH=$HOME/bin:$PATH export PATH=~/.npm-global/bin:$PATH # 这行无效！

独家技巧：用echo $PATH | awk -F: '{print $1}'快速查看PATH第一个目录，确认是否为你期望的codex所在目录。

5.2 “VS Code里PATH是对的，codex也能which到，但执行就卡住不动”——Node.js版本冲突

现象：
which codex返回/Users/xxx/.npm-global/bin/codex，codex --version执行后光标闪烁，无输出，10秒后超时。

原因：
codex脚本内部调用node执行JS，但VS Code终端里node -v显示v16.20.0，而codex要求v18+。系统终端里node -v是v20.12.0，但VS Code终端加载了旧版本nvm。

解决方案：
在VS Code设置中，添加：

{ "terminal.integrated.env.osx": { "NVM_DIR": "/Users/xxx/.nvm" } }

然后在VS Code终端里执行：

source ~/.nvm/nvm.sh nvm use 20.12.0 codex --version # 立刻响应

实操心得：VS Code的terminal.integrated.env可以注入任意环境变量，这是解决IDE环境隔离的银弹。

5.3 “npm install -g codex成功，但codex命令只能在安装目录下运行”——相对路径陷阱

现象：
cd ~/.npm-global/lib/node_modules/@opencode-ai/codex后，./bin/codex --version成功，但在家目录下codex --version失败。

原因：
./bin/codex是相对路径执行，不依赖PATH。而全局命令必须通过PATH查找。这说明~/.npm-global/bin根本没加进PATH，或者加错了位置。

排查命令：

# 查看当前shell加载了哪些配置文件 echo $ZDOTDIR ls -la ~/.zsh* # 看是否有.zshenv, .zprofile, .zshrc # 检查哪个文件里写了PATH grep -n "PATH=" ~/.zsh* 2>/dev/null

修复：
找到写PATH的文件（通常是.zshrc），确认export PATH=~/.npm-global/bin:$PATH这一行存在且未被注释。如果.zshenv里有export PATH=...，它会覆盖.zshrc，必须统一管理。

5.4 “公司电脑IT锁死，npm config set prefix被拒绝”——受限环境终极方案

现象：
执行npm config set prefix ...报错Error: EACCES: permission denied, open '/usr/local/etc/npmrc'，说明npm全局配置文件被IT组只读锁定。

解决方案：
不用npm config，直接修改用户级配置文件：

# 创建用户配置文件 echo "prefix = $HOME/.npm-global" > ~/.npmrc echo "cache = $HOME/.npm-cache" >> ~/.npmrc # 然后安装 npm install -g @opencode-ai/codex

~/.npmrc是用户级配置，IT组无法锁定，100%生效。

补充技巧：
在受限环境，用npx临时运行Codex：

npx @opencode-ai/codex --version # 虽然慢（