故障排除
原文：Troubleshooting
一句话
解决 Claude Code 运行中的性能、稳定性、搜索问题及其他常见故障。
什么时候翻这页
- 遇到 CPU 或内存使用过高、程序卡顿、自动压缩频繁触发等问题时
- 搜索功能无法找到文件或返回结果不完整时
- 需要排查集成终端显示乱码或命令挂起的情况
- 运行
/doctor 后发现需要进一步诊断的问题
核心概念
- 上下文窗口（context window）：Claude Code 存储和处理对话内容的内存区域，大小有限
- 自动压缩（auto-compact）：当上下文接近限制时自动清理旧内容的机制
- 抖动（thrashing）：上下文被反复填满又清空的状态，导致性能下降
- 堆转储（heapdump）：捕获内存使用快照的工具，用于分析内存问题
- 子代理（sub-agents）：在独立上下文中运行的任务，避免主上下文过载
怎么做
高 CPU 或内存使用
- 定期使用
/compact 命令减少上下文大小
- 在完成主要任务后关闭并重启 Claude Code
- 考虑将大型构建目录添加到
.gitignore 文件中
- 如果内存使用仍然很高，运行
/heapdump 生成内存快照到 ~/Desktop
自动压缩抖动错误
- 要求 Claude 分块读取大文件，而不是整个文件
- 使用带焦点的
/compact 命令，例如 /compact keep only the plan and the diff
- 将大文件工作移至子代理
- 如果早期对话不再需要，运行
/clear
命令挂起或冻结
- 按 Ctrl+C 尝试取消当前操作
- 如果无响应，关闭终端并重启
- 在同一目录运行
claude --resume 恢复会话
编辑器集成终端乱码
- 在 Claude Code 中运行
/terminal-setup 设置 terminal.integrated.gpuAcceleration 为 "off"
- 或在编辑器设置中手动设置并重新加载窗口
搜索和发现问题
- 安装系统平台的
ripgrep 包
- 设置环境变量
USE_BUILTIN_RIPGREP=0 使用系统安装的版本
WSL 搜索性能问题
- 提交更具体的搜索，指定目录或文件类型
- 如果可能，将项目移至 Linux 文件系统（
/home/）
- 考虑在 Windows 上原生运行 Claude Code 而非通过 WSL
命令 / 配置速查
| 命令 | 功能 |
|---|
/compact | 减少上下文大小 |
/heapdump | 生成内存使用快照 |
/doctor | 检查安装健康状态、设置有效性等 |
/clear | 清除早期对话内容 |
/terminal-setup | 设置终端 GPU 加速为关闭 |
/feedback | 向 Anthropic 报告问题 |
claude --resume | 恢复之前的会话 |
| 环境变量 | 功能 |
|---|
USE_BUILTIN_RIPGREP | 设置为 0 使用系统安装的 ripgrep |
初学者易错点
- 忽视定期使用
/compact 导致上下文过大，影响性能
- 在 WSL 环境中未意识到搜索性能可能受限，导致搜索结果不完整
- 遇到自动压缩抖动错误时，不知道如何有效恢复
- 误以为关闭终端会丢失对话内容，实际上会话可以恢复
- 未正确配置 ripgrep 导致搜索功能无法正常工作
相关词条
debug-your-config 调试配置问题troubleshoot-install 安装和登录问题errors 错误参考vs-code VS Code 集成问题jetbrains JetBrains 集成问题terminal-config 终端配置