目标：能独立解决安装和使用中的常见问题
预计时间：15 分钟
对应官方文档：Troubleshoot Install、Troubleshooting、Error Reference
排错决策流程图
遇到问题时，按照以下流程逐步排查：
安装问题
问题：command not found: claude
原因： 安装路径未加入 PATH
解决：
# 检查安装位置
which claude || find ~ -name "claude" -type f 2>/dev/null
# 手动添加 PATH（根据 shell 选择）
# Bash
echo 'export PATH="$HOME/.claude/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
# Zsh
echo 'export PATH="$HOME/.claude/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
# Fish
set -U fish_user_paths $HOME/.claude/bin $fish_user_paths问题：安装脚本下载失败
原因： 网络问题或代理限制
解决：
# 使用代理
curl -fsSL -x http://proxy:port https://claude.ai/install.sh | bash
# 或手动下载后执行
curl -fsSL https://claude.ai/install.sh -o install.sh
bash install.sh问题：Windows 安装后无法启动
检查清单：
-
PowerShell 版本：需要 5.1+，推荐 7.x
$PSVersionTable.PSVersion -
执行策略：可能需要调整
Get-ExecutionPolicy # 如果是 Restricted，临时改为 RemoteSigned Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser -
Git for Windows：建议安装，提供 Bash 工具支持
登录问题
问题：浏览器无法打开
解决：
# 手动复制 URL
# 终端会显示类似：
# Please open https://claude.ai/login?device=xxx
# 手动复制到浏览器打开问题：公司网络/代理导致登录失败
# 设置代理
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080
# 或配置 Claude 使用系统代理
claude config set http_proxy http://proxy.company.com:8080问题：OAuth 回调失败
这在 Windows 或远程服务器上常见：
# 选择 "Login with code" 选项
# 浏览器会显示授权码，复制粘贴到终端
claude auth login --method oauth-code运行问题
问题：Claude 响应很慢
诊断：
> /cost # 查看 token 消耗
> /context # 查看上下文大小
解决：
- 压缩历史：
/compact - 减少上下文：
/drop不必要的文件 - 切换模型：使用更快的模型（如 Sonnet 代替 Opus）
- Fast Mode：开启快速模式
> /fast-mode on
问题：CPU/内存占用高
原因： 大型代码库导致索引和搜索消耗资源
解决：
# 排除不需要的目录
# 创建 .claudeignore 文件
echo "node_modules/" >> .claudeignore
echo ".git/" >> .claudeignore
echo "dist/" >> .claudeignore
# 限制并发
claude config set max_parallelism 2问题：Claude "卡住" 或无响应
解决：
# 按 Ctrl+C 中断当前操作
# 如果完全卡住，强制退出
killall claude
# 然后重新连接
claude --continue问题：修改了不想改的文件
解决：
# 使用 git 恢复
git checkout -- <file> # 恢复单个文件
git checkout -- . # 恢复所有文件
git reset --hard HEAD # 完全重置（慎用）
# 或使用 checkpoint
> /checkpoint list # 查看检查点
> /checkpoint restore 2 # 恢复到检查点 2常见错误码
| 错误 | 含义 | 解决 |
|---|---|---|
AUTH_ERROR | 认证失败 | 重新登录 claude auth login |
RATE_LIMIT | 请求太频繁 | 等待几秒重试，或升级套餐 |
CONTEXT_TOO_LONG | 上下文超限 | /compact 或减少文件 |
TOOL_ERROR | 工具执行失败 | 检查命令参数，或手动执行 |
NETWORK_ERROR | 网络问题 | 检查连接，或配置代理 |
完整错误码参考：Error Reference
诊断工具
/doctor 命令
> /doctor
自动检查：
- 版本是否最新
- 配置是否正确
- 权限是否正常
- 网络连接状态
/debug 命令
> /debug your-config
显示：
- 加载了哪些配置文件
- CLAUDE.md 是否生效
- Hooks 和 MCP 是否正常运行
获取帮助
> /help # 所有命令帮助
> /help <command> # 具体命令帮助，如 /help /add
更多代码示例
示例 1：批量诊断脚本——一键收集环境信息
当你需要向支持团队报告问题时，可以先运行以下脚本收集完整环境信息：
#!/bin/bash
# save as diagnose.sh
echo "=== Claude Code 诊断报告 ==="
echo "时间: $(date)"
echo ""
echo "--- 系统信息 ---"
uname -a
echo ""
echo "--- Claude 版本 ---"
claude --version 2>/dev/null || echo "claude 命令未找到"
echo ""
echo "--- Claude 路径 ---"
which claude 2>/dev/null || echo "PATH 中无 claude"
echo ""
echo "--- Node.js 版本 ---"
node --version 2>/dev/null || echo "node 未安装"
echo ""
echo "--- 网络连通性 ---"
curl -fsSL -I https://claude.ai/healthz 2>/dev/null | head -1 || echo "无法访问 claude.ai"
echo ""
echo "--- 代理设置 ---"
echo "HTTP_PROXY=$HTTP_PROXY"
echo "HTTPS_PROXY=$HTTPS_PROXY"
echo ""
echo "--- 最近会话 ---"
claude --list-sessions 2>/dev/null || echo "无法获取会话列表"运行方式：
bash diagnose.sh > claude-diagnosis.txt然后将 claude-diagnosis.txt 附在问题报告中。
示例 2：创建 .claudeignore 优化大型项目性能
对于前端大型项目，排除不需要索引的目录能显著提升性能：
# 在项目根目录创建 .claudeignore
cat > .claudeignore << 'EOF'
# 依赖目录
node_modules/
vendor/
.venv/
__pycache__/
# 构建产物
dist/
build/
*.min.js
*.min.css
# 日志与数据
*.log
logs/
tmp/
coverage/
# 二进制与媒体
*.png
*.jpg
*.gif
*.mp4
*.zip
*.tar.gz
# 版本控制元数据
.git/
EOF创建后重启 Claude Code，使用 /context 验证上下文大小是否减少。
示例 3：使用 Git 工作树隔离危险操作
在 Auto 模式下进行大规模重构前，使用 git worktree 隔离变更：
# 创建独立工作目录进行重构
git worktree add ../my-project-refactor
# 进入隔离目录并启动 Claude
cd ../my-project-refactor
claude --mode auto
# 重构完成后，如果满意，合并回原分支
cd ../my-project
git worktree list
git merge refactor-branch
# 清理工作树
git worktree remove ../my-project-refactor这样即使 Claude 在 Auto 模式下做了意外修改，也不会影响你的主工作目录。
实战场景
场景 1：排查 "Claude 响应极慢" 问题
背景：你正在一个包含 5 万行代码的 Python 项目中使用 Claude Code，突然发现每次输入后需要等待 30 秒以上才有响应。
操作步骤：
-
在 Claude Code 中先查看当前 token 消耗和上下文大小：
> /cost输出示例：
Current session cost: $2.34 Context size: ~180k tokens (limit 200k)发现上下文已接近上限！
-
查看当前加载了哪些文件：
> /context发现之前用
/add src/**/*.py加载了 200 多个文件，其中包含大量自动生成代码。 -
清理不必要的上下文：
> /drop src/generated/ > /drop src/migrations/ > /compact -
进一步排查性能，检查是否有大目录被索引：
# 在另一个终端中执行 du -sh node_modules/ .git/ venv/ 2>/dev/null发现
node_modules/占 2GB，且没有.claudeignore。 -
创建
.claudeignore：cat > .claudeignore << 'EOF' node_modules/ .git/ venv/ __pycache__/ *.pyc EOF -
重启 Claude Code，重新输入同样的问题，响应时间恢复正常（约 3-5 秒）。
预期结果：通过 /cost 和 /context 定位到上下文膨胀问题，通过 /compact 和 .claudeignore 将响应时间从 30 秒降到 3 秒。
场景 2：恢复因 Claude 误操作导致的数据丢失
背景：你在 Auto Edits 模式下让 Claude 删除 "未使用的导入"，结果它误删了一个在运行时通过 __import__ 动态加载的模块，导致应用崩溃。
操作步骤：
-
立即停止操作：如果 Claude 还在运行其他命令，按
Ctrl+C中断 -
检查当前 git 状态：
git status输出显示多个文件被修改，且尚未提交。
-
使用 Claude 的 checkpoint 恢复：
> /checkpoint list输出：
Checkpoints: 3. 重构完成后 (2 minutes ago) 2. 删除导入前 (5 minutes ago) 1. 会话开始 (15 minutes ago) -
恢复到误删导入之前的检查点：
> /checkpoint restore 2Claude 自动回滚所有文件到检查点 2 的状态。
-
验证恢复结果：
git diff --stat确认不再有误删的导入。
-
重新以更精确的方式执行：
> /mode ask > 请检查并删除未使用的导入，但保留 src/dynamic_loader.py 中所有导入， > 因为该文件在运行时会通过 __import__ 动态使用它们。这次在 Ask 模式下逐文件确认，安全完成清理。
预期结果：通过 /checkpoint restore 在 10 秒内回滚误操作，切换到 Ask 模式后以更安全的方式完成同样任务，数据零损失。
初级教程完成！
恭喜！你已经掌握了 Claude Code 的基础使用。接下来可以：
→ 进入 中级教程，学习定制和效率提升 → 或继续在日常开发中实践，熟练后再进阶
遇到本文未覆盖的问题？查阅 官方排错文档 或运行 claude /doctor