# 第八阶段 · 模块八 · 第三节：常见问题诊断
Claude Code 使用中会遇到哪些常见问题？如何诊断和解决这些问题？
Claude Code 全局架构
┌─────────────────────────────────────────────────────────────────────┐
│ 调试与日志 │
│ │
│ 常见问题诊断 ← 本节 │
│ ├── 连接问题 ──> 网络/服务器 │
│ ├── 认证问题 ──> API 密钥/OAuth │
│ └── 性能问题 ──> 慢/卡/超时 │
└─────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────┐
│ 连接问题 │
│ │
│ ├─ 网络不可达 ──> 检查网络/防火墙 │
│ ├─ 服务器超时 ──> 检查服务端状态 │
│ ├─ DNS 解析失败 ──> 检查 DNS 配置 │
│ └─ 连接被拒绝 ──> 检查端口/服务 │
└─────────────────────────────────────────────────────────────────────┘
# 1. 检查网络连通性
ping api.anthropic.com
# 2. 检查 DNS 解析
nslookup api.anthropic.com
# 3. 检查端口开放
curl -v https://api.anthropic.com
# 4. 查看详细错误
claude --verbose 2>&1 | grep -i error
问 1：连接超时的常见原因？
// 常见原因：
// 1. 网络问题
// - 防火墙阻止
// - 代理配置错误
// - DNS 污染
// 2. 服务端问题
// - API 服务维护
// - 限流
// - 区域不可用
// 3. 客户端问题
// - 请求超时设置过短
// - 代理配置错误
┌─────────────────────────────────────────────────────────────────────┐
│ 认证问题 │
│ │
│ ├─ API 密钥无效 ──> 检查 ANTHROPIC_API_KEY │
│ ├─ OAuth 过期 ──> 运行 claude auth refresh │
│ ├─ 权限不足 ──> 检查 API 密钥权限 │
│ └─ 地域限制 ──> 检查服务可用区 │
└─────────────────────────────────────────────────────────────────────┘
# 1. 检查环境变量
echo $ANTHROPIC_API_KEY
# 2. 验证 API 密钥
claude auth status
# 3. 刷新认证
claude auth refresh
# 4. 检查认证日志
tail -f ~/.claude/logs/errors/auth-*.log
问 1：如何修复认证过期？
# 刷新 OAuth 令牌
claude auth refresh
# 如果失败，重新登录
claude auth logout
claude auth login
┌─────────────────────────────────────────────────────────────────────┐
│ API 问题 │
│ │
│ ├─ Rate Limit ──> 等待或升级计划 │
│ ├─ Context Length ──> 使用 /compact │
│ ├─ Model Unavailable ──> 切换模型 │
│ └─ Invalid Request ──> 检查请求参数 │
└─────────────────────────────────────────────────────────────────────┘
# 查看速率限制
claude --verbose 2>&1 | grep -i "rate.*limit"
# 等待后重试
sleep 60
claude "your prompt"
问 1：遇到 Rate Limit 怎么办？
// 解决方案：
// 1. 等待
// 大多数限流有冷却时间，等待后自动恢复
// 2. 降低请求频率
// - 减少并发请求
// - 增加请求间隔
// 3. 升级计划
// 免费用户限流更严格，升级到付费计划
// 4. 使用缓存
// 避免重复请求相同内容
┌─────────────────────────────────────────────────────────────────────┐
│ 工具执行问题 │
│ │
│ ├─ 工具不存在 ──> 检查工具注册 │
│ ├─ 权限不足 ──> 运行 claude permissions │
│ ├─ 执行超时 ──> 增加超时设置 │
│ └─ 文件不存在 ──> 检查路径 │
└─────────────────────────────────────────────────────────────────────┘
# 查看工具权限
claude permissions list
# 授予权限
claude permissions allow Read
claude permissions allow Write
# 查看详细错误
claude --verbose 2>&1 | grep -i "permission"
问 1：工具执行失败的常见原因？
// 常见原因：
// 1. 权限问题
// - Read/Write 权限未授予
// - Bash 命令权限受限
// 2. 路径问题
// - 文件不存在
// - 路径错误
// - 权限不足
// 3. 参数问题
// - 缺少必需参数
// - 参数类型错误
// 4. 环境问题
// - 工作目录不存在
// - 环境变量未设置
┌─────────────────────────────────────────────────────────────────────┐
│ 性能问题 │
│ │
│ ├─ 响应慢 ──> 检查网络/查看日志 │
│ ├─ 上下文满 ──> 使用 /compact │
│ ├─ 内存高 ──> 重启 Claude Code │
│ └─ CPU 高 ──> 关闭其他程序 │
└─────────────────────────────────────────────────────────────────────┘
# 1. 检查系统资源
top -u
free -h
# 2. 查看 Claude Code 进程
ps aux | grep claude
# 3. 检查网络延迟
curl -w "@curl-format.txt" -o /dev/null -s https://api.anthropic.com
# 4. 使用 verbose 查看详细日志
claude --verbose
问 1：如何优化性能？
// 性能优化建议：
// 1. 减少上下文大小
// - 定期使用 /compact
// - 清理不必要的对话
// 2. 使用更快模型
// - Haiku 比 Opus 快
// - Sonnet 平衡速度和智能
// 3. 减少工具调用
// - 合并多个文件操作
// - 使用更精确的查询
// 4. 网络优化
// - 使用稳定的网络
// - 考虑代理配置
┌─────────────────────────────────────────────────────────────────────┐
│ MCP 问题 │
│ │
│ ├─ 连接失败 ──> 检查 MCP 服务器 │
│ ├─ 工具不可用 ──> 检查 MCP 配置 │
│ ├─ 超时 ──> 增加超时/检查服务器负载 │
│ └─ 协议错误 ──> 检查 MCP SDK 版本 │
└─────────────────────────────────────────────────────────────────────┘
# 1. 列出 MCP 服务器
claude mcp list
# 2. 测试 MCP 连接
claude mcp call <server>.<tool> --args '{}'
# 3. 查看 MCP 日志
tail -f ~/.claude/logs/mcp-*.log
# 4. 使用 --debug 查看详细信息
claude --debug
问 1：MCP 服务器无响应的常见原因？
// 常见原因：
// 1. 服务器未启动
// - 手动启动 MCP 服务器
// - 检查 systemd/systemctl 状态
// 2. 进程崩溃
// - 查看服务器日志
// - 重启服务器
// 3. 端口占用
// - 检查端口占用
// - 更换端口
// 4. 网络问题
// - 检查防火墙
// - 验证网络连通性
# 1. 查看崩溃日志
ls -la ~/.claude/logs/crashes/
# 2. 获取堆栈跟踪
tail -n 100 ~/.claude/logs/crashes/latest
# 3. 使用 --verbose 重现问题
claude --verbose
# 4. 导出日志用于报告
claude logs export --output bug-report.zip
┌─────────────────────────────────────────────────────────────────────┐
│ 崩溃原因 │
│ │
│ ├─ 内存不足 ───> 增加系统内存/关闭其他程序 │
│ ├─ 栈溢出 ───> 减少递归/增加栈大小 │
│ ├─ DLL 缺失 ──> 重新安装 Claude Code │
│ └─ 权限问题 ──> 以管理员身份运行 │
└─────────────────────────────────────────────────────────────────────┘
问 1：如何报告 Bug？
# 1. 收集日志
claude logs export --output bug-report.zip
# 2. 复现步骤
# - 描述问题
# - 提供复现命令
# - 附上日志
# 3. 提交 Issue
# - GitHub: https://github.com/anthropics/claude-code/issues
# - 附上 bug-report.zip
答案：
// 问题排查清单：
// 1. 收集信息
// - 错误消息
// - 发生时间
// - 操作步骤
// 2. 检查日志
// - Claude Code 日志
// - 系统日志
// - MCP 服务器日志
// 3. 尝试基础修复
// - 重启 Claude Code
// - 清理缓存
// - 检查网络
// 4. 升级/降级
// - 检查版本兼容性
// - 尝试最新版本
答案：
// 预防措施：
// 1. 定期更新
// - 保持 Claude Code 最新
// - 更新 MCP 服务器
// 2. 监控资源
// - 定期检查内存/CPU
// - 监控磁盘空间
// 3. 备份配置
// - 备份 ~/.claude/settings.json
// - 备份重要的 MCP 配置
// 4. 文档记录
// - 记录自定义配置
// - 记录遇到的问题和解决方案
答案：
// 寻求帮助的时机：
// 1. 错误无法解决
// - 按照文档仍无法解决
// - 错误消息不明确
// 2. 性能严重下降
// - 影响正常使用
// - 无法通过优化解决
// 3. 安全问题
// - 发现安全漏洞
// - 认证异常
// 寻求帮助的渠道：
// - GitHub Issues
// - Discord Community
// - Anthropic Support
| 资源 | 说明 |
| 故障排除指南 | https://docs.anthropic.com/claude-code/troubleshooting |
| GitHub Issues | https://github.com/anthropic/claude-code/issues |
| Discord Community | https://discord.gg/claude-code |
第九章：高级主题：
- 多模态能力
- 思维链提示
- 代码库索引
*- 第一轮：□ 事实准确性*
*- 第二轮：□ 深度与洞见*
*- 第三轮：□ 可读性与价值*