先说一下我自己的经历。去年有段时间，我 Mac 的终端几乎每天都要遇到一次zsh: command not found，而且不是某个特定命令的问题，是npm install -g装完任何全局工具，比如一些 CLI 脚手架、命令行小工具，敲命令的时候终端都像失忆了一样告诉我找不到。试过重装 Node、清理缓存、重启终端，都无济于事。折腾很久之后才明白，这根本不是某个包的问题，而是 npm 的全局安装目录和 zsh 的环境变量 PATH 没有对齐。这篇文章就把这条排查路径完整写出来，包括问题产生的原因、不同安装方式下的差异、具体的解决办法，以及我踩过的那些坑。如果你也被同一句话折磨过，照着下面的思路走一遍，基本都能解决。
1. 先搞清楚 zsh 到底在哪儿找命令
1.1 终端执行命令时发生了什么
你每次在 zsh 里敲一个命令，zsh 并不会直接去全盘扫描哪个目录里藏着这个可执行文件。它有一套自己的查找顺序：先去内存里查一遍已经记录过的命令哈希表，查不到就按环境变量PATH里列出的目录顺序，挨个目录去搜索同名文件。找到了就执行，找不到就返回zsh: command not found。
这个机制用大白话讲，就像你朋友让你去某个小区找一个叫张三的人。你先在脑子里回忆一下张三长什么样、住几栋几单元，这是哈希表命中；回忆不起来就拿出通讯录，通讯录里记了哪些小区名字，你就按顺序去这些小区门口查访，这是 PATH 搜索；整个通讯录翻完了都没有，你只能告诉朋友“这个小区里根本没有张三”。
所以command not found说的严格一点，不是“这个命令不存在”，而是“zsh 按 PATH 配置的目录范围里，没有找到这个命令”。这句话是理解整篇文章的钥匙，后面所有的排查都是围绕 PATH 来展开的。
1.2 为什么偏偏是 npm 全局安装后爆雷
npm 安装全局工具时，默认会把可执行文件放到一个目录里，但这个目录不一定在你的 PATH 中。macOS 上 PATH 的默认组成一般包含/usr/local/bin、/usr/bin、/bin、/usr/sbin、/sbin等，外加 Homebrew 自己的一些目录。问题在于，不同方式安装的 Node.js，npm 计算出的全局安装路径根本不一样；而不同的 shell 配置方式，又会决定这些路径到底有没有被加进 PATH。
更麻烦的是，npm 安装完成时只会打印“added X packages”，它不会帮你修改任何一处 shell 配置文件，更不会负责让你的终端重新加载配置。也就是说npm install -g装完之后，路径不会自动出现在你当前的终端里，除非你手动刷新 PATH，否则新开的终端大概率还是找不到命令。这就是“不管装啥都报 command not found”的典型场景，问题不在包，而在路径对接。
1.3 排查前先确认 Node 和 npm 自身状态
动手改任何配置之前，先确认这台机器上的 Node 和 npm 本身是健康可用的。命令行执行以下操作：
node -v npm -v如果这两行能正常打印版本号，说明 Node 环境本身没问题。接着再用which确认当前调用的是哪个 Node：
which node记住这个结果，后面会反复用到。比如输出是/usr/local/bin/node，说明你用的是官方安装包；输出是/opt/homebrew/bin/node，说明是 Homebrew 装的；如果是~/.nvm/versions/node/v18.20.0/bin/node，说明是 nvm 管理的版本。这三种来源对应的 npm 全局路径完全不同，搞错方向会越修越乱。
提示：如果你连
node、npm都提示 command not found，那就不是“全局工具找不到路径”的问题了，而是 Node 本身还没接入 PATH。这种情况建议先重新装一遍 Node，或者确认 nvm 的启动脚本是否被误删。
2. 根因定位：你的 npm 到底把命令装到了哪里
2.1 用 npm config get prefix 找安装前缀
npm 的全局安装目录由一个叫prefix的配置项控制。执行下面的命令，看看当前真实值：
npm config get prefix这个命令会打印一个绝对路径，比如/usr/local、/opt/homebrew、/Users/你的用户名/.nvm/versions/node/v20.11.0等。关键点来了：npm 会把可执行文件放在<prefix>/bin目录，把模块代码放在<prefix>/lib/node_modules目录。所以如果你想让全局命令生效，就必须确保<prefix>/bin出现在 PATH 里。
再补充一个命令：
npm root -g这个命令打印的是全局模块的库目录，也就是<prefix>/lib/node_modules，它不是放命令的地方。很多人把这个路径加进 PATH，结果当然没用。记住：命令在bin目录，不在lib/node_modules目录。
2.2 不同 Node 安装方式下的路径差异
我在实际排查中发现，大部分人并不是安装方式有问题，而是“搞不清自己的安装方式对应的路径”。下面这个表是 macOS 上主流的三种情况，可以直接对照：
| Node 安装方式 | npm 默认 prefix | 全局命令实际目录 | 这个目录通常在 PATH 里吗 |
|---|---|---|---|
| 官网 pkg 安装包 | /usr/local | /usr/local/bin | 通常默认已在 PATH |
| Homebrew（Intel） | /usr/local | /usr/local/bin | 通常默认已在 PATH |
| Homebrew（Apple Silicon） | /opt/homebrew | /opt/homebrew/bin | Homebrew 会自动写入 |
| nvm 管理版本 | ~/.nvm/versions/node/vxx.x.x | ~/.nvm/versions/node/vxx.x.x/bin | 需要 nvm 加载脚本生效 |
你会发现，官网包和 Homebrew 装出来的 Node，全局命令目录基本都在默认 PATH 里，所以正常情况下不会报 command not found。真正容易出问题的是 nvm 场景：nvm 每个 Node 版本都有独立的全局目录，如果你切换了 Node 版本，或者 nvm 的启动脚本没有正常加载，那些装过的全局命令就会像人间蒸发一样。
还有一种情况更隐蔽：你自己手动执行过npm config set prefix ~/.npm-global或其他自定义前缀。一旦你设置了自定义 prefix，npm 就会把命令装到~/.npm-global/bin这类目录，而这个目录几乎不可能在默认 PATH 里，于是无论装什么命令都会报找不到。很多教程会推荐这种方式来规避权限问题，但如果你不知道还要补一步 PATH 配置，就等于挖了一个大坑。
2.3 一个容易被忽略的细节：全局安装和 npx 的区别
有时候你并没有真正执行全局安装，而是用npx临时运行了一个包。npx 会把包下载到缓存目录里，在临时环境执行命令，装完之后当然不会留下一个全局可用命令。所以如果你看到某篇教程里写“运行npx create-react-app”，然后你回到新终端敲create-react-app，出现 command not found 是非常正常的，因为那本来就只是临时调用，不是全局安装。
反过来，如果你确实执行的是npm install -g，安装时 npm 也打印了成功日志，但敲命令仍然报错，那就不必怀疑人生，几乎可以断定是 PATH 缺了<prefix>/bin。还有一种特殊情况，某些 scoped 包，例如@vue/cli安装后命令叫vue，而不是@vue/cli；@nestjs/cli安装后命令叫nest。如果包名和命令名对不上，你可能在敲一个根本不存在的命令。遇到这种情况去包的官方文档查一下bin字段，或者临时执行npm ls -g --depth=0看看安装的包名列表。
3. 对症下药：三种解法，照着做就行
3.1 方案 A：把 npm 全局目录指向用户目录并加入 PATH
这个方案我目前最推荐，因为不需要 sudo，也避开了系统目录权限限制。原理很简单：让 npm 把全局文件装到用户自己的目录下，再把那个目录的bin路径加入 PATH。
第一步，创建全局安装根目录并修改 npm 配置：
mkdir -p ~/.npm-global npm config set prefix ~/.npm-global第二步，把 bin 目录加入当前 shell 的 PATH：
export PATH="$HOME/.npm-global/bin:$PATH"第三步，为了下次新开的终端也生效，需要把上面这行写入~/.zshrc：
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc第四步，重新加载配置：
source ~/.zshrc然后重新执行一遍之前安装失败的全局包，例如：
npm install -g some-cli some-cli --version正常情况下这次就可以正确输出版本号了。需要说明的是，把$HOME/.npm-global/bin放在 PATH 的前面还是后面会影响命令查找优先级。放在前面意味着这个目录里的命令会优先于系统目录里的同名命令，如果想避免和系统命令冲突，放在后面更稳妥，不过对于 npm 全局工具来说问题不大，我习惯放在最前面方便覆盖。
3.2 方案 B：不挪位置，直接把原 prefix 的 bin 加进 PATH
如果你不想改变 npm 的默认安装路径，也可以保持 prefix 不变，只做 PATH 补充。先用第 2 章的方法拿到 prefix 值，然后把它拼进 PATH。
比如 prefix 是/usr/local，就执行：
export PATH="/usr/local/bin:$PATH" echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.zshrc source ~/.zshrc如果 prefix 是/opt/homebrew，那就写：
export PATH="/opt/homebrew/bin:$PATH"不过这里有一条重要原则：如果 prefix 是/opt/homebrew且你是通过 Homebrew 安装的 Node，/opt/homebrew/bin通常已经被 Homebrew 写入 PATH 了，你还要手动补说明有其他配置把你原有的 PATH 覆盖了。这种情况不能只盯着 PATH 颠倒顺序，还要去查配置文件的覆盖问题。具体我在第 4 章会重点讲。
3.3 方案 C：nvm 用户需要先处理版本切换问题
如果你的 Node 由 nvm 管理，全局工具的路径绑定到具体的 Node 版本目录，比如~/.nvm/versions/node/v18.20.0/bin。这种情况下有两个常见病灶。
第一个病灶是 nvm 的启动脚本丢失。打开~/.zshrc，检查有没有下面这行：
export NVM_DIR="$HOME/.nvm" [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"如果没有就补上，然后重新加载配置。如果连nvm命令本身都提示 command not found，多半就是这段脚本丢了，先解决它，再看全局命令。
第二个病灶是装完全局包之后切换了 Node 版本。你在 Node 18 下执行npm install -g some-cli，命令出现在 v18 的 bin 目录；之后nvm use 20切换到 Node 20，当前 PATH 里的 bin 目录指向 v20，那个全局命令自然就找不到了。这个问题的解法是：要么切回原来的版本再使用命令，要么干脆在当前版本下重新安装一次全局包，或者在升级 Node 新版本时用 nvm 的迁移功能把全局包带过去。我的习惯是，长期稳定的项目固定用一个 LTS 版本，避免为了保持全局工具可用而频繁切换版本。
3.4 配置完成后的一整套验证流程
改完配置不能光看“命令能用了”就结束。我建议按下面的顺序完整验证一遍：
npm config get prefix确认 prefix 指向你期望的目录。
echo $PATH确认<prefix>/bin真的出现在输出中，注意看位置是否靠前。
which some-cli如果输出类似~/.npm-global/bin/some-cli，说明找到了；如果输出not found，说明 PATH 还没生效，大概率需要重新打开终端。
再执行一下：
command -v some-cli和which效果类似，确认命令是否可被 zsh 找到。最后再实际跑一遍版本号命令。整套流程下来，能一次性发现问题出在配置没写对、终端没刷新，还是路径本身拼错了。
4. 高频踩坑现场：为什么我改了 PATH 还是不行
4.1 你改了 PATH，但被后面的 export 覆盖了
这是最隐蔽也最坑的一种情况。打开~/.zshrc，你会发现里面可能有很多行长这样的配置：
export PATH="/Users/xxx/flutter/bin:$PATH" export PATH="/Users/xxx/miniconda3/bin:$PATH" export PATH="/usr/local/bin:$PATH"看起来每个工具都在往 PATH 里追加目录，对吧？问题在于，如果某一行写成了下面这种形式：
export PATH="/usr/local/bin"注意看，这里没有冒号也没有$PATH，它等于把整个 PATH 变量重新赋值成了/usr/local/bin，前面所有工具加进去的目录在这一瞬间就全部消失了。常见的触发场景是：你在某次配置工具时照抄了网上的错误命令，顺手粘进了 zshrc；以后每次打开终端，PATH 永远只保留最后一次 export 的内容。npm 全局命令的 bin 目录如果排在这些 export 前面，就会被无情抹掉。
排查方法是执行echo $PATH，看输出里有没有完整保留 Homebrew、nvm 和 npm 的路径，而不是只有孤零零一个目录。修复方式是删掉那些没有$PATH的 export 行，或者改成标准追加写法：
export PATH="/some/dir/bin:$PATH"4.2 用 sudo 安装带来的权限混乱
很多旧教程会让你执行sudo npm install -g，理由是“权限不够”。对于新版 Mac 上使用 nvm 的场景，这完全是错误操作。一旦你用 sudo 装了全局包，它文件归属就变成了 root，而你的日常用户想卸载它，会提示没有权限；后续想切换目录、修改配置，也会处处受制。更重要的是，用 sudo 安装并不能解决 PATH 问题，因为 PATH 是环境变量，不归 sudo 管。
如果已经发生这种情况，我的建议是不要试图用chown去改整个目录的归属，麻烦不说，还可能影响系统其他部分。正确操作就是先查文件归属，确认后把受影响的全局包卸载重装，而且这次不要加 sudo：
ls -l /usr/local/lib/node_modules sudo npm uninstall -g some-cli npm install -g some-cli只要你把 npm 的 prefix 指向用户目录，比如第 3 章的~/.npm-global，根本不需要 sudo。这也是为什么我强烈推荐方案 A 的原因，从源头避开权限坑。
4.3 命令本身不叫你以为的那个名字
有些时候“command not found”和 PATH 毫无关系。npm 包名和它提供的命令名并不一定是同一个字符串。@angular/cli的命令是ng，@vue/cli的命令是vue，@nestjs/cli的命令是nest，而像expo-cli的命令又确实是expo。如果你看着包名瞎猜命令名，很容易猜错。
排查方法也简单：先看全局安装的包列表：
npm ls -g --depth=0找到那个包名后，用它真实的 package.json 来确认 bin 字段：
npm view <包名> bin这个命令会返回实际的可执行命令名。也可以临时在终端里执行ls <prefix>/bin，直接看这个目录里躺着哪些命令，一目了然。
4.4 新终端生效了，但当前终端就是不行
还有一部分人遇到的情况是：配置改完后，关闭终端再重新打开，命令能用了；但刚配置完时在当前终端敲命令还是报错。这不算故障，而是 shell 配置的生效时机问题。~/.zshrc只在 zsh 启动时读取一次，你修改了文件，当前会话里的 PATH 不会自动更新。我的习惯是改完配置文件立刻执行：
source ~/.zshrc让当前会话直接重新读取配置，省得反复开关终端。如果是修改了系统级的/etc/paths或/etc/zshrc，那就只能重新打开终端窗口了。另外，如果你用的终端软件不是系统自带终端，比如 iTerm2，也可能存在配置缓存，有时需要彻底退出终端 App 再重新打开才能加载最新配置。
4.5 Homebrew 和 nvm 同时存在导致 PATH 打架
我见过很多机器的echo $PATH输出里，同时包含/opt/homebrew/bin和~/.nvm/versions/node/v20/bin。这两个目录里各自都有不同版本的 node 和 npm 工具链。Homebrew 版的 node 和 nvm 版的 node 在 PATH 里谁排前面，决定了你当前用的到底是哪个 Node。
如果 PATH 顺序里 Homebrew 的 node 排在前面，你执行which npm会看到/opt/homebrew/bin/npm；而 nvm 的 npm 全局工具却在另一个版本目录下。这两个环境互相抢夺命令，就很容易让人误判。我的建议很直接：要么把 Node 的管理完全交给 nvm，移除 Homebrew 的 node 包；要么不用 nvm，把 nvm 的加载脚本从 zshrc 里移走。两个版本管理器并存对日常开发没有必要，遇到问题也很难排查。
5. 原理吃透之后，怎样长期远离这个报错
5.1 zsh 配置文件的加载顺序和 PATH 的写入时机
macOS 上 zsh 会按不同启动场景读取不同配置文件。登录 shell 会依次加载/etc/zprofile、~/.zprofile、/etc/zshrc、~/.zshrc；非登录交互式 shell 主要读取~/.zshrc。要保证任何一个新终端都能找到 npm 全局命令，最佳位置就是~/.zshrc。有些教程让你把 PATH 配置写进~/.bash_profile，这对默认 shell 是 zsh 的 macOS 没有意义，因为 zsh 根本不会读 bash 的配置文件。还有少量配置写在~/.zshenv里也能生效，但那个文件影响范围太广，容易产生副作用，不推荐日常使用。
PATH 的写入时机也很关键。zsh 启动时是从上到下逐行执行配置文件的，前面执行的export PATH=...会先改变变量值，后面执行的命令会基于这个值继续处理。所以如果你在 zshrc 里既写了 nvm 的初始化脚本，又手动 export 了一串 PATH，顺序反了就可能出现 nvm 刚把 Node 版本目录加进去，下一秒就被别的配置覆盖掉。我的做法是，所有 PATH 相关的 export 都集中放在 zshrc 的前半部分，nvm 初始化放在它们之前，确保追加的路径都能保留下来。
5.2 统一全局工具目录，维护成本最低
当我把 npm 的 prefix 改成~/.npm-global之后，我同时把 Python 的 pip、Ruby 的 gem 里那些不常用的 CLI 工具也尽量归拢到用户目录。这样做的直接好处是：备份环境时只要管一个目录，清理时也只需要删一个目录，不用担心误删系统文件。
具体来说，我用 zshrc 里的一组 export 维护了一个符合自己习惯的 PATH：
export PATH="$HOME/.npm-global/bin:$PATH" export PATH="$HOME/.local/bin:$PATH"~/.npm-global/bin放 npm 相关工具，~/.local/bin放其他脚本。每次新装机器，只要复制 zshrc 和这两个目录，开发环境就能快速还原。这个办法看起来土，实际用起来非常省心。
5.3 能 npx 就不全局装，能本地装就不污染全局
最后分享一个观念层面的习惯，这能帮你从源头减少 command not found 的出现频率。现在很多官方文档都推荐使用npx来临时执行各类脚手架工具，比如：
npx create-vite@latest my-app这种用法不会在全局留下任何命令，自然不会产生“装完找不到”的问题。而对于一个项目里的构建工具，比如vite、eslint、prettier，应该作为开发依赖安装在项目本地，用npm run dev、npm run build这类的脚本去调用，而不是全局安装。全局只留那些真正跨项目、高频使用的 CLI，例如一些自己写的日常脚本工具、静态服务器等。这样 PATH 配置基本不会出问题，反而更接近团队协作时环境一致的要求。
我在实际使用中还发现，与其在出现问题后挨个查 PATH，不如每次安装新工具后主动执行一次which <命令>来验证一遍。几十秒的功夫，能省下后面一整天的排查时间。方法也好记：装完全局包先问一句“which 找得到吗”，如果找不到，不要急着重装，先检查 prefix 和 PATH，问题往往就在这两个变量之间的错位里。
