第 12 章：问题排查与进阶技巧

恭喜你完成了前 11 章的学习！你已经掌握了使用 Claude Code 开发番茄钟应用的核心技能。本章是教程的最后一章，我们将学习如何排查问题、诊断错误，以及一些高级技巧，让你能够更高效地使用 Claude Code。

12.1 常见问题分类

在使用 Claude Code 的过程中，你可能会遇到以下几类问题：

安装问题

Node.js 版本不兼容：Claude Code 通常需要 Node.js 18 或更高版本
权限问题：无法读取或写入某些文件或目录
依赖安装失败：npm 或 yarn 安装依赖时出错

性能问题

上下文过大：项目文件过多导致响应变慢
内存不足：处理大型文件或复杂操作时卡顿
网络问题：无法连接到 Anthropic API

行为异常

Claude 不按预期操作：误解指令或执行错误操作
权限问题：工具调用被拒绝
状态不一致：会话状态与实际文件状态不符

了解这些问题的分类有助于你快速定位问题根源，选择合适的解决方法。

12.2 `/rewind` — 回滚到检查点

命令语法

/rewind [options]

功能说明

将对话和代码回滚到上一个检查点。这是 Claude Code 的"撤销"功能，当 Claude 把代码改坏了或者你走错了方向时，可以快速回到之前的状态。

别名

/undo — 与 /rewind 功能相同
/checkpoint — 查看当前检查点列表

实际使用示例

示例 1：回滚到上一个检查点

/rewind

示例 2：查看检查点列表

/checkpoint

示例 3：回滚到特定检查点

/rewind --checkpoint 3

回滚模式

/rewind 支持两种回滚模式：

仅回滚对话：对话历史回到检查点，但代码文件保持当前状态
回滚对话 + 代码：对话和代码文件都回到检查点时的状态

回滚模式可以通过选项控制：

/rewind --code-only    # 仅回滚代码
/rewind --conversation-only  # 仅回滚对话
/rewind --both         # 回滚对话和代码（默认）

使用场景

Claude 把代码改坏了，想回到修改前的状态
走错了方向，想重新开始某个任务
实验不同的实现方案，需要回滚对比

注意事项

Git 未跟踪的文件不会被回滚
已提交到 Git 的更改不会受到影响
回滚后可以继续之前的对话流程
建议在关键操作前使用 /checkpoint 创建手动检查点

12.3 `/debug` — 启用调试日志

命令语法

/debug [description]

功能说明

启用调试日志，捕获 Claude Code 的内部操作日志，帮助诊断问题。启用后，Claude Code 会记录工具调用、响应时间、错误信息等详细信息。

技能关联

systematic-debugging 技能提供了完整的调试工作流：

启用调试日志
读取并分析日志
识别问题模式
提供修复建议

实际使用示例

示例 1：中途启用调试日志

/debug

示例 2：使用描述参数

/debug timer component renders incorrectly

示例 3：分析现有日志

/debug --analyze

日志位置

调试日志保存在：

~/.claude/debug/<session-id>.txt

每个会话都有唯一的 session-id，日志文件包含该会话的完整调试信息。

启用方式

方式 1：中途启用 在对话中途运行 /debug，从该点开始捕获日志：

/debug

方式 2：启动时启用 从启动开始就捕获日志：

claude --debug

注意事项

调试日志默认关闭，以减少性能开销
启用后会略微影响性能，建议在需要时才使用
日志可能包含敏感信息，分享前请检查
可以使用可选的描述参数帮助聚焦分析

12.4 `/feedback` — 提交 Bug 报告

命令语法

/feedback [report]

功能说明

提交 Bug 报告或功能反馈给 Anthropic 团队。自动附加当前会话的上下文信息，帮助团队快速定位和解决问题。

别名

/bug — 与 /feedback 功能相同

实际使用示例

示例 1：快速反馈当前问题

/feedback

示例 2：提交详细的 Bug 报告

/feedback Claude sometimes ignores file paths when using the Read tool

示例 3：反馈功能请求

/feedback It would be great to have a command to search across all files

自动附加的信息

/feedback 会自动附加以下信息：

当前会话的对话历史
使用的 Claude Code 版本
系统环境信息（操作系统、Node.js 版本等）
最后几次工具调用的详细信息

GitHub Issues

除了使用 /feedback 命令，你也可以直接在 GitHub 提交 Issue：

https://github.com/anthropics/claude-code/issues

提交 Issue 时，请尽量包含：

问题复现步骤
预期行为
实际行为
环境信息
相关的日志或截图

注意事项

反馈前请先搜索 GitHub Issues，确认问题未被报告
提供详细的复现步骤有助于快速修复
功能请求也欢迎，帮助改进 Claude Code
Anthropic 团队会评估并回复你的反馈

12.5 `/insights` — 使用分析

命令语法

/insights

功能说明

生成 Claude Code 使用情况的分析报告，帮助你了解自己的使用习惯、交互模式和可能的摩擦点。

实际使用示例

示例 1：生成当前项目的使用分析

/insights

示例 2：分析特定时间段

/insights --last 7d

报告内容

/insights 生成的报告通常包含：

项目领域分析

你最常开发的项目类型（Web 应用、CLI 工具、库等）
主要使用的技术栈（React、Node.js、Python 等）
工作模式（前端开发、后端开发、全栈开发等）

交互模式分析

最常用的命令
工具调用频率
对话长度分布
会话持续时间

摩擦点识别

经常被拒绝的权限请求
频繁出错的操作
需要多轮对话才能完成的任务
性能瓶颈

应用场景

发现自己的使用习惯和偏好
识别可以优化的工作流程
决定哪些技能或功能值得学习
发现可能需要的权限配置

注意事项

隐私保护：分析基于本地数据，不上传到云端
报告生成需要一定时间，请耐心等待
可以定期运行 /insights 跟踪使用习惯的变化

12.6 其他诊断工具

`/heapdump` — JavaScript 堆快照

命令语法

/heapdump

功能说明 生成当前进程的 JavaScript 堆快照，用于诊断内存泄漏或内存占用过高问题。

实际使用示例

/heapdump

输出位置 快照文件会保存到桌面：

~/Desktop/heapdump-<timestamp>.heapsnapshot

注意事项

堆快照文件可能很大
需要使用 Chrome DevTools 或其他工具分析
仅在遇到内存问题时使用

`/powerup` — 交互式功能发现

命令语法

/powerup

功能说明 启动交互式学习课程，帮助你发现 Claude Code 的高级功能。课程包含动画演示和实践练习。

实际使用示例

/powerup

课程内容

命令速查
技能使用技巧
高级工作流
最佳实践

注意事项

适合新用户和想要深入学习的用户
可以随时中断和继续
建议按顺序完成课程

12.7 问题排查流程

问题排查流程图

遇到问题
    ↓
尝试 /rewind 回滚到上一个检查点
    ↓
问题解决了吗？
    ├─ 是 → 继续工作
    └─ 否 ↓
        启用 /debug 并复现问题
            ↓
        查看调试日志
            ↓
        使用 /doctor 检查环境
            ↓
        问题解决了吗？
            ├─ 是 → 继续工作
            └─ 否 ↓
                使用 /feedback 提交 Bug 报告

常见问题快速参考表

问题类型	首选命令	备选方案
Claude 改坏了代码	`/rewind`	手动 git 回滚
操作被拒绝	检查权限	使用 `/rewind` 重试
性能问题	`/debug`	`/doctor`
行为异常	`/debug`	`/rewind`
安装问题	`/doctor`	手动检查环境
内存问题	`/heapdump`	重启 Claude Code
发现 Bug	`/feedback`	GitHub Issues

12.8 动手做：排查问题

让我们通过一个实际场景来练习问题排查。假设你在开发番茄钟应用时遇到了一个 Bug。

步骤 1：模拟问题场景

让 Claude 修改番茄钟代码，但引入一个 bug：

请修改 Timer 组件，在暂停时显示 "PAUSED" 文字，但不要改变计时逻辑

假设 Claude 错误地修改了计时逻辑，导致计时器无法正确暂停。

步骤 2：使用 `/rewind` 回滚

当你发现问题后，立即使用 /rewind 回到修改前的状态：

/rewind

如果 /rewind 没有解决问题，可以尝试查看检查点列表：

/checkpoint

然后回滚到特定的检查点：

/rewind --checkpoint 2

步骤 3：启用调试日志

重新让 Claude 执行修改，并启用调试日志：

/debug timer component renders incorrectly

请修改 Timer 组件，在暂停时显示 "PAUSED" 文字，但不要改变计时逻辑

步骤 4：查看调试日志

调试日志保存在 ~/.claude/debug/ 目录下。你可以使用以下命令查看：

cat ~/.claude/debug/<session-id>.txt

或者让 Claude 帮你分析：

/debug --analyze

步骤 5：使用 `/doctor` 检查环境

确保环境配置没有问题：

/doctor

步骤 6：给 Claude 更精确的指令

根据调试信息，重新给 Claude 更精确的指令：

请修改 Timer 组件，仅在 UI 层面显示 "PAUSED" 文字，不要修改 useTimer hook 或任何状态管理逻辑。只需要在 render 中添加条件渲染的 "PAUSED" 文字。

这样 Claude 就能够更准确地理解你的需求，避免引入 bug。

12.9 课程总结

核心命令回顾

在这 12 章中，我们学习了以下核心命令：

基础命令（ch01-04）

/help — 查看帮助文档
/config — 配置 Claude Code
/model — 选择 AI 模型
/clear — 清除对话历史

文件操作（ch05-07）

/read — 读取文件
/write — 写入文件
/edit — 编辑文件
/search — 搜索代码

项目管理（ch08-09）

/git — Git 操作
/run — 运行命令
/test — 运行测试
/build — 构建项目

高级功能（ch10-12）

/skill — 使用技能
/rewind — 回滚到检查点
/debug — 启用调试日志
/feedback — 提交反馈

按场景的命令选择指南

场景 1：开始新项目

/config — 配置项目设置
/skill brainstorming — 头脑风暴设计
/skill planning-with-files — 制定计划
开始开发

场景 2：修复 Bug

/debug — 启用调试日志
复现问题
/debug --analyze — 分析日志
如果需要，/rewind 回滚
修复问题

场景 3：代码审查

/read — 读取代码
/skill code-review — 执行代码审查
/skill systematic-debugging — 深度调试
应用修复

场景 4：学习新技能

/powerup — 完成交互式课程
/insights — 分析使用习惯
尝试新的技能和工作流

继续学习的建议

在实际项目中使用：理论学习和实践相结合，在你的实际项目中应用所学知识
探索更多技能：Claude Code 有丰富的技能库，根据你的需求选择学习
参与社区：在 GitHub Issues 中讨论问题，分享你的经验
定期查看更新：Claude Code 持续更新，关注新功能和改进

本章小结

本章是教程的最后一章，我们学习了：

问题分类：了解安装、性能和行为异常三类常见问题
/rewind：使用回滚功能撤销错误操作
/debug：启用调试日志诊断问题
/feedback：提交 Bug 报告和功能反馈
/insights：分析使用习惯，优化工作流程
其他诊断工具：/heapdump 和 /powerup
问题排查流程：系统化的故障排除方法
实践练习：通过实际场景应用问题排查技巧

至此，你已经完成了完整的 Claude Code 教程。你已经掌握了：

Claude Code 的基本概念和工作原理
核心命令和工具的使用方法
如何在实际项目中集成 Claude Code
高级技巧和问题排查方法

现在，你可以自信地在自己的项目中使用 Claude Code，提高开发效率，减少重复劳动。记住，Claude Code 是你的 AI 编程助手，它的价值在于帮助你更好地完成工作，而不是替代你。

祝你在使用 Claude Code 的过程中取得更多成就！

教程结束

感谢你阅读本教程。如果你有任何问题或建议，欢迎在 GitHub Issues 中反馈： https://github.com/anthropics/claude-code/issues

12.1 常见问题分类

安装问题

性能问题

行为异常

12.2 /rewind — 回滚到检查点

命令语法

功能说明

别名

实际使用示例

回滚模式

使用场景

注意事项

12.3 /debug — 启用调试日志

命令语法

功能说明

技能关联

实际使用示例

日志位置

启用方式

注意事项

12.4 /feedback — 提交 Bug 报告

命令语法

功能说明

别名

实际使用示例

自动附加的信息

GitHub Issues

注意事项

12.5 /insights — 使用分析

命令语法

功能说明

实际使用示例

报告内容

应用场景

注意事项

12.6 其他诊断工具

/heapdump — JavaScript 堆快照

/powerup — 交互式功能发现

12.7 问题排查流程

问题排查流程图

常见问题快速参考表

12.8 动手做：排查问题

步骤 1：模拟问题场景

步骤 2：使用 /rewind 回滚

步骤 3：启用调试日志

步骤 4：查看调试日志

步骤 5：使用 /doctor 检查环境

步骤 6：给 Claude 更精确的指令

12.9 课程总结

核心命令回顾

按场景的命令选择指南

推荐的学习路径

继续学习的建议

本章小结

12.2 `/rewind` — 回滚到检查点

12.3 `/debug` — 启用调试日志

12.4 `/feedback` — 提交 Bug 报告

12.5 `/insights` — 使用分析

`/heapdump` — JavaScript 堆快照

`/powerup` — 交互式功能发现

步骤 2：使用 `/rewind` 回滚

步骤 5：使用 `/doctor` 检查环境