Claude Code 安装失败怎么办：常见报错与排查

这篇适合谁、读完能做到什么

装完 Claude Code 却找不到 claude 命令、安装脚本下载失败、或者登录一直报错，是入门时最常见的卡点。这篇按报错和症状来查。读完你应该能分辨问题出在 PATH、网络、代理证书、残留的旧版本还是登录状态，并且照着把它修好。^[1]

装好了却找不到 claude 怎么办

原生安装器会把启动文件放在 macOS 和 Linux 的 ~/.local/bin/claude，Windows 上是 %USERPROFILE%\.local\bin\claude.exe。如果安装输出里出现 Native installation exists but ~/.local/bin is not in your PATH.，说明程序已经装好，只是这个目录不在 PATH 里。安装器只提示修法，不会替你改 PATH。^[1]

先在终端里确认文件是否存在：

ls -la ~/.local/bin/claude

如果列出了文件，再检查 PATH。下面这条命令没有输出，就说明目录不在 PATH 里：

echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin"

macOS 默认用 Zsh，把目录加进 PATH 的命令是 echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc，然后执行 source ~/.zshrc。^[1] Linux 上的 Bash 写入 ~/.bashrc。macOS 上的 Bash 要写入 ~/.bash_profile，因为 Terminal 把 Bash 当作登录 shell，它只读取 ~/.bash_profile、~/.bash_login、~/.profile 中第一个存在的文件。^[1]

改完之后，原来开着的终端窗口还是旧的 PATH。在编辑器里面打开的终端，PATH 来自编辑器本身，所以要开新窗口，或者重启编辑器。然后运行 claude --version 确认。^[1]

只装了 VS Code 扩展的情况要注意：扩展把一份私有的 CLI 放在自己的目录里，给聊天面板用，不会把 claude 加入 PATH。想在终端里用 claude，必须再做一次独立的原生安装。^[1]

下载被拦、连不上 downloads.claude.ai 怎么办

安装器从 downloads.claude.ai 下载程序。可以先用一条命令测试能不能连上：

curl -sI https://downloads.claude.ai/claude-code-releases/latest

返回第一行是 200 就说明连通了。返回 403 通常是代理或网络过滤拦截了这个域名，也可能是所在地区不支持 Claude Code；返回 5xx 一般是服务暂时出问题，等几分钟再试。^[1] 如果输出里是 App unavailable in region，说明所在国家不在支持范围内，官方文档附有支持国家的列表。^[1]

用公司代理的话，安装前要先设置 HTTP_PROXY 和 HTTPS_PROXY，地址不清楚就去问 IT 部门。^[1]

公司网络证书报错怎么办

公司代理如果做 TLS 检查，会让安装和后续请求出现证书错误。官方文档的做法是让安装脚本的 curl 和 Claude Code 都信任代理的 CA 证书：macOS 和 Linux 上分别设置 CURL_CA_BUNDLE 和 NODE_EXTRA_CA_CERTS，指向同一个 PEM 文件，文件里要包含公共根证书和代理的完整 CA 链。^[1]

装了多个版本怎么清理

多个安装并存时，版本可能对不上，行为也会出怪事。先用 which -a claude 列出 PATH 里所有的 claude，再检查 ~/.claude/local/ 这个旧版 npm 本地安装，以及全局 npm 安装。文档建议只保留原生安装。要删的话，npm 版用 npm uninstall -g @anthropic-ai/claude-code，Homebrew 版用 brew uninstall --cask claude-code，WinGet 版用 winget uninstall Anthropic.ClaudeCode。^[1]

Homebrew 如果提示 Cask 'claude-code' is unavailable: No Cask with this name exists，说明本地的 cask 索引还没更新，先运行 brew update 再安装。^[1]

Windows 上常见的安装错误

在 Windows 上，最常见的错误是复制错了安装命令。irm 在 CMD 里不被识别，应该在 PowerShell 里运行 irm https://claude.ai/install.ps1 | iex。在 CMD 里则用 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd。^[1] 注意 PowerShell 把 curl 当作 Invoke-WebRequest 的别名，所以 macOS 和 Linux 上的 curl -fsSL 写法在那里会报参数错误。^[1]

如果提示 Claude Code does not support 32-bit Windows，多半是打开了带 (x86) 后缀的 PowerShell。在该窗口里运行 [Environment]::Is64BitOperatingSystem，返回 True 的话，换成不带 x86 的 Windows PowerShell 再装一次。^[1]

Claude Code 在 Windows 上需要 Git for Windows（提供 bash）或 PowerShell 二者之一。装了 Git 却找不到时，可以在 settings.json 的 env 里设置 CLAUDE_CODE_GIT_BASH_PATH。注意文件名必须是 bash.exe、sh.exe、bash 或 sh，否则会被忽略并自动检测。^[1]

Linux 安装中途被 Killed 怎么办

安装大约需要 512 MB 可用内存，运行 Claude Code 则需要至少 4 GB 内存。安装时如果退出码是 137，通常是 Linux 的 out-of-memory 机制结束了进程。文档给的办法是加一个 2 GB 的交换文件：^[1]

sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

加完后重新运行安装命令即可。^[1]

macOS、WSL 和 CPU 相关的报错

macOS 上出现 dyld: Symbol not found 或 Abort trap: 6，多半是系统版本太旧。Claude Code 要求 macOS 13.0 或更高版本。^[1]
出现 Illegal instruction，可能是 CPU 不支持 AVX 指令集。在 Linux 虚拟机里可以用 grep -m1 -ow avx /proc/cpuinfo 检查，没有输出说明虚拟化没有把 AVX 传给客户机。文档说这种情况目前没有绕过办法。^[1]
WSL1 上出现 cannot execute binary file: Exec format error，文档建议把发行版转成 WSL2：wsl --set-version <DistroName> 2。^[1]

npm 安装后提示 native binary not installed

用 npm 安装时，原生程序是作为平台相关的可选依赖下载的。如果 postinstall 步骤或者可选依赖被跳过，运行 claude 会提示 Error: claude native binary not installed.。文档建议运行 node node_modules/@anthropic-ai/claude-code/install.cjs 补上。^[1]