你装好了 Claude Code，可是在终端里敲 claude 却冒出这样的提示——是不是很眼熟？
zsh: command not found: claude # macOS
bash: claude: command not found # Linux
'claude' is not recognized as an internal or external command # Windows CMD
claude : The term 'claude' is not recognized as the name of a cmdlet # PowerShell这个错误的意思是 “找不到 claude 这个可执行文件”，而成因绝大多数都是 “安装目录没有加入 PATH”。很多时候安装本身是成功的——只是 shell 不知道该去哪里找。本文对照 2026 年 9 月 29 日的官方文档，系统梳理 安装方式与位置、如何修复 PATH、多重安装之间的冲突、Windows 特有的陷阱，以及更新方式。
先说要点。（1）command not found 几乎都只是“~/.local/bin（安装目录）没在 PATH 里”——把它加上、重启终端就好了。（2）npm 的权限错误（EACCES）不要用 sudo 去解决——改用原生安装器才对。（3）卡住时就跑 claude doctor——它会把安装状态、设置和更新结果一并检查。具体命令和默认值会随版本变化，最新信息请以官方文档为准。
按你看到的提示查找
| 看到的文字 | 出现位置 | 对应小节 |
|---|---|---|
zsh: command not found: claudebash: claude: command not found | macOS / Linux | §3 |
'claude' is not recognized as an internal or external commandclaude : The term 'claude' is not recognized as the name of a cmdlet | Windows 的 CMD / PowerShell | §3、§4 |
Native installation exists but ~/.local/bin is not in your PATH | claude doctor、输入框下方 | §3 |
Failed to run Claude Code: Error: Could not locate the Claude CLI on PATH | Windows 上的 VS Code | §4 |
更新之后立刻出现 'claude' is not recognized | Windows | §4 |
Auto-update failed · Run claude doctor | 运行中会话的状态栏 | §5 |
装好了，却找不到
— 只是安装目录没在 PATH 里
二进制文件 确实存在。只是 shell 搜索的 PATH 里没有列出它的位置。
所以修复方法就是 “给 PATH 加一行”——通常几十秒就搞定。
1. 这个错误到底在说什么
当你敲下一条命令时，shell（zsh / bash / PowerShell）会 按顺序搜索 PATH 环境变量里列出的各个文件夹，并运行第一个匹配到的可执行文件。command not found: claude 意味着 这些文件夹里没有一个包含 claude。
关键在于：这并不一定代表安装失败了。原生安装器会把 claude 放在 ~/.local/bin（Windows 为 %USERPROFILE%\.local\bin），但只要 这个文件夹没在 PATH 里，二进制文件就算存在，shell 也找不到。所以 大多数情况都能靠“给 PATH 加一行并重启终端”解决。在怀疑安装失败之前，先跑 ls ~/.local/bin/claude 确认 二进制文件是否就在那里。
在 Windows 上，安装命令“用错了 shell”（例如把 PowerShell 命令放到 CMD 里跑）会产生不同的错误——这部分在 §4 讲。先把正确的安装方式和位置弄清楚。
2. 安装方式与二进制文件的位置
下面是截至 2026 年 9 月 29 日官方安装页面列出的安装方式，以及二进制文件最终落在哪里（推荐使用原生安装器）。
| 方式 | 命令（形态） | 位置 / 备注 |
|---|---|---|
| 原生（推荐）mac/Linux/WSL | curl -fsSL https://claude.ai/install.sh | bash | ~/.local/bin/claude。支持自动更新 |
| 原生（推荐）Windows PowerShell | irm https://claude.ai/install.ps1 | iex | %USERPROFILE%\.local\bin\claude.exe。支持自动更新 |
| 原生（推荐）Windows CMD | curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd | 位置与 PowerShell 相同 |
| npm | npm install -g @anthropic-ai/claude-code | Node.js 22 及以上（自 v2.1.198 起）。安装同一个原生二进制 |
| Homebrew（mac） | brew install --cask claude-code | 不自动更新 → brew upgrade claude-code（另有跟随每个版本的 claude-code@latest） |
| WinGet（Windows） | winget install Anthropic.ClaudeCode | 不自动更新 → winget upgrade Anthropic.ClaudeCode |
| apt / dnf / apk（Linux） | 面向 Debian、Fedora、RHEL、Alpine 的签名软件源 | 不自动更新 → 用包管理器升级 |
要点在于：官方推荐原生安装器。npm 版安装的是 同一个原生二进制文件。自 v2.1.198 起 npm 包要求 Node.js 22 或更高，但在旧版 Node.js 上 npm 只会给出 EBADENGINE 警告，安装照样完成（二进制运行时不需要 Node）。npm 这条路 更容易出现权限和 PATH 问题，如果是全新安装，原生才是稳妥之选。另外要注意，只安装 VS Code 扩展会在扩展内部捆绑一个私有 CLI，并不会把 claude 加进 PATH——如果你想在终端里用 claude，需要另行单独安装。
3. 主要成因与修复
下面把 command not found 周边常见的成因与对应的修复方法成对列出。
安装 / PATH 的主要诱因
~/.local/bin 不在 PATH 里。把 export PATH="$HOME/.local/bin:$PATH" 加到 ~/.zshrc/~/.bashrc 并重启终端。sudo npm（官方不建议）。改用原生安装器是最快也最安全的修复。EBADENGINE 警告。它 不是 找不到 claude 的原因——先检查 PATH。which -a claude（Win：where.exe claude）检查，并 只保留原生那一个。Error: claude native binary not installed. 表示 可选依赖或 postinstall 步骤被跳过了。去掉 --omit=optional 或 --ignore-scripts 再重新安装。
拿不准时，“用原生安装器重装” 能解决其中大部分——
它能一次性绕开权限、Node 和冲突的问题。
一个具体的 PATH 修复示例（macOS zsh）：echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc，然后 source ~/.zshrc。在 Linux 的 bash 上，对 ~/.bashrc 做同样的事；在 macOS 上用 bash 的话，要写进 ~/.bash_profile（终端把 bash 作为登录 shell 启动，不读取 ~/.bashrc）。在 Windows PowerShell 中，用 [Environment]::SetEnvironmentVariable('PATH', "$([Environment]::GetEnvironmentVariable('PATH', 'User'));$env:USERPROFILE\.local\bin", 'User') 把目录加进用户 PATH。改完之后，打开一个新的终端，用 claude --version 确认。
“Native installation exists but ~/.local/bin is not in your PATH”
这条警告出现在 claude doctor 的输出里（Installation warnings 一栏），以及 输入框下方。按用户在官方 GitHub issue 中贴出的原文，它是这样的：
Native installation exists but ~/.local/bin is not in your PATH
Run: echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc then open a new terminal or run: source ~/.zshrc意思是 原生二进制就在 ~/.local/bin 里，但 Claude Code 看到的 PATH 里没有这个目录。修法与上面相同：把那一行写进 shell 的配置文件，再打开新终端。如果在新终端里 echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin" 已经能打印出该目录，警告却仍然出现，那就属于 GitHub 上报告过的情况（#63695：PATH 只写在 ~/.zshenv 里，并从 VS Code 终端启动；#75431：claude 装在别的位置）。截至 2026 年 9 月 29 日，这两个 issue 都未修复就已关闭。只要 claude --version 在新终端里能正常运行，安装本身就没有问题。
4. Windows 特有的陷阱
在 Windows 上，最经典的失败就是 把安装命令“用错了 shell”去跑。错误信息会告诉你到底搞错了哪一种。
识别用错 shell 的情况
| 错误 | 含义与修复 |
|---|---|
'irm' is not recognized as an internal or external command | 在 CMD 里跑了 PowerShell 命令 → 打开 PowerShell 运行 irm https://claude.ai/install.ps1 | iex，或改用 CMD 安装器 |
The token '&&' is not a valid statement separator | 在 PowerShell 里跑了 CMD 命令 → 改用 PowerShell 安装器 |
A parameter cannot be found that matches parameter name 'fsSL' | 在 PowerShell 里跑了 macOS/Linux 的 curl 命令（PowerShell 中的 curl 是 Invoke-WebRequest 的别名）→ 改用 PowerShell 安装器 |
'bash' is not recognized as the name of a cmdlet | 在 Windows 上跑了 Linux 安装器 → 改用 PowerShell 安装器 |
其他 Windows 注意事项：（1）安装后重启终端（PATH 变更要在新终端里才生效）。（2）老版本的 Claude Desktop 注册了 WindowsApps\Claude.exe，可能导致 claude 启动的是桌面应用而非 CLI——更新 Claude Desktop 即可。（3）Git for Windows 是可选的：没装时，Claude Code 通过自带的 PowerShell 工具执行命令。装了 Git 却找不到 Git Bash 时，在设置里用 CLAUDE_CODE_GIT_BASH_PATH 指向你的 bash.exe。在 WSL 下运行也是一个选择。
VS Code 的“Could not locate the Claude CLI on PATH”
在 Windows 上，当你在 VS Code 的集成终端（shell 为 PowerShell）里打开 Claude Code，而扩展在 PATH 中找不到已安装的 claude 时，VS Code 扩展会显示这个错误。开头是这样的：
Failed to run Claude Code: Error: Could not locate the Claude CLI on PATH.扩展之所以拦下启动，是因为在 PowerShell 里按名字运行 claude，可能会执行打开的文件夹里的 claude，而不是已安装的 CLI。（1）在 VS Code 之外打开新的 PowerShell 窗口，运行 where.exe claude；如果什么也没打印，按 §3 把安装目录加进 PATH。（2）把 PATH 写进 用户或系统环境变量，而不是只写在 PowerShell 配置文件里（扩展不会执行你的配置文件）。（3）VS Code 只在启动时读取 PATH，所以要 重启 VS Code。
更新之后立刻出现“'claude' is not recognized”
在 Windows 上更新时，Claude Code 会先把现有的 claude.exe 改名为 claude.exe.old. 加时间戳的备份，再把新版本放到原位。如果放置失败、改名又撤销不了，%USERPROFILE%\.local\bin 里就只剩备份而没有 claude.exe。在 PowerShell 中恢复最新的备份：
Get-ChildItem "$env:USERPROFILE\.local\bin\claude.exe.old.*" | Sort-Object Name | Select-Object -Last 1 | Rename-Item -NewName claude.exe然后用 claude --version 确认。如果没有 claude.exe.old.* 文件，就用 irm https://claude.ai/install.ps1 | iex 重新安装。自 v2.1.281 起，更新失败时会自动恢复保留的可执行文件。
5. 自动更新与更新方式
原生安装会 在后台自动更新，并在下次启动时生效。要手动更新可用 claude update；要重装或固定某个特定版本可用 claude install <version>（也接受 stable / latest）。最近一次更新的结果可用 claude doctor 查看。Homebrew、WinGet、apt、dnf、apk 安装默认不会自动更新；在 Homebrew 和 WinGet 上设置 CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1 后，Claude Code 会替你执行升级命令。
npm 安装上自动更新失败时
如果 npm 全局文件夹 不可写，自动更新就会失败。claude doctor 会列出修复办法，而根本解决之道是 迁移到原生安装。若只是想停掉自动更新，可在设置的 env 里设置 DISABLE_AUTOUPDATER（手动更新仍然有效）；要彻底禁止所有更新，则设置 DISABLE_UPDATES。
“Auto-update failed · Run claude doctor”
后台更新失败时，运行中的会话会在状态栏显示这条提示。GitHub issue 里引用过两种写法：Auto-update failed · Run claude doctor（v2.1.220 至 v2.1.278），以及更早版本的 npm 安装上的 Auto-update failed · Try claude doctor or npm i -g @anthropic-ai/claude-code。按以下顺序处理：
- 在终端运行
claude doctor——会显示最近一次更新的结果和安装方面的警告。 - 运行
claude update立即更新。成功会显示Successfully updated from <old version> to version <new version>，没有待更新时显示Claude Code is up to date (<version>)。 - 如果已经是最新，说明失败只是暂时的（比如网络中断）。据 GitHub issue（#89286、#96038）报告，这条提示可能一直留到重启会话为止。
- 如果是 npm 全局安装且该目录不可写，自动更新无法工作——迁移到原生安装器（见上方的框）。
- 在公司网络中反复失败时，检查能否访问
downloads.claude.ai。
6. 排查工作流
成因不明确时，自上而下逐步排查。大多数情况在第 3 步就能解决。
自上而下逐步定位
claude doctor（若起不来就从 shell 里跑）检查 安装健康度。which -a claude / where.exe claude 看 装在哪里、装了几个（是否冲突）。~/.local/bin 加进 PATH 并重启终端。
铁则：按 “二进制存在吗 → 在 PATH 里吗 → 有没有冲突？” 的顺序来。
卡住时，原生重装 是可靠的最后一招。
总结
Claude Code 的 “command not found: claude” 在大多数情况下只是 “安装目录（~/.local/bin）没在 PATH 里”。二进制文件是存在的，所以 给 PATH 加一行并重启终端 就好了。安装方面，推荐原生安装器（npm 版要求 Node.js 22 及以上，且权限/PATH 陷阱更多）。npm 的 EACCES 应当改用原生来解决，而不是 sudo。
排查顺序为 （1）claude doctor →（2）用 which -a claude / where.exe claude 查冲突 →（3）把 ~/.local/bin 加进 PATH →（4）删除多余版本 →（5）原生重装。在 Windows 上，要留意 用错 shell（例如在 CMD 里跑 irm）、需要 重启终端，以及老版本 Claude Desktop 的 Claude.exe 冲突。更新用 claude update / claude install，停掉自动更新用 DISABLE_AUTOUPDATER。卡住时，原生重装 是可靠的修复。相关阅读：Claude Code 错误集锦、认证 / 登录错误。
FAQ
Q. 我装好了，却出现 command not found: claude。
A. 几乎可以肯定是 安装目录没在你的 PATH 里。先用 ls ~/.local/bin/claude（Windows：%USERPROFILE%\.local\bin）检查二进制文件是否存在；如果在那里，就把 export PATH="$HOME/.local/bin:$PATH" 加到 ~/.zshrc/~/.bashrc，然后 打开一个新的终端。安装本身通常是成功的。
Q. npm install -g 报权限错误（EACCES）。
A. 不要用 sudo npm（官方不建议；它会招来权限和安全问题）。最快也最安全的途径是 改用原生安装器（mac/Linux：curl -fsSL https://claude.ai/install.sh | bash）。原生构建没有权限陷阱，也无需 Node。你也可以把 npm 的全局 prefix 移到用户可写的目录，但官方推荐的是原生。
Q. 我装了多个 claude，结果跑起来的是旧版本。
A. 运行 which -a claude（Windows：where.exe claude）查看 PATH 上的每一个 claude。你可能同时混有 npm-global、Homebrew、WinGet 和原生。保留原生那一个（~/.local/bin），删除其余的（例如 npm uninstall -g @anthropic-ai/claude-code），收敛到单一安装。
Q. 在 Windows 上敲 claude 却打开了桌面应用。
A. 老版本的 Claude Desktop 注册了 WindowsApps\Claude.exe，它在 PATH 上的优先级高于 CLI。更新 Claude Desktop 即可解决。另外，如果运行 PowerShell 安装器后找不到、或显示的是旧版本，重启终端 让 PATH 变更生效。
Q. 更新不起作用 / 我想停掉更新。
A. 原生安装会在后台自动更新，并在下次启动时生效。手动更新用 claude update；要重装或固定版本用 claude install <version>。出现 Auto-update failed · Run claude doctor 时，先运行 claude doctor 再运行 claude update；如果显示已是最新，重启会话后提示就会消失。如果 npm 全局安装上的自动更新失败，那是写入权限问题——按 claude doctor 的提示 迁移到原生。要停掉自动更新，在设置的 env 里设置 DISABLE_AUTOUPDATER；要禁止所有更新，则设置 DISABLE_UPDATES。
