{/* TRANSLATED — 已翻译为中文 */}

> ## 文档索引
> 在此获取完整文档索引：https://code.claude.com/docs/llms.txt
> 使用此文件发现所有可用页面，然后再进一步探索。

# 安装和登录故障排除

> 修复安装或登录 Claude Code 时的命令未找到、PATH、权限、网络和认证错误。

如果安装失败或你无法登录，在下方查找你的错误。对于 Claude Code 运行后的运行时问题，参见[故障排除](/en/troubleshooting)。对于配置问题如设置未生效或钩子未触发，参见[调试你的配置](/en/debug-your-config)。

## 查找你的错误

将你看到的错误消息或症状与修复方法匹配：

| 你看到的内容                                                                                    | 解决方案                                                                                                                |
| :--------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------- |
| `command not found: claude` 或 `'claude' is not recognized`                                    | [修复你的 PATH](#command-not-found-claude-after-installation)                                                           |
| `syntax error near unexpected token '<'`                                                       | [安装脚本返回 HTML](#install-script-returns-html-instead-of-a-shell-script)                                             |
| `curl: (22) The requested URL returned error: 403`                                             | [安装脚本返回 403](#install-script-returns-html-instead-of-a-shell-script)                                              |
| `curl: (23)` 或 `curl: (56) Failure writing output to destination`                             | [检查连接或使用替代安装器](#curl-56-failure-writing-output-to-destination)                                               |
| Linux 安装期间 `Killed`                                                                         | [为低内存服务器添加交换空间](#install-killed-on-low-memory-linux-servers)                                                |
| `TLS connect error` 或 `SSL/TLS secure channel`                                                | [更新 CA 证书](#tls-or-ssl-connection-errors)                                                                           |
| `Failed to fetch version` 或无法访问下载服务器                                                   | [检查网络和代理设置](#check-network-connectivity)                                                                        |
| `irm is not recognized` 或 `&& is not valid`                                                   | [为你的 shell 使用正确的命令](#wrong-install-command-on-windows)                                                         |
| `'bash' is not recognized as the name of a cmdlet`                                             | [使用 Windows 安装器命令](#wrong-install-command-on-windows)                                                             |
| `Claude Code on Windows requires either Git for Windows (for bash) or PowerShell`              | [安装 shell](#claude-code-on-windows-requires-either-git-for-windows-for-bash-or-powershell)                            |
| `Claude Code does not support 32-bit Windows`                                                  | [打开 Windows PowerShell，而不是 x86 条目](#claude-code-does-not-support-32-bit-windows)                                 |
| `The process cannot access the file ... because it is being used by another process`           | [清除下载文件夹并重试](#the-process-cannot-access-the-file-during-windows-install)                                       |
| `Error loading shared library`                                                                 | [系统使用了错误的二进制变体](#linux-musl-or-glibc-binary-mismatch)                                                       |
| `Illegal instruction`                                                                          | [架构或 CPU 指令集不匹配](#illegal-instruction)                                                                          |
| WSL 中 `cannot execute binary file: Exec format error`                                         | [WSL1 原生二进制回归](#exec-format-error-on-wsl1)                                                                       |
| PowerShell 安装器完成但未找到 `claude` 或显示旧版本                                              | [重启终端并验证 PATH](#verify-your-path)                                                                                |
| macOS 上 `dyld: cannot load`、`dyld: Symbol not found` 或 `Abort trap`                         | [二进制不兼容](#dyld-cannot-load-on-macos)                                                                              |
| `Invoke-Expression: Missing argument in parameter list`                                        | [安装脚本返回 HTML](#install-script-returns-html-instead-of-a-shell-script)                                             |
| `App unavailable in region`                                                                    | Claude Code 在你的国家/地区不可用。参见[支持的国家/地区](https://www.anthropic.com/supported-countries)。                 |
| `unable to get local issuer certificate`                                                       | [配置企业 CA 证书](#tls-or-ssl-connection-errors)                                                                       |
| `OAuth error` 或 `403 Forbidden`                                                               | [修复认证](#login-and-authentication)                                                                                   |
| `Could not load the default credentials` 或 `Could not load credentials from any providers`    | [Bedrock、Vertex 或 Foundry 凭证](#bedrock-vertex-or-foundry-credentials-not-loading)                                    |
| `ChainedTokenCredential authentication failed` 或 `CredentialUnavailableError`                 | [Bedrock、Vertex 或 Foundry 凭证](#bedrock-vertex-or-foundry-credentials-not-loading)                                    |
| `API Error: 500`、`529 Overloaded`、`429` 或其他未列出的 4xx 和 5xx 错误                          | 参见[错误参考](/en/errors)                                                                                               |

如果你的问题未列出，请进行下面的诊断检查以缩小原因范围。

<Tip>
  如果你想完全跳过终端，[Claude Code 桌面应用](/en/desktop-quickstart)让你通过图形界面安装和使用 Claude Code。为 [macOS](https://claude.ai/api/desktop/darwin/universal/dmg/latest/redirect?utm_source=claude_code\&utm_medium=docs) 或 [Windows](https://claude.com/download?utm_source=claude_code\&utm_medium=docs) 下载，无需任何命令行设置即可开始编码。
</Tip>

## 运行诊断检查

### 检查网络连接

安装器从 `downloads.claude.ai` 下载。验证你可以访问它：

```bash theme={null}
curl -sI https://downloads.claude.ai/claude-code-releases/latest
```

`HTTP/2 200` 行意味着你已到达服务器。如果没有输出、`Could not resolve host` 或连接超时，你的网络正在阻止连接。常见原因：

* 企业防火墙或代理阻止 `downloads.claude.ai`
* 区域网络限制：尝试 VPN 或替代网络
* TLS/SSL 问题：更新系统的 CA 证书，或检查是否配置了 `HTTPS_PROXY`

如果你在企业代理后面，在安装前将 `HTTPS_PROXY` 和 `HTTP_PROXY` 设置为代理地址。如果不知道代理 URL，询问你的 IT 团队，或检查浏览器的代理设置。

此示例设置两个代理变量，然后通过代理运行安装器：

<Tabs>
  <Tab title="macOS/Linux">
    ```bash theme={null}
    export HTTP_PROXY=http://proxy.example.com:8080
    export HTTPS_PROXY=http://proxy.example.com:8080
    curl -fsSL https://claude.ai/install.sh | bash
    ```
  </Tab>

  <Tab title="Windows PowerShell">
    ```powershell theme={null}
    $env:HTTP_PROXY = 'http://proxy.example.com:8080'
    $env:HTTPS_PROXY = 'http://proxy.example.com:8080'
    irm https://claude.ai/install.ps1 | iex
    ```
  </Tab>
</Tabs>

### 验证你的 PATH

如果安装成功但运行 `claude` 时出现 `command not found` 或 `not recognized` 错误，说明安装目录不在你的 PATH 中。你的 shell 在 PATH 中列出的目录中搜索程序，安装器将 `claude` 放在 macOS/Linux 上的 `~/.local/bin/claude` 或 Windows 上的 `%USERPROFILE%\.local\bin\claude.exe`。

通过列出你的 PATH 条目并过滤 `local/bin` 来检查安装目录是否在你的 PATH 中：

<Tabs>
  <Tab title="macOS/Linux">
    ```bash theme={null}
    echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin"
    ```

    如果打印出 `/Users/you/.local/bin` 或 `/home/you/.local/bin`，说明目录在你的 PATH 中，可以跳到[检查冲突的安装](#check-for-conflicting-installations)。如果没有输出，将其添加到你的 shell 配置中。

    对于 macOS 上默认的 Zsh：

    ```bash theme={null}
    echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
    source ~/.zshrc
    ```

    对于大多数 Linux 发行版上默认的 Bash：

    ```bash theme={null}
    echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
    source ~/.bashrc
    ```

    或者，关闭并重新打开你的终端。

    对于其他 shell 如 fish 或 Nushell，使用 shell 自己的配置语法将 `~/.local/bin` 添加到你的 PATH，然后重启终端。

    验证修复是否生效：

    ```bash theme={null}
    claude --version
    ```
  </Tab>

  <Tab title="Windows PowerShell">
    ```powershell theme={null}
    $env:PATH -split ';' | Select-String '\.local\\bin'
    ```

    如果没有输出，将安装目录添加到你的用户 PATH：

    ```powershell theme={null}
    $currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
    [Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')
    ```

    重启终端以使更改生效。

    验证修复是否生效：

    ```powershell theme={null}
    claude --version
    ```
  </Tab>

  <Tab title="Windows CMD">
    ```batch theme={null}
    echo %PATH% | findstr /i "local\bin"
    ```

    如果没有输出，打开系统设置，转到环境变量，将 `%USERPROFILE%\.local\bin` 添加到你的用户 PATH 变量。重启终端。

    验证修复是否生效：

    ```batch theme={null}
    claude --version
    ```
  </Tab>
</Tabs>

### 检查冲突的安装

多个 Claude Code 安装可能导致版本不匹配或意外行为。检查已安装的内容：

<Tabs>
  <Tab title="macOS/Linux">
    列出在你的 PATH 中找到的所有 `claude` 二进制文件：

    ```bash theme={null}
    which -a claude
    ```

    如果没有打印任何内容，说明你的 PATH 中还没有 `claude`。回到[验证你的 PATH](#verify-your-path)。

    检查 `claude` 二进制文件可能来自的三个位置。`~/.local/bin/claude` 是原生安装器，`~/.claude/local/` 是旧版本 Claude Code 创建的遗留本地 npm 安装，npm 全局列表显示 `-g` 安装：

    ```bash theme={null}
    ls -la ~/.local/bin/claude
    ```

    ```bash theme={null}
    ls -la ~/.claude/local/
    ```

    ```bash theme={null}
    npm -g ls @anthropic-ai/claude-code 2>/dev/null
    ```
  </Tab>

  <Tab title="Windows PowerShell">
    列出在你的 PATH 中找到的所有 `claude` 二进制文件：

    ```powershell theme={null}
    where.exe claude
    ```

    检查原生安装器是否放置了二进制文件：

    ```powershell theme={null}
    Test-Path "$env:USERPROFILE\.local\bin\claude.exe"
    ```
  </Tab>
</Tabs>

如果发现多个安装，只保留一个。推荐 macOS/Linux 上的 `~/.local/bin/claude` 或 Windows 上的 `%USERPROFILE%\.local\bin\claude.exe` 原生安装。移除多余的：

卸载 npm 全局安装：

```bash theme={null}
npm uninstall -g @anthropic-ai/claude-code
```

移除遗留的本地 npm 安装：

```bash theme={null}
rm -rf ~/.claude/local
```

在 Windows 上，使用 PowerShell：

```powershell theme={null}
Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\local"
```

移除 macOS 上的 Homebrew 安装。如果你安装了 `claude-code@latest` cask，替换该名称：

```bash theme={null}
brew uninstall --cask claude-code
```

移除 Windows 上的 WinGet 安装：

```powershell theme={null}
winget uninstall Anthropic.ClaudeCode
```

### 检查目录权限

安装器需要对 macOS 和 Linux 上的 `~/.local/bin/` 和 `~/.claude/` 的写入权限。在 Windows 上，安装位置在 `%USERPROFILE%` 下，该目录默认可被你的用户写入，因此此部分很少适用。

检查目录是否可写：

```bash theme={null}
test -w ~/.local/bin && echo "writable" || echo "not writable"
test -w ~/.claude && echo "writable" || echo "not writable"
```

如果任一目录不可写，创建安装目录并将你的用户设为所有者：

```bash theme={null}
sudo mkdir -p ~/.local/bin
sudo chown -R $(whoami) ~/.local
```

### 验证二进制文件是否工作

如果 `claude --version` 打印版本但 `claude` 在启动时崩溃或挂起，运行这些检查以缩小原因范围。如果 `claude --version` 显示命令未找到，先去[验证你的 PATH](#verify-your-path)；下面的命令假设 `claude` 在你的 PATH 中。

确认二进制文件存在且可执行：

```bash theme={null}
ls -la "$(command -v claude)"
```

在 Windows 上，使用 PowerShell：

```powershell theme={null}
Get-Command claude | Select-Object Source
```

在 Linux 上，检查缺失的共享库。如果 `ldd` 显示缺失的库，你可能需要安装系统包。在 Alpine Linux 和其他基于 musl 的发行版上，参见 [Alpine Linux 设置](/en/setup#alpine-linux-and-musl-based-distributions)。

```bash theme={null}
ldd "$(command -v claude)" | grep "not found"
```

确认二进制文件可以执行：

```bash theme={null}
claude --version
```

## 常见安装问题

这些是最常遇到的安装问题及其解决方案。

### 安装脚本返回 HTML 而不是 shell 脚本

运行安装命令时，你可能会看到以下错误之一：

```text theme={null}
bash: line 1: syntax error near unexpected token `<'
bash: line 1: `<!DOCTYPE html>'
```

在 PowerShell 上，同样的问题表现为：

```text theme={null}
Invoke-Expression: Missing argument in parameter list.
```

根据请求的路由方式，你可能会看到没有 HTML 正文的 403：

```text theme={null}
curl: (22) The requested URL returned error: 403
```

这些都意味着安装 URL 返回了 HTML 页面或错误状态而不是安装脚本。如果 HTML 页面显示"App unavailable in region"，说明 Claude Code 在你的国家/地区不可用。参见[支持的国家/地区](https://www.anthropic.com/supported-countries)。

没有正文的裸 403 通常有相同的原因，但也可能来自企业代理或防火墙阻止下载。如果你在支持的国家/地区仍然看到 403，在尝试下面的替代安装器之前先进行[检查网络连接](#check-network-connectivity)，因为那些访问相同的主机。

否则，这可能是由于网络问题、区域路由或临时服务中断。

**解决方案：**

1. **使用替代安装方法**：

   在 macOS 上，通过 Homebrew 安装：

   ```bash theme={null}
   brew install --cask claude-code
   ```

   在 Windows 上，通过 WinGet 安装：

   ```powershell theme={null}
   winget install Anthropic.ClaudeCode
   ```

2. **几分钟后重试**：问题通常是临时的。等待并再次尝试原始命令。

### 安装后 `command not found: claude`

安装完成但 `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` |

这意味着安装目录不在你的 shell 搜索路径中。参见[验证你的 PATH](#verify-your-path) 了解各平台的修复方法。

### `curl: (56) Failure writing output to destination`

`curl ... | bash` 命令下载脚本并将其管道传输到 Bash 执行。此错误以及相关的 `curl: (23) Failure writing output to destination` 意味着 Bash 没有接收到完整的脚本。退出代码 56 表示下载本身被中断，退出代码 23 表示 curl 无法将其接收到的内容写入管道，通常是因为 Bash 提前退出。

**解决方案：**

1. **检查网络稳定性**：Claude Code 二进制文件托管在 `downloads.claude.ai`。测试你是否可以访问它：
   ```bash theme={null}
   curl -sI https://downloads.claude.ai/claude-code-releases/latest
   ```
   `HTTP/2 200` 行意味着你已到达服务器，原始故障可能是间歇性的；重试安装命令。如果看到 `Could not resolve host` 或连接超时，说明你的网络正在阻止下载。

2. **尝试替代安装方法**：

   在 macOS 上：

   ```bash theme={null}
   brew install --cask claude-code
   ```

   在 Windows 上：

   ```powershell theme={null}
   winget install Anthropic.ClaudeCode
   ```

### TLS 或 SSL 连接错误

类似 `curl: (35) TLS connect error`、`schannel: next InitializeSecurityContext failed` 或 PowerShell 的 `Could not establish trust relationship for the SSL/TLS secure channel` 的错误表示 TLS 握手失败。

**解决方案：**

1. **更新系统 CA 证书**：

   在 Ubuntu/Debian 上：

   ```bash theme={null}
   sudo apt-get update && sudo apt-get install ca-certificates
   ```

   在 macOS 上，系统 curl 使用钥匙串信任存储；更新 macOS 本身会更新根证书。

2. **在 Windows 上，在运行安装器之前启用 TLS 1.2**：
   ```powershell theme={null}
   [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
   irm https://claude.ai/install.ps1 | iex
   ```

3. **检查代理或防火墙干扰**：执行 TLS 检查的企业代理可能导致这些错误，包括 `unable to get local issuer certificate` 和 `SELF_SIGNED_CERT_IN_CHAIN`。对于安装步骤，使用 `--cacert` 将 curl 指向你的企业 CA 包：
   ```bash theme={null}
   curl --cacert /path/to/corporate-ca.pem -fsSL https://claude.ai/install.sh | bash
   ```
   对于安装后的 Claude Code 本身，设置 `NODE_EXTRA_CA_CERTS` 使 API 请求信任相同的包：
   ```bash theme={null}
   export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem
   ```
   如果没有证书文件，请向你的 IT 团队索取。你也可以尝试直接连接以确认代理是原因。

4. **在 Windows 上，绕过证书吊销检查**（如果看到 `CRYPT_E_NO_REVOCATION_CHECK (0x80092012)` 或 `CRYPT_E_REVOCATION_OFFLINE (0x80092013)`）。这些意味着 curl 到达了服务器但你的网络阻止了证书吊销查找，这在企业防火墙后面很常见。在安装命令中添加 `--ssl-revoke-best-effort`：
   ```batch theme={null}
   curl --ssl-revoke-best-effort -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
   ```
   或者，使用 `winget install Anthropic.ClaudeCode` 安装，完全避免 curl。

### `Failed to fetch version from downloads.claude.ai`

安装器无法访问下载服务器。这通常意味着 `downloads.claude.ai` 在你的网络上被阻止。

**解决方案：**

1. **直接测试连接**：
   ```bash theme={null}
   curl -sI https://downloads.claude.ai/claude-code-releases/latest
   ```

2. **如果在代理后面**，设置 `HTTPS_PROXY` 以便安装器可以通过它路由。参见[代理配置](/en/network-config#proxy-configuration)了解详情。
   ```bash theme={null}
   export HTTPS_PROXY=http://proxy.example.com:8080
   curl -fsSL https://claude.ai/install.sh | bash
   ```

3. **如果在受限网络上**，尝试不同的网络或 VPN，或使用替代安装方法：

   在 macOS 上：

   ```bash theme={null}
   brew install --cask claude-code
   ```

   在 Windows 上：

   ```powershell theme={null}
   winget install Anthropic.ClaudeCode
   ```

### Windows 上的错误安装命令

如果看到 `'irm' is not recognized`、`The token '&&' is not valid` 或 `'bash' is not recognized as the name of a cmdlet`，说明你复制了适用于不同 shell 或操作系统的安装命令。

* **`irm` 未识别**：你在 CMD 中，而不是 PowerShell。你有两个选项：

  在开始菜单中搜索"PowerShell"打开 PowerShell，然后运行原始安装命令：

  ```powershell theme={null}
  irm https://claude.ai/install.ps1 | iex
  ```

  或者留在 CMD 中使用 CMD 安装器：

  ```batch theme={null}
  curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
  ```

* **`&&` 无效**：你在 PowerShell 中但运行了 CMD 安装器命令。使用 PowerShell 安装器：
  ```powershell theme={null}
  irm https://claude.ai/install.ps1 | iex
  ```

* **`bash` 未识别**：你在 Windows 上运行了 macOS/Linux 安装器。改用 PowerShell 安装器：
  ```powershell theme={null}
  irm https://claude.ai/install.ps1 | iex
  ```

### Windows 安装期间 `The process cannot access the file`

如果 PowerShell 安装器报错 `Failed to download binary: The process cannot access the file ... because it is being used by another process`，说明安装器无法写入 `%USERPROFILE%\.claude\downloads`。这通常意味着之前的安装尝试仍在运行，或者杀毒软件正在扫描该文件夹中部分下载的二进制文件。

关闭任何运行安装器的其他 PowerShell 窗口，等待杀毒扫描释放文件。然后删除下载文件夹并重新运行安装器：

```powershell theme={null}
Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\downloads"
irm https://claude.ai/install.ps1 | iex
```

### 低内存 Linux 服务器上安装被终止

如果在 VPS 或云实例上安装时看到 `Killed`：

```text theme={null}
Setting up Claude Code...
Installing Claude Code native build latest...
bash: line 142: 34803 Killed    "$binary_path" install ${TARGET:+"$TARGET"}
```

Linux OOM killer 终止了进程，因为系统内存不足。Claude Code 至少需要 4 GB 可用 RAM。

**解决方案：**

1. **添加交换空间**（如果你的服务器 RAM 有限）。交换空间使用磁盘空间作为溢出内存，即使物理 RAM 较低也能完成安装。

   创建 2 GB 交换文件并启用它：

   ```bash theme={null}
   sudo fallocate -l 2G /swapfile
   sudo chmod 600 /swapfile
   sudo mkswap /swapfile
   sudo swapon /swapfile
   ```

   然后重试安装：

   ```bash theme={null}
   curl -fsSL https://claude.ai/install.sh | bash
   ```

2. **关闭其他进程**以在安装前释放内存。

3. **使用更大的实例**（如果可能）。Claude Code 至少需要 4 GB RAM。

### Docker 中安装挂起

在 Docker 容器中安装 Claude Code 时，以 root 身份安装到 `/` 可能导致挂起。

**解决方案：**

1. **在运行安装器之前设置工作目录**。从 `/` 运行时，安装器会扫描整个文件系统，导致过多的内存使用。设置 `WORKDIR` 将扫描限制在小目录中：
   ```dockerfile theme={null}
   WORKDIR /tmp
   RUN curl -fsSL https://claude.ai/install.sh | bash
   ```

2. **增加 Docker 内存限制**（如果使用 Docker Desktop）：
   ```bash theme={null}
   docker build --memory=4g .
   ```

### Claude Desktop 在 Windows 上覆盖 `claude` 命令

如果你安装了旧版本的 Claude Desktop，它可能在 `WindowsApps` 目录中注册了一个 `Claude.exe`，该文件在 PATH 优先级上高于 Claude Code CLI。运行 `claude` 会打开桌面应用而不是 CLI。

更新 Claude Desktop 到最新版本以修复此问题。

### Windows 上的 Claude Code 需要 Git for Windows（用于 bash）或 PowerShell

Git for Windows 是可选的。当 Git Bash 缺失时，Claude Code 使用 [PowerShell 工具](/en/tools-reference#powershell-tool)，因此此错误意味着两个 shell 都未找到。

**如果 PowerShell 不在你的 PATH 中**，其默认位置是 `C:\Windows\System32\WindowsPowerShell\v1.0\`。将该目录添加到你的 `PATH`，或安装提供 `pwsh` 的 [PowerShell 7](https://aka.ms/powershell)。

**要安装 Git for Windows**，从 [git-scm.com/downloads/win](https://git-scm.com/downloads/win) 下载。安装期间选择"Add to PATH"。安装后重启终端。安装它可以启用 Bash 工具，在使用基于 Bash 的脚本和工具时很有用。

**如果 Git 已安装**但 Claude Code 找不到它，在你的 [settings.json 文件](/en/settings)中设置路径：

```json theme={null}
{
  "env": {
    "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
  }
}
```

如果你的 Git 安装在其他位置，通过在 PowerShell 中运行 `where.exe git` 找到路径，并使用该目录中的 `bin\bash.exe` 路径。

### Claude Code 不支持 32 位 Windows

Windows 在开始菜单中有两个 PowerShell 条目：`Windows PowerShell` 和 `Windows PowerShell (x86)`。x86 条目以 32 位进程运行，即使在 64 位机器上也会触发此错误。要检查你的情况，在产生错误的同一窗口中运行：

```powershell theme={null}
[Environment]::Is64BitOperatingSystem
```

如果打印 `True`，你的操作系统没问题。关闭窗口，打开不带 x86 后缀的 `Windows PowerShell`，然后再次运行安装命令。

如果打印 `False`，你使用的是 32 位版本的 Windows。Claude Code 需要 64 位操作系统。参见[系统要求](/en/setup#system-requirements)。

### Linux musl 或 glibc 二进制不匹配

如果安装后看到关于缺失共享库如 `libstdc++.so.6` 或 `libgcc_s.so.1` 的错误，安装器可能下载了错误的系统二进制变体。

```text theme={null}
Error loading shared library libstdc++.so.6: No such file or directory
```

这可能发生在安装了 musl 交叉编译包的基于 glibc 的系统上，导致安装器错误地将系统检测为 musl。

**解决方案：**

1. **检查你的系统使用哪个 libc**：
   ```bash theme={null}
   ldd --version 2>&1 | head -1
   ```
   输出提到 `GNU libc` 或 `GLIBC` 表示 glibc。输出提到 `musl` 表示 musl。

2. **如果你在 glibc 上但得到了 musl 二进制文件**，移除安装并重新安装。你也可以使用 `https://downloads.claude.ai/claude-code-releases/{VERSION}/manifest.json` 处的清单手动下载正确的二进制文件。提交 [GitHub issue](https://github.com/anthropics/claude-code/issues)，附上 `ldd --version` 和 `ls /lib/libc.musl*` 的输出。

3. **如果你实际上在 musl 上**，如 Alpine Linux，安装所需的包：
   ```bash theme={null}
   apk add libgcc libstdc++ ripgrep
   ```

### `Illegal instruction`

如果运行 `claude` 或安装器打印 `Illegal instruction`，说明原生二进制文件使用了你的处理器不支持的 CPU 指令。有两种不同的原因。

**架构不匹配。** 安装器下载了错误的二进制文件，例如在 ARM 服务器上的 x86。在 macOS 或 Linux 上使用 `uname -m`，或在 PowerShell 中使用 `$env:PROCESSOR_ARCHITECTURE` 检查。如果结果与你收到的二进制文件不匹配，[提交 GitHub issue](https://github.com/anthropics/claude-code/issues)并附上输出。

**缺失 AVX 指令集。** 如果你的架构正确但仍然看到 `Illegal instruction`，你的 CPU 可能缺少 AVX 或二进制文件需要的其他指令。这影响大约 2013 年之前的 Intel 和 AMD 处理器，以及虚拟机管理程序不向客户机传递 AVX 的虚拟机。

在 VPS 或 VM 上，运行 `grep -m1 -ow avx /proc/cpuinfo`；空结果意味着 AVX 对客户机不可用。

没有原生二进制文件的解决方法；跟踪 [issue #50384](https://github.com/anthropics/claude-code/issues/50384) 了解状态，报告时在 Linux 上附上 `grep -m1 "model name" /proc/cpuinfo` 或在 macOS 上附上 `sysctl -n machdep.cpu.brand_string` 的 CPU 型号。

替代安装方法下载相同的原生二进制文件，无法解决任一原因。

### macOS 上 `dyld: cannot load`

如果在安装期间看到 `dyld: cannot load`、`dyld: Symbol not found` 或 `Abort trap: 6`，说明二进制文件与你的 macOS 版本或硬件不兼容。

```text theme={null}
dyld: cannot load 'claude-2.1.42-darwin-x64' (load command 0x80000034 is unknown)
Abort trap: 6
```

引用 `libicucore` 的 `Symbol not found` 错误也表明你的 macOS 版本早于二进制文件支持的版本：

```text theme={null}
dyld: Symbol not found: _ubrk_clone
  Referenced from: claude-darwin-x64 (which was built for Mac OS X 13.0)
  Expected in: /usr/lib/libicucore.A.dylib
```

**解决方案：**

1. **检查你的 macOS 版本**：Claude Code 需要 macOS 13.0 或更高版本。打开 Apple 菜单并选择"关于本机"检查你的版本。

2. **更新 macOS**（如果你使用的是旧版本）。二进制文件使用了旧版 macOS 不支持的加载命令和系统库。Homebrew 等替代安装方法下载相同的二进制文件，无法解决此错误。

### WSL1 上 `Exec format error`

如果在 WSL 中运行 `claude` 打印 `cannot execute binary file: Exec format error`，你在 WSL1 上遇到了 [issue #38788](https://github.com/anthropics/claude-code/issues/38788) 跟踪的已知原生二进制回归。二进制文件的程序头以 WSL1 加载器无法处理的方式更改了。

最干净的修复方法是从 PowerShell 将你的发行版转换为 WSL2：

```powershell theme={null}
wsl --set-version <DistroName> 2
```

如果你需要留在 WSL1 上，通过动态链接器调用二进制文件。将此函数添加到 WSL 内的 `~/.bashrc`，如果你的主目录不同则替换路径：

```bash theme={null}
claude() {
  /lib64/ld-linux-x86-64.so.2 "$(readlink -f "$HOME/.local/bin/claude")" "$@"
}
```

然后运行 `source ~/.bashrc` 并重试 `claude`。

### WSL 中的 npm 安装错误

如果你在 WSL 内使用 `npm install -g` 安装了 Claude Code，这些问题适用。如果你使用了[原生安装器](/en/setup)，跳过此部分。

**OS 或平台检测问题。** 如果 npm 在安装期间报告平台不匹配，WSL 可能正在使用 Windows 的 `npm`。先运行 `npm config set os linux`，然后使用 `npm install -g @anthropic-ai/claude-code --force` 安装。不要使用 `sudo`。

**运行 `claude` 时 `exec: node: not found`。** 你的 WSL 环境可能正在使用 Windows 的 Node.js 安装。使用 `which npm` 和 `which node` 确认：以 `/mnt/c/` 开头的路径是 Windows 二进制文件，而 Linux 路径以 `/usr/` 开头。要修复此问题，通过 Linux 发行版的包管理器或通过 [`nvm`](https://github.com/nvm-sh/nvm) 安装 Node。

**nvm 版本冲突。** 如果你在 WSL 和 Windows 中都安装了 nvm，在 WSL 中切换 Node 版本可能会失败，因为 WSL 默认导入 Windows PATH 且 Windows nvm 优先。最常见的原因是 nvm 未在你的 shell 中加载。将 nvm 加载器添加到 `~/.bashrc` 或 `~/.zshrc`：

```bash theme={null}
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"
```

或在当前会话中加载它：

```bash theme={null}
source ~/.nvm/nvm.sh
```

如果 nvm 已加载但 Windows 路径仍优先，显式前置你的 Linux Node 路径：

```bash theme={null}
export PATH="$HOME/.nvm/versions/node/$(node -v)/bin:$PATH"
```

<Warning>
  避免通过 `appendWindowsPath = false` 禁用 Windows PATH 导入，因为这会破坏从 WSL 调用 Windows 可执行文件的能力。同样，如果你将 Node.js 用于 Windows 开发，避免从 Windows 卸载它。
</Warning>

### 安装期间的权限错误

如果原生安装器因权限错误失败，目标目录可能不可写。参见[检查目录权限](#check-directory-permissions)。

如果你之前使用 npm 安装并遇到 npm 特定的权限错误，切换到原生安装器：

```bash theme={null}
curl -fsSL https://claude.ai/install.sh | bash
```

### npm 安装后找不到原生二进制文件

`@anthropic-ai/claude-code` npm 包通过每平台可选依赖（如 `@anthropic-ai/claude-code-darwin-arm64`）引入原生二进制文件。如果安装后运行 `claude` 打印 `Could not find native binary package "@anthropic-ai/claude-code-<platform>"`，检查以下原因：

* **可选依赖被禁用。** 从你的 npm install 命令中移除 `--omit=optional`，从 pnpm 中移除 `--no-optional`，从 yarn 中移除 `--ignore-optional`，并检查 `.npmrc` 未设置 `optional=false`。然后重新安装。原生二进制文件仅作为可选依赖提供，因此如果被跳过则没有 JavaScript 回退。
* **不支持的平台。** 预构建的二进制文件为 `darwin-arm64`、`darwin-x64`、`linux-x64`、`linux-arm64`、`linux-x64-musl`、`linux-arm64-musl`、`win32-x64` 和 `win32-arm64` 发布。Claude Code 不为其他平台提供二进制文件；参见[系统要求](/en/setup#system-requirements)。
* **企业 npm 镜像缺少平台包。** 确保你的注册表除了元包外还镜像了所有八个 `@anthropic-ai/claude-code-*` 平台包。

使用 `--ignore-scripts` 安装不会触发此错误。将二进制文件链接到位的 postinstall 步骤被跳过，因此 Claude Code 回退到每次启动时定位和生成平台二进制文件的包装器。这可以工作但启动更慢；启用脚本重新安装以直接执行。

## 登录和认证

这些部分涉及登录失败、OAuth 错误和令牌问题。

### 重置你的登录

当登录失败且原因不明显时，干净的重新认证可以解决大多数情况：

1. 运行 `/logout` 完全登出
2. 关闭 Claude Code
3. 使用 `claude` 重启并重新完成认证过程

如果登录期间浏览器没有自动打开，按 `c` 将 OAuth URL 复制到剪贴板，然后手动粘贴到浏览器中。当 URL 在窄终端或 SSH 终端中跨行包装且无法直接点击时，这也适用。

### OAuth error: Invalid code

如果看到 `OAuth error: Invalid code. Please make sure the full code was copied`，说明登录代码已过期或在复制粘贴时被截断。

**解决方案：**

* 按 Enter 重试并在浏览器打开后快速完成登录
* 如果浏览器没有自动打开，输入 `c` 复制完整 URL
* 如果使用远程/SSH 会话，浏览器可能在错误的机器上打开。复制终端中显示的 URL 并在本地浏览器中打开。

### 登录后 403 Forbidden

如果登录后看到 `API Error: 403 {"error":{"type":"forbidden","message":"Request not allowed"}}`：

* **Claude Pro/Max 用户**：在 [claude.ai/settings](https://claude.ai/settings) 验证你的订阅是否有效
* **Anthropic Console 用户**：确认你的账户具有"Claude Code"或"Developer"角色。管理员在 Anthropic Console 的 Settings → Members 中分配此角色。
* **在代理后面**：企业代理可能干扰 API 请求。参见[网络配置](/en/network-config)了解代理设置。

### 此组织已被禁用（有活跃订阅）

如果你有活跃的 Claude 订阅但仍看到 `API Error: 400 ... "This organization has been disabled"`，说明 `ANTHROPIC_API_KEY` 环境变量覆盖了你的订阅。这通常发生在旧雇主或项目的旧 API 密钥仍在你的 shell 配置文件中设置时。

当 `ANTHROPIC_API_KEY` 存在且你已批准时，Claude Code 使用该密钥而不是你订阅的 OAuth 凭证。在带 `-p` 标志的非交互模式下，密钥在存在时始终使用。参见[认证优先级](/en/authentication#authentication-precedence)了解完整的解析顺序。

要改用你的订阅，取消设置环境变量并从你的 shell 配置文件中移除它：

```bash theme={null}
unset ANTHROPIC_API_KEY
claude
```

检查 `~/.zshrc`、`~/.bashrc` 或 `~/.profile` 中的 `export ANTHROPIC_API_KEY=...` 行并移除它们以使更改永久生效。在 Windows 上，检查你的 PowerShell 配置文件 `$PROFILE` 和用户环境变量中的 `ANTHROPIC_API_KEY`。在 Claude Code 内运行 `/status` 以确认哪个认证方法处于活跃状态。

### WSL2、SSH 或容器中的 OAuth 登录失败

当 Claude Code 在 WSL2 中、通过 SSH 在远程机器上或在容器内运行时，浏览器通常在不同的主机上打开，其重定向无法到达 Claude Code 的本地回调服务器。登录后，浏览器显示登录代码而不是自动重定向回来。在终端的 `Paste code here if prompted` 提示处粘贴该代码以完成登录。

如果浏览器根本没有从 WSL2 打开，将 `BROWSER` 环境变量设置为你的 Windows 浏览器路径：

```bash theme={null}
export BROWSER="/mnt/c/Program Files/Google/Chrome/Application/chrome.exe"
claude
```

或者，在交互式登录提示处按 `c` 复制 OAuth URL，或复制 `claude auth login` 打印的 URL，并在本地机器上的浏览器中打开。

如果将代码粘贴到交互式提示中没有效果，你的终端的粘贴绑定可能没有到达输入字段。尝试终端的替代粘贴快捷键，通常是 Windows Terminal 中的右键单击或 Shift+Insert，或改用 `claude auth login`，它从标准输入读取粘贴的代码：

```bash theme={null}
claude auth login
```

此回退也适用于原生 Windows 或任何粘贴到交互式提示失败的终端。

### 未登录或令牌过期

如果 Claude Code 在会话后提示你重新登录，你的 OAuth 令牌可能已过期。

运行 `/login` 重新认证。如果这经常发生，检查你的系统时钟是否准确，因为令牌验证依赖于正确的时间戳。

在 macOS 上，登录也可能在钥匙串被锁定或其密码与你的账户密码不同步时失败，这阻止 Claude Code 保存凭证。运行 `claude doctor` 检查钥匙串访问。要手动解锁钥匙串，运行 `security unlock-keychain ~/Library/Keychains/login.keychain-db`。如果解锁没有帮助，打开钥匙串访问，选择 `login` 钥匙串，然后选择 Edit > Change Password for Keychain "login" 以与你的账户密码重新同步。

### Bedrock、Vertex 或 Foundry 凭证未加载

如果你配置 Claude Code 使用云提供商并在 Bedrock 上看到 `Could not load credentials from any providers`，在 Vertex 上看到 `Could not load the default credentials`，或在 Foundry 上看到 `ChainedTokenCredential authentication failed`，说明你的云提供商 CLI 可能在当前 shell 中未认证。

对于 Bedrock，确认你的 AWS 凭证有效：

```bash theme={null}
aws sts get-caller-identity
```

对于 Vertex AI，确认 `ANTHROPIC_VERTEX_PROJECT_ID` 和 `CLOUD_ML_REGION` 在你的 shell 中已设置，然后设置应用默认凭证：

```bash theme={null}
gcloud auth application-default login
```

对于 Microsoft Foundry，确认 `ANTHROPIC_FOUNDRY_API_KEY` 已设置，或使用 Azure CLI 登录以便默认凭证链可以找到你的账户：

```bash theme={null}
az login
```

如果凭证在你的终端中有效但在 VS Code 或 JetBrains 扩展中无效，IDE 进程可能没有继承你的 shell 环境。在 IDE 自己的设置中设置提供商环境变量，或从已导出它们的终端启动 IDE。

参见 [Amazon Bedrock](/en/amazon-bedrock)、[Google Vertex AI](/en/google-vertex-ai) 或 [Microsoft Foundry](/en/microsoft-foundry) 了解完整的提供商设置。

## 仍然卡住

如果以上都没有解决你的问题：

1. 检查 [GitHub 仓库](https://github.com/anthropics/claude-code/issues)了解已知问题，或提交新 issue 附上你的操作系统、运行的安装命令和完整的错误输出
2. 如果 `claude --version` 有效但其他地方有问题，运行 `claude doctor` 获取自动诊断报告
3. 如果你可以启动会话，在 Claude Code 内使用 `/feedback` 报告问题