故障排除

发现 Claude Code 安装和使用中常见问题的解决方案。

安装问题

常见错误消息

错误	解决方案
command not found: claude	修复 PATH
syntax error near unexpected token '<'	安装脚本返回 HTML
curl: (56) Failure writing output to destination	先下载脚本，然后运行
Linux 上安装期间 Killed	添加交换空间
TLS connect error	更新 CA 证书
Failed to fetch version	检查网络连接
Invoke-Expression: Missing argument	使用正确的 shell

调试步骤

检查网络连接

验证可以访问 Google Cloud Storage：

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

验证 PATH

检查安装目录是否在 PATH 中：

macOS/Linux:

echo $PATH | tr ':' '\n' | grep local/bin

# 添加到 shell 配置
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Windows PowerShell:

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

检查冲突的安装

# macOS/Linux
which -a claude
ls -la ~/.local/bin/claude
npm -g ls @anthropic-ai/claude-code 2>/dev/null

# 卸载冲突安装
npm uninstall -g @anthropic-ai/claude-code
brew uninstall --cask claude-code

常见安装问题

安装脚本返回 HTML

错误：bash: line 1: syntax error near unexpected token '<'

这意味着安装 URL 返回了 HTML 页面而不是安装脚本。

解决方案：

1. 使用替代安装方法：

   # macOS/Linux
   brew install --cask claude-code
   
   # Windows
   winget install Anthropic.ClaudeCode

2. 几分钟后重试

Windows：irm 或 && 未被识别

• irm 未被识别：在 CMD 中而不是 PowerShell。打开 PowerShell 或使用 CMD 安装程序
• && 无效：在 PowerShell 中运行了 CMD 命令。使用 PowerShell 安装程序

低内存 Linux 服务器上安装被杀死

Claude Code 需要至少 4 GB 的可用 RAM。添加交换空间：

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

Windows：需要 git-bash

Windows 上的 Claude Code 需要 Git for Windows。设置路径：

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

Linux：错误的二进制变体

如果看到关于缺失共享库的错误：

# 检查 libc
ldd /bin/ls | head -1

# 如果在 glibc 上但获得了 musl 二进制文件，重新安装

身份验证问题

重复的权限提示

使用 /permissions 命令允许特定工具无需批准即可运行。

OAuth 错误：无效代码

• 按 Enter 重试，并快速完成登录
• 如果浏览器不自动打开，输入 c 复制完整 URL

登录后 403 Forbidden

• Claude Pro/Max 用户：验证订阅有效
• Console 用户：确认分配了”Claude Code”角色
• 在代理后面：检查代理设置

OAuth 登录在 WSL2 中失败

设置 BROWSER 环境变量：

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

性能和稳定性

高 CPU 或内存使用

1. 定期使用 /compact 以减少上下文大小
2. 在主要任务之间关闭并重启 Claude Code
3. 将大型构建目录添加到 .gitignore

搜索和发现问题

安装系统 ripgrep：

# macOS
brew install ripgrep

# Ubuntu/Debian
sudo apt install ripgrep

# Windows
winget install BurntSushi.ripgrep.MSVC

然后设置 USE_BUILTIN_RIPGREP=0。

IDE 集成问题

JetBrains IDE 在 WSL2 上未被检测到

选项 1：配置 Windows 防火墙

1. 找到 WSL2 IP：wsl hostname -I
2. 创建防火墙规则（管理员 PowerShell）：

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

选项 2：切换到镜像网络

在 .wslconfig 中添加：

[wsl2]
networkingMode=mirrored

JetBrains 终端中的 Escape 键

1. 转到设置 → 工具 → 终端
2. 取消选中”Move focus to the editor with Escape”

Markdown 格式问题

代码块中缺少语言标签

解决方案：

1. 要求 Claude 添加语言标签
2. 使用后处理 hooks 自动格式化
3. 在提示中明确要求 proper markdown 格式

配置文件位置

文件	目的
~/.claude/settings.json	用户设置
.claude/settings.json	项目设置
.claude/settings.local.json	本地项目设置
~/.claude.json	全局状态
.mcp.json	项目 MCP 服务器

重置配置

# 重置所有用户设置和状态
rm ~/.claude.json
rm -rf ~/.claude/

# 重置项目特定设置
rm -rf .claude/
rm .mcp.json

获取更多帮助

1. 使用 /bug 命令直接向 Anthropic 报告问题
2. 检查 GitHub 存储库了解已知问题
3. 运行 /doctor 诊断问题
4. 直接询问 Claude 关于其功能

---

本文档来自 Claude Code 官方文档