hibridge.
03 Claude Code · 安装第 7 节

安装故障排查：常见错误与对应处理

一张对照表加十条详解。先在表里找到你看到的那句话，再往下翻。

约 10 分钟

用法：在下面的表里找到你屏幕上那句话，跳到对应的小节。

找不到的话，先跑一次 claude doctor——它会打印安装与配置的诊断结果，并给出建议。

对照表

你看到的 去哪一节
command not found: claude / 'claude' 不是内部或外部命令 ① 找不到 claude 这个命令
syntax error near unexpected token '<' / 满屏 HTML ② 下回来的不是安装脚本
curl: (22) ... error: 403 ② 下回来的不是安装脚本
App unavailable in region ③ 地区不受支持
'irm' is not recognized ④ Windows 上用错了命令
The token '&&' is not a valid statement separator ④ Windows 上用错了命令
A parameter cannot be found that matches parameter name 'fsSL' ④ Windows 上用错了命令
'bash' is not recognized as the name of a cmdlet ④ Windows 上用错了命令
Claude Code does not support 32-bit Windows ⑤ 开错了 PowerShell
Claude Code on Windows requires either Git for Windows ... or PowerShell ⑥ 找不到可用的命令环境
The process cannot access the file ... ⑦ Windows 安装时文件被占用
dyld: cannot load / Symbol not found / Abort trap: 6 ⑧ macOS 版本太低
cannot execute binary file: Exec format error ⑨ WSL 1 的已知问题
运行 claude 打开的是桌面应用 ⑩ 桌面应用抢了这个命令
Killed / exit code 137 ⑪ 内存不够
TLS connect error / unable to get local issuer certificate ⑫ 证书或网络问题
登录相关的报错 见登录授权、安装验证与工作目录

找不到 claude 这个命令

各系统的原话不一样，是同一件事：

系统 报错
macOS zsh: command not found: claude
Linux bash: claude: command not found
Windows CMD 'claude' is not recognized as an internal or external command
PowerShell claude : The term 'claude' is not recognized as the name of a cmdlet

意思是：程序装上了，但系统不知道去哪找它。

先试这个

关掉终端窗口，重新开一个。

安装时打开的那个窗口用的还是旧的环境设置。这一步能解决大部分情况，不要跳过。

还是不行

macOS / Linux —— 先看安装目录在不在搜索路径里：

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

有输出说明路径没问题，跳到下面的「装了两份」。没输出就加进去。

macOS（默认 Zsh）：

Terminal
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

多数 Linux（默认 Bash）：

Terminal
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Windows PowerShell ——

PowerShell
$env:PATH -split ';' | Select-String '\.local\\bin'

没输出就加：

PowerShell
$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

加完必须重开终端。

装了两份

多个版本同时存在会导致奇怪的表现。查一下：

Terminal
which -a claude

Windows 上是 where.exe claude。

如果找到多份，只留一个，推荐留官方安装脚本装的那个（macOS / Linux 在 ~/.local/bin/claude，Windows 在 %USERPROFILE%\.local\bin\claude.exe）。

清掉多余的：

Terminal
npm uninstall -g @anthropic-ai/claude-code   # npm 全局装的
rm -rf ~/.claude/local                        # 旧版本留下的
brew uninstall --cask claude-code             # Homebrew 装的

下回来的不是安装脚本

报错长这样：

bash: line 1: syntax error near unexpected token `<'
bash: line 1: `<!DOCTYPE html>'

PowerShell 上表现为一堆解析错误，报错文本里夹着 HTML 标签或 CSS。也可能是干净的一句：

curl: (22) The requested URL returned error: 403

含义都一样：那个地址返回的是一个网页或一个错误状态，不是安装脚本。

分两种情况

如果网页里写着 App unavailable in region —— 跳到③ 地区不受支持。

如果是干净的 403 —— 可能是网络里有东西拦住了 downloads.claude.ai。先自查连通性：

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

Windows PowerShell 上要写 curl.exe（PowerShell 里的 curl 是另一个东西，不认这些参数）。

第一行出现 200 就说明能通。

处理

  1. 换一种安装方式。macOS 用 brew install --cask claude-code，Windows 用 winget install Anthropic.ClaudeCode。但注意这两条走的是同一批服务器，如果是网络拦截，换了也一样。
  2. 过几分钟重试。这类问题经常是临时的。

地区不受支持

看到 App unavailable in region，含义是 Claude Code 在你所在的地区不提供服务。完整名单见 Anthropic 支持的国家。

这属于你自己的网络环境，我们不提供也不建议任何相关方案。

Windows 上用错了命令

四条报错，一个原因：你复制的是给另一个窗口用的命令。

报错 你实际在哪 该用哪条
'irm' is not recognized CMD CMD 那条，或改开 PowerShell
The token '&&' is not a valid statement separator PowerShell PowerShell 那条
A parameter cannot be found that matches parameter name 'fsSL' PowerShell（你用了 macOS 的命令） PowerShell 那条
'bash' is not recognized as the name of a cmdlet Windows（你用了 macOS 的命令） PowerShell 那条

PowerShell：

PowerShell
irm https://claude.ai/install.ps1 | iex

CMD：

CMD
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

怎么分辨自己在哪：看行首有没有 PS。有是 PowerShell，没有是 CMD。

开错了 PowerShell

Claude Code does not support 32-bit Windows

多数情况下你的电脑没问题，是你打开了开始菜单里带 (x86) 的那一项。

在报错的那个窗口里确认：

PowerShell
[Environment]::Is64BitOperatingSystem
  • True —— 系统没问题。关掉这个窗口，改开不带 (x86) 的 Windows PowerShell，重装。
  • False —— 你的 Windows 确实是 32 位的。Claude Code 需要 64 位系统。

找不到可用的命令环境

Claude Code on Windows requires either Git for Windows (for bash) or PowerShell

这句话的意思不是「必须装 Git」，是「Git Bash 和 PowerShell 一个都没找到」。

处理办法二选一：

① 把 PowerShell 加回搜索路径。 它的默认位置是 C:\Windows\System32\WindowsPowerShell\v1.0\。

② 装 Git for Windows（git-scm.com/downloads/win），安装时选上「Add to PATH」，装完重开终端。

如果 Git 已经装了但它找不到，在 settings.json 里指路：

JSON
{
  "env": {
    "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
  }
}

一个容易踩空的细节：这个路径必须指向名叫 bash.exe、sh.exe、bash 或 sh 的文件。指向 Git for Windows 那个 git-bash.exe 启动器不算——它会被忽略，而且不报错，表现得像你根本没设过。

Windows 安装时文件被占用

Failed to download binary: The process cannot access the file ... because it is being used by another process

原因通常是上一次安装还在跑，或者杀毒软件正在扫描那个下载到一半的文件。

关掉其他正在跑安装的 PowerShell 窗口，等杀毒扫完，然后：

PowerShell
Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\downloads"
irm https://claude.ai/install.ps1 | iex

macOS 版本太低

dyld: cannot load ...
dyld: Symbol not found: _ubrk_clone
Abort trap: 6

Claude Code 需要 macOS 13.0 或更高。

看自己的版本：苹果菜单 → 关于本机。

换安装方式解决不了这个问题。 Homebrew 下载的是同一个程序。只能升级系统。

WSL 1 的已知问题

cannot execute binary file: Exec format error

这是 WSL 1 上一个已知的兼容问题。

最干净的办法是转成 WSL 2，在 PowerShell 里：

PowerShell
wsl --set-version <你的发行版名> 2

必须留在 WSL 1 的话，在 WSL 里的 ~/.bashrc 末尾加上这段，然后 source ~/.bashrc：

Terminal
claude() {
  /lib64/ld-linux-x86-64.so.2 "$(readlink -f "$HOME/.local/bin/claude")" "$@"
}

桌面应用抢了这个命令

运行 claude，打开的却是桌面应用。

原因是旧版本的 Claude 桌面应用注册了一个同名程序，优先级比命令行版高。

处理：把桌面应用升级到最新版。

内存不够

Linux 上安装时出现 Killed，或者：

Installation was killed before it could finish (exit code 137).
This usually means the system ran out of memory.

安装大约需要 512 MB 空闲内存，运行需要更多。

三条路：关掉别的程序腾内存；加交换空间；换配置更高的机器。官方的最低要求是 4 GB 内存。

证书或网络问题

TLS connect error
unable to get local issuer certificate
Could not create SSL/TLS secure channel

较老的 Windows 10 上常见，可以先执行这一句再重装：

PowerShell
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
irm https://claude.ai/install.ps1 | iex

其他情况通常是系统的根证书太旧，或者你在一个需要走代理的网络里。代理的设置办法见环境相关问题：编码、路径与网络。

都不管用的时候

按顺序：

  1. claude doctor —— 它会给出针对你这台机器的具体建议
  2. 官方仓库的 issue 列表 —— 搜一下你的报错原文
  3. 能进会话的话，用 /feedback 反馈
  4. 如果问题在账号而不在安装（登录循环、订阅识别不出来），走官方支持：在 claude.ai 登录后点左下角头像 → Get help

如果你的订阅是从我们这里买的，第 4 类问题可以直接把订单号发给我们，我们能看到那一单的状态。但安装和环境问题不在我们的服务范围内——上面这些是官方文档的内容，我们只是把它整理成了中文。

本节事实查证日期：2026-08-05。 全部依据官方 Troubleshoot installation and login 与 Terminal guide。报错原文可能随版本变化。

← 回到手册目录