故障排查

Claude Code 安装和使用中遇到问题，本文提供从错误现象直达解决方案的速查表，以及逐步排查安装问题的详细流程：验证 PATH、检查网络和代理、确认二进制兼容性、处理冲突安装。覆盖 macOS、Linux、Windows（含 WSL）的主要错误场景，包括 command not found、TLS 证书错误、Git Bash 要求、musl/glibc 不匹配、OAuth 认证失败等。

安装问题速查

看到的错误	解决方案
`command not found: claude` 或 `'claude' is not recognized`	修复 PATH
`syntax error near unexpected token '<'`	安装脚本返回 HTML
`curl: (56) Failure writing output`	先下载脚本再运行
`Killed`（Linux 上安装时）	添加 swap 空间
TLS/SSL 连接错误或 `unable to get local issuer certificate`	更新 CA 证书
`Failed to fetch version` 或无法访问下载服务器	检查网络和代理
`irm is not recognized` 或 `&& is not valid`	使用正确的 shell 命令
`'bash' is not recognized as the name of a cmdlet`	使用 Windows 安装命令
`Claude Code on Windows requires git-bash`	安装或配置 Git Bash
`Claude Code does not support 32-bit Windows`	打开正确的 PowerShell
`Error loading shared library`	错误的二进制版本（musl/glibc）
`Illegal instruction` on Linux	架构不匹配
`dyld: cannot load` 或 `Abort trap` on macOS	二进制不兼容
`Invoke-Expression: Missing argument in parameter list`	安装脚本返回 HTML
`App unavailable in region`	Claude Code 在您所在地区不可用，查看支持地区
`OAuth error` 或 `403 Forbidden`	修复认证问题

排查安装问题

检查网络连通性

安装包从 storage.googleapis.com 下载。先验证能否访问：

bash

curl -sI https://storage.googleapis.com

如果失败，可能原因：

企业防火墙或代理拦截了 Google Cloud Storage
地区网络限制：尝试 VPN 或其他网络
TLS/SSL 问题：更新系统 CA 证书

如果在企业代理后面，安装前设置代理环境变量：

bash

export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
curl -fsSL https://claude.ai/install.sh | bash

验证 PATH 设置

安装成功但运行 claude 报找不到命令，说明安装目录不在 PATH 中。

安装位置：

macOS/Linux：~/.local/bin/claude
Windows：%USERPROFILE%\.local\bin\claude.exe

macOS/Linux 修复：

bash

# Zsh（macOS 默认）
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Bash（Linux 默认）
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Windows PowerShell 修复：

powershell

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

重开终端后运行 claude --version 验证。

具体问题解决

`command not found` 安装后找不到命令

zsh: command not found: claude
bash: claude: command not found
'claude' is not recognized as an internal or external command

参见上面的验证 PATH 设置。

安装脚本返回 HTML

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

PowerShell 里表现为：Invoke-Expression: Missing argument in parameter list.

说明安装 URL 返回了 HTML 页面而不是脚本。如果页面显示"App unavailable in region"，说明你所在地区不支持 Claude Code。

解决方案：

bash

# macOS/Linux 用 Homebrew
brew install --cask claude-code

# Windows 用 WinGet
winget install Anthropic.ClaudeCode

或者等几分钟后重试。

`curl: (56)` 写入错误

连接中断导致脚本下载失败。

解决方案：

测试网络连通性：curl -fsSL https://storage.googleapis.com -o /dev/null
使用 Homebrew 或 WinGet 替代安装方式

内存不足被强制终止

bash: line 142: 34803 Killed    "$binary_path" install ...

Linux 系统内存不足，OOM killer 杀掉了进程。需要至少 4GB 可用内存。

添加 swap 空间：

bash

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

# 然后重新安装
curl -fsSL https://claude.ai/install.sh | bash

TLS 或 SSL 连接错误

curl: (35) TLS connect error
SSL/TLS secure channel could not be established
unable to get local issuer certificate

解决方案：

bash

# Ubuntu/Debian 更新 CA 证书
sudo apt-get update && sudo apt-get install ca-certificates

# macOS
brew install ca-certificates

企业代理 TLS 检查导致的问题，设置企业 CA 证书：

bash

export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem

Windows: `irm` 或 `&&` 命令无法识别

irm 无法识别：你在 CMD 里，不是 PowerShell。打开 PowerShell 或者用 CMD 安装命令：
batch
```
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
```
&& 无效：你在 PowerShell 里却用了 CMD 命令。用 PowerShell 安装命令：
powershell
```
irm https://claude.ai/install.ps1 | iex
```

Windows: 需要 Git Bash

安装并运行 Git for Windows，安装时选择"Add to PATH"。

如果已安装但仍报错，在 settings.json 中指定路径：

json

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

Linux: 库文件缺失

Error loading shared library libstdc++.so.6: No such file or directory

可能安装了错误的二进制版本（musl vs glibc）。

检查系统类型：

bash

ldd /bin/ls | head -1

Alpine Linux 安装缺失的包：

bash

apk add libgcc libstdc++ ripgrep

认证问题

反复提示权限确认

运行 /permissions 将常用命令加入白名单，避免每次都要确认。详见权限配置。

认证失败或 OAuth 错误

运行 /logout 完全退出
关闭 Claude Code
重新运行 claude 完成认证

如果浏览器没有自动打开，按 c 复制 OAuth URL，手动粘贴到浏览器。

OAuth error: Invalid code

登录码过期或被截断。按 Enter 重试，要在浏览器打开后快速完成操作。

403 Forbidden

Claude Pro/Max 用户：在 claude.ai/settings 确认订阅有效
Console 用户：确认账户有"Claude Code"或"Developer"角色
企业代理：代理可能干扰 API 请求，参见网络配置

"This organization has been disabled"

环境变量 ANTHROPIC_API_KEY 覆盖了你的订阅认证。取消设置：

bash

unset ANTHROPIC_API_KEY
claude

同时检查 ~/.zshrc、~/.bashrc 或 ~/.profile 中的 export ANTHROPIC_API_KEY=... 行，删除它。

WSL 相关问题

WSL2 中 JetBrains IDE 检测不到

配置 Windows 防火墙（推荐）：

找到 WSL2 IP：wsl hostname -I

以管理员身份打开 PowerShell 创建防火墙规则：

powershell

New-NetFirewallRule -DisplayName "Allow WSL2 Internal Traffic" -Direction Inbound -Protocol TCP -Action Allow -RemoteAddress 172.21.0.0/16 -LocalAddress 172.21.0.0/16

根据实际 IP 调整范围。

重启 IDE 和 Claude Code

切换到镜像网络模式（可选）：

在 Windows 用户目录的 .wslconfig 中添加：

ini

[wsl2]
networkingMode=mirrored

然后运行 wsl --shutdown 重启。

WSL2 中 OAuth 登录失败

浏览器无法在 WSL 中打开。设置浏览器路径：

bash

export BROWSER="/mnt/c/Program Files/Google/Chrome/Application/chrome.exe"
claude

或者按 c 复制登录 URL，手动在 Windows 浏览器打开。

WSL 中搜索结果缓慢或不完整

跨文件系统工作时会有磁盘读取性能损耗，导致搜索结果减少。

解决方案：

搜索更具体：指定目录或文件类型
移项目到 Linux 文件系统：/home/ 目录下而不是 /mnt/c/
用原生 Windows：性能更好

性能问题

CPU 或内存占用高

定期运行 /compact 减小上下文大小
任务之间关闭并重启 Claude Code
在 .gitignore 中添加大型构建目录

搜索和 `@文件` 不工作

安装系统 ripgrep：

bash

# macOS
brew install ripgrep

# Windows
winget install BurntSushi.ripgrep.MSVC

# Ubuntu/Debian
sudo apt install ripgrep

# Alpine Linux
apk add ripgrep

然后设置环境变量 USE_BUILTIN_RIPGREP=0。

配置文件位置

文件	用途
`~/.claude/settings.json`	用户设置（权限、hooks、模型覆盖）
`.claude/settings.json`	项目设置（提交到 git）
`.claude/settings.local.json`	本地项目设置（不提交）
`~/.claude.json`	全局状态（主题、OAuth、MCP 服务器）
`.mcp.json`	项目 MCP 服务器（提交到 git）

重置配置（会删除所有设置和会话历史）：

bash

rm ~/.claude.json
rm -rf ~/.claude/
rm -rf .claude/
rm .mcp.json

获取更多帮助

在 Claude Code 内：运行 /feedback 直接向 Anthropic 报告问题
运行诊断：/doctor 检查安装状态、配置文件、MCP 服务器、插件错误等
GitHub Issues：在 github.com/anthropics/claude-code 查看已知问题
直接问 Claude：Claude 有访问自己文档的能力，可以回答关于功能和配置的问题

安装或运行时出现蓝屏（BSOD）

在 Windows 系统上安装或运行 Claude Code 时遭遇蓝屏死机（Blue Screen of Death, BSOD），这是一个严重的系统级错误。虽然 Claude Code 本身通常不会直接导致系统不稳定，但其安装过程或运行时可能与特定的系统驱动、安全软件或虚拟化环境发生冲突。

常见原因与紧急处理

记录错误代码：蓝屏画面会显示一个错误代码（例如 SYSTEM_SERVICE_EXCEPTION, IRQL_NOT_LESS_OR_EQUAL, KMODE_EXCEPTION_NOT_HANDLED）。这是诊断问题的关键信息。
进入安全模式：重启计算机，在 Windows 启动时强制关机再开机（重复2-3次），进入“自动修复”界面，选择“高级选项” -> “启动设置” -> 重启，然后按 F4 或 5 进入带网络连接的安全模式。

针对性排查步骤

1. 禁用冲突软件（最可能的原因）

安全软件：第三方杀毒软件、防火墙或“系统优化”工具可能将 Claude Code 的安装行为误判为威胁。在安全模式下，暂时禁用或卸载这些软件，然后重试安装。
虚拟机/容器软件：Hyper-V、VMware Workstation、VirtualBox、Docker Desktop 等可能与安装进程冲突。尝试暂时关闭这些服务或软件。

2. 更新系统驱动

过时或不兼容的驱动程序是蓝屏的常见诱因。重点更新：

显卡驱动：前往 NVIDIA、AMD 或 Intel 官网下载最新版驱动。
芯片组驱动：从电脑制造商（如 Dell、HP、Lenovo）官网或主板官网下载。
存储驱动（如 Intel RST、AMD RAID）。

3. 检查 Windows 功能与更新

运行系统文件检查器：在安全模式下的命令提示符（管理员）中运行 sfc /scannow。
检查磁盘错误：运行 chkdsk C: /f（根据系统盘符调整）。
安装所有 Windows 更新：确保系统已更新至最新版本，特别是 .NET Framework 和 Visual C++ 运行库。

4. WSL2 相关蓝屏处理

如果在使用 WSL2 时遇到蓝屏：

更新 WSL2 内核：在 PowerShell（管理员）中运行 wsl --update。
调整 .wslconfig：在用户目录（C:\Users\<你的用户名>）创建或修改 .wslconfig 文件，尝试使用镜像网络模式：
ini
```
[wsl2]
networkingMode=mirrored
```
修改后运行 wsl --shutdown 重启 WSL。
关闭 Hyper-V：如果不需要，可以在“控制面板”->“程序”->“启用或关闭 Windows 功能”中取消勾选“Hyper-V”，但这会禁用 WSL2。

5. 使用替代安装方法

如果通过 install.ps1 脚本安装反复引发问题，尝试：

使用 Winget（推荐）：在 PowerShell（管理员）中运行 winget install Anthropic.ClaudeCode。
手动下载安装：从官方渠道获取离线安装包进行安装。

如果问题依旧

如果上述步骤均无法解决，建议：

查看 Windows 事件查看器（eventvwr.msc）中“系统”日志在蓝屏时间点附近的错误事件。
在安全模式下使用 claude /doctor 命令运行诊断，查看是否有环境配置错误。
考虑在全新的用户账户下尝试安装，以排除用户配置文件损坏的可能。
如果蓝屏频繁发生，可能需要备份数据后执行系统重置或全新安装 Windows。

重要提示：蓝屏问题可能涉及深层系统冲突。在进行任何重大系统更改前，请务必创建系统还原点或备份重要数据。

常见问题

Q: Claude code 安装导致蓝屏怎么办？

首先尝试以管理员身份运行安装程序，并暂时禁用第三方杀毒软件。如果是在虚拟机或使用 WSL2，请检查虚拟化功能是否开启且驱动为最新。更新显卡和芯片组驱动也可能解决兼容性问题。

Q: 安装 Claude Code 时电脑蓝屏了如何修复？

记录蓝屏错误代码（如 IRQL_NOT_LESS_OR_EQUAL）。进入安全模式，卸载最近安装的可能冲突软件，或使用系统还原点。确保系统已安装所有 Windows 更新。

Q: Claude Code 蓝屏问题常见原因有哪些？

常见原因包括：1) 安全软件（如某些杀毒软件）过度拦截；2) 虚拟机平台（Hyper-V、VMware）与 Claude Code 安装进程冲突；3) 系统驱动（尤其是显卡、存储驱动）过旧；4) 系统文件损坏。

Q: WSL2 下安装 Claude Code 会引起蓝屏吗？

有可能。如果 WSL2 与 Windows 主机网络或文件系统交互时驱动不稳定，可能引发系统错误。尝试更新 WSL2 内核至最新版，或在 .wslconfig 中设置 networkingMode=mirrored 以使用更稳定的网络模式。

Q: 如何避免 Claude Code 安装时的蓝屏风险？

安装前创建系统还原点。关闭所有非必要后台程序，特别是安全软件和虚拟机。确保 Windows 为最新版本，并提前更新主板和显卡驱动。优先使用 winget 或离线安装包进行安装。

故障排查 ​

安装问题速查 ​

排查安装问题 ​

检查网络连通性 ​

验证 PATH 设置 ​

具体问题解决 ​

command not found 安装后找不到命令 ​

安装脚本返回 HTML ​

curl: (56) 写入错误 ​

内存不足被强制终止 ​

TLS 或 SSL 连接错误 ​

Windows: irm 或 && 命令无法识别 ​

Windows: 需要 Git Bash ​

Linux: 库文件缺失 ​

认证问题 ​

反复提示权限确认 ​

认证失败或 OAuth 错误 ​

403 Forbidden ​

"This organization has been disabled" ​

WSL 相关问题 ​

WSL2 中 JetBrains IDE 检测不到 ​

WSL2 中 OAuth 登录失败 ​

WSL 中搜索结果缓慢或不完整 ​

性能问题 ​

CPU 或内存占用高 ​

搜索和 @文件 不工作 ​

配置文件位置 ​

获取更多帮助 ​

安装或运行时出现蓝屏（BSOD） ​

常见原因与紧急处理 ​

针对性排查步骤 ​

1. 禁用冲突软件（最可能的原因） ​

2. 更新系统驱动 ​

3. 检查 Windows 功能与更新 ​

4. WSL2 相关蓝屏处理 ​

5. 使用替代安装方法 ​

如果问题依旧 ​

常见问题 ​

故障排查

安装问题速查

排查安装问题

检查网络连通性

验证 PATH 设置

具体问题解决

`command not found` 安装后找不到命令

安装脚本返回 HTML

`curl: (56)` 写入错误

内存不足被强制终止

TLS 或 SSL 连接错误

Windows: `irm` 或 `&&` 命令无法识别

Windows: 需要 Git Bash

Linux: 库文件缺失

认证问题

反复提示权限确认

认证失败或 OAuth 错误

403 Forbidden

"This organization has been disabled"

WSL 相关问题

WSL2 中 JetBrains IDE 检测不到

WSL2 中 OAuth 登录失败

WSL 中搜索结果缓慢或不完整

性能问题

CPU 或内存占用高

搜索和 `@文件` 不工作

配置文件位置

获取更多帮助

安装或运行时出现蓝屏（BSOD）

常见原因与紧急处理

针对性排查步骤

1. 禁用冲突软件（最可能的原因）

2. 更新系统驱动

3. 检查 Windows 功能与更新

4. WSL2 相关蓝屏处理

5. 使用替代安装方法

如果问题依旧

常见问题