🎉 欢迎使用 AI合租 文档系统！返回主站 →
文档中心
💻 Claude Code
故障排除

Claude Code 故障排除指南

全面的 Claude Code 问题诊断和解决方案，覆盖 macOS、Windows、Linux 等所有平台。

快速诊断

遇到问题时，首先运行以下命令进行基础检查：

# 检查 Claude Code 版本
claude --version
 
# 检查环境变量
echo $ANTHROPIC_BASE_URL    # Linux/macOS
echo $env:ANTHROPIC_BASE_URL  # Windows PowerShell
 
# 测试基本连接
claude "Hello"

常见问题分类

📦 安装相关问题

1. npm 权限错误

症状：EACCES: permission denied 或 npm ERR! code EACCES

macOS/Linux 解决方案
# 方法一：修复 npm 权限
sudo chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share}
 
# 方法二：配置 npm 全局目录（推荐）
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
Windows 解决方案
# 以管理员身份运行 PowerShell
npm config set prefix "$env:USERPROFILE\npm-global"
[System.Environment]::SetEnvironmentVariable("PATH", $env:PATH + ";$env:USERPROFILE\npm-global", [System.EnvironmentVariableTarget]::User)

2. Node.js 版本过低

症状：Error: Node.js version 14.x.x is not supported

所有平台解决方案
# 检查当前版本
node --version
 
# macOS - 使用 Homebrew 更新
brew upgrade node
 
# Linux - 使用 NodeSource 更新
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs
 
# Windows - 重新下载安装包
# 访问 https://nodejs.org 下载最新 LTS 版本

3. 全局包安装失败

症状：Cannot find module '@anthropic-ai/claude-code'

# 清除 npm 缓存
npm cache clean --force
 
# 重新安装
npm install -g @anthropic-ai/claude-code
 
# 验证安装
npm list -g @anthropic-ai/claude-code

🔑 环境变量问题

1. 环境变量未设置

症状：Error: ANTHROPIC_AUTH_TOKEN is not set

macOS 解决方案
# 检查当前 shell
echo $SHELL
 
# 对于 Zsh（默认）
echo 'export ANTHROPIC_BASE_URL="https://cc.aihezu.dev/api"' >> ~/.zshrc
echo 'export ANTHROPIC_AUTH_TOKEN="你的API密钥"' >> ~/.zshrc
source ~/.zshrc
 
# 对于 Bash
echo 'export ANTHROPIC_BASE_URL="https://cc.aihezu.dev/api"' >> ~/.bash_profile
echo 'export ANTHROPIC_AUTH_TOKEN="你的API密钥"' >> ~/.bash_profile
source ~/.bash_profile
Windows 解决方案
# PowerShell 永久设置
[System.Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://cc.aihezu.dev/api", [System.EnvironmentVariableTarget]::User)
[System.Environment]::SetEnvironmentVariable("ANTHROPIC_AUTH_TOKEN", "你的API密钥", [System.EnvironmentVariableTarget]::User)
 
# 重启 PowerShell 验证
echo $env:ANTHROPIC_BASE_URL
Linux 解决方案
# 添加到 .bashrc 或 .zshrc
echo 'export ANTHROPIC_BASE_URL="https://cc.aihezu.dev/api"' >> ~/.bashrc
echo 'export ANTHROPIC_AUTH_TOKEN="你的API密钥"' >> ~/.bashrc
source ~/.bashrc
 
# 系统级设置（可选）
sudo tee /etc/environment.d/claude.conf << EOF
ANTHROPIC_BASE_URL="https://cc.aihezu.dev/api"
ANTHROPIC_AUTH_TOKEN="你的API密钥"
EOF

2. 环境变量在 VS Code 中不生效

症状：VS Code 扩展无法连接，但终端中 Claude 工作正常

macOS 解决方案
# 重启 VS Code
# 或在 VS Code 集成终端中测试
echo $ANTHROPIC_BASE_URL
 
# 如果仍然不工作，在 VS Code 设置中添加：
# "terminal.integrated.env.osx": {
#   "ANTHROPIC_BASE_URL": "https://cc.aihezu.dev/api",
#   "ANTHROPIC_AUTH_TOKEN": "你的API密钥"
# }
Windows 解决方案
# 重启 VS Code
# 在 VS Code 集成终端中测试
echo $env:ANTHROPIC_BASE_URL
 
# 在 VS Code settings.json 中添加：
# "terminal.integrated.env.windows": {
#   "ANTHROPIC_BASE_URL": "https://cc.aihezu.dev/api",
#   "ANTHROPIC_AUTH_TOKEN": "你的API密钥"
# }

🌐 网络连接问题

1. 代理服务器连接失败

症状：Error: connect ECONNREFUSED 或 timeout

# 检查代理地址是否正确
curl -I $ANTHROPIC_BASE_URL
 
# 测试网络连接
ping your-proxy-domain.com
 
# 检查防火墙设置
# macOS: 系统偏好设置 → 安全性与隐私 → 防火墙
# Windows: 控制面板 → 系统和安全 → Windows Defender 防火墙
# Linux: sudo ufw status

2. SSL/TLS 证书问题

症状：Error: certificate verify failed

# 临时忽略 SSL 验证（仅用于测试）
export NODE_TLS_REJECT_UNAUTHORIZED=0
 
# 或设置 CA 证书路径
export SSL_CERT_FILE=/path/to/cacert.pem

3. 公司网络/代理问题

# 配置 HTTP 代理
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=https://proxy.company.com:8080
 
# 或使用 Claude 内置代理设置
claude config set proxy.http http://proxy.company.com:8080
claude config set proxy.https https://proxy.company.com:8080

💻 平台特定问题

macOS 特定问题

1. macOS Gatekeeper 阻止
# 如果遇到"无法验证开发者"错误
sudo spctl --master-disable  # 临时禁用
# 安装完成后重新启用
sudo spctl --master-enable
2. Homebrew 路径问题
# 确保 Homebrew 在 PATH 中
echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc  # Apple Silicon
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.zshrc     # Intel Mac
source ~/.zshrc

Windows 特定问题

1. PowerShell 执行策略
# 如果遇到执行策略错误
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
2. Windows Defender 误报
1. 打开 Windows 安全中心
2. 病毒和威胁防护 → 排除项
3. 添加 Node.js 安装目录
4. 添加 npm 全局包目录
3. 长路径支持
# 启用长路径支持
New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force

Linux 特定问题

1. WSL2 网络问题
# 检查 WSL2 网络配置
cat /etc/resolv.conf
 
# 重启 WSL2 网络
wsl --shutdown
# 然后重新启动 WSL2
2. 权限问题
# 修复配置目录权限
sudo chown -R $(whoami):$(whoami) ~/.claude
chmod 755 ~/.claude
chmod 644 ~/.claude/config.json
3. 依赖包缺失
# Ubuntu/Debian
sudo apt update
sudo apt install build-essential python3
 
# CentOS/RHEL
sudo dnf groupinstall "Development Tools"
sudo dnf install python3
 
# Arch Linux
sudo pacman -S base-devel python

🔧 VS Code 集成问题

1. 扩展无法安装

# 清除 VS Code 扩展缓存
rm -rf ~/.vscode/extensions/ms-vscode.claude-*
 
# 重新安装扩展
code --install-extension anthropic.claude-code

2. 命令面板中找不到 Claude 命令

  • 检查扩展是否已启用
  • 重新加载 VS Code 窗口（Ctrl/Cmd+Shift+P → "Developer: Reload Window"）
  • 检查 VS Code 版本是否兼容

3. 扩展无响应

# 查看 VS Code 开发者控制台
# 帮助 → 切换开发人员工具
# 检查 Console 中的错误信息

🛠️ 高级诊断

调试模式

# 启用详细日志
export DEBUG=claude:*
claude "test"
 
# 查看配置文件
claude config list
 
# 检查网络连接详情
claude debug network

日志文件位置

  • macOS: ~/Library/Logs/claude/
  • Windows: %APPDATA%\claude\logs\
  • Linux: ~/.local/share/claude/logs/

配置重置

# 备份当前配置
cp ~/.claude/config.json ~/.claude/config.json.backup
 
# 重置为默认配置
claude config reset
 
# 或完全删除配置
rm -rf ~/.claude

📞 获取更多帮助

自助诊断工具

# 运行内置诊断
claude doctor
 
# 生成诊断报告
claude debug report > claude-debug.txt

收集错误信息

当联系支持时，请提供以下信息：

  1. 系统信息

    # macOS
sw_vers
 
# Windows
systeminfo | findstr /B /C:"OS Name" /C:"OS Version"
 
# Linux
lsb_release -a

  2. Node.js 和 npm 版本

    node --version
npm --version

  3. Claude Code 版本和配置

    claude --version
claude config list

  4. 错误日志

    # 最近的错误日志
tail -n 50 ~/.local/share/claude/logs/error.log

专业技术支持

如果以上解决方案都无法解决问题，请联系我们的技术支持：

💡

提示：在联系支持前，建议先运行 claude doctor 命令进行自动诊断，这能帮助快速定位问题。

📚 相关文档

VS Code 集成卸载指南