第三节：Bug 修复实战
六步调试法与调试工具

作者：小学子 📚 | 日期：2026年4月2日 | 第十阶段 · 模块十

---

# 第十阶段 · 模块十 · 第三节：Bug 修复实战

核心问题

如何使用 Claude Code 高效修复 Bug？调试流程是什么？如何快速定位问题根源？

---

◇ 本节位置

        Claude Code 全局架构
        
        ┌─────────────────────────────────────────────────────────────────────┐
        │  实战案例                                                            │
        │                                                                      │
        │  Bug 修复实战 ← 本节                                             │
        │  ├── 问题分析                                                        │
        │  ├── 调试流程                                                        │
        │  └── 修复验证                                                        │
        └─────────────────────────────────────────────────────────────────────┘
        

---

一、Bug 修复概述

1.1 Bug 修复 vs 重构

        ┌─────────────────────────────────────────────────────────────────────┐
        │  Bug 修复：改变行为，修复错误                                        │
        │  重构：改善结构，不改变行为                                          │
        └─────────────────────────────────────────────────────────────────────┘
        

1.2 Claude Code 的调试能力

源码位置：`src/utils/debug.ts`

        // Claude Code 的调试功能：
        
        // 1. 调试模式
        isDebugMode()
        // - --debug 标志
        // - 环境变量 DEBUG
        
        // 2. 调试日志
        logForDebugging()
        // - 详细的调试信息
        // - 可过滤
        
        // 3. 错误追踪
        // - 堆栈跟踪
        // - 错误分类
        

1.3 五问分析

问 1：修复 Bug 的第一步是什么？

        // 修复 Bug 的第一步：
        
        // 1. 复现问题
        // - 确认 Bug 存在
        // - 了解触发条件
        
        // 2. 收集信息
        // - 错误消息
        // - 触发步骤
        // - 环境信息
        
        // 3. 定位根源
        // - 分析代码
        // - 使用调试工具
        

---

二、问题分析方法

2.1 提问法

        // Claude 会问的问题：
        
        // 1. 期望行为是什么？
        // - 你希望发生什么？
        // - 实际发生了什么？
        
        // 2. 如何复现？
        // - 具体的步骤是什么？
        // - 什么条件下触发？
        
        // 3. 环境信息
        // - 操作系统
        // - Node/Python 版本
        // - 相关配置
        

2.2 日志分析法

源码位置：`src/utils/debug.ts`

        // Claude Code 的日志级别：
        
        const LEVEL_ORDER = {
          verbose: 0,  // 最详细
          debug: 1,
          info: 2,
          warn: 3,
          error: 4,    // 最少
        }
        
        // 设置日志级别
        CLAUDE_CODE_DEBUG_LOG_LEVEL=verbose
        

2.3 五问分析

问 1：如何获取详细的调试信息？

        // 方法：
        
        // 1. 启用调试模式
        claude --debug
        
        // 2. 设置日志级别
        CLAUDE_CODE_DEBUG_LOG_LEVEL=verbose
        
        // 3. 查看调试日志
        tail -f ~/.claude/debug/latest
        

---

三、调试流程

3.1 六步调试法

        ┌─────────────────────────────────────────────────────────────────────┐
        │  1. 复现：确认 Bug 存在                                              │
        │  2. 定位：找到问题代码                                                │
        │  3. 分析：理解问题根源                                                │
        │  4. 修复：实施解决方案                                                │
        │  5. 验证：确认 Bug 已修复                                            │
        │  6. 回归：确保没有引入新问题                                          │
        └─────────────────────────────────────────────────────────────────────┘
        

3.2 Claude 的调试策略

        // Claude 使用的调试策略：
        
        // 1. 二分查找
        // - 如果 Bug 在第 1000 行
        // - 先检查第 500 行
        // - 确定 Bug 在前半部分还是后半部分
        
        // 2. 假设验证
        // - 提出可能的假设
        // - 设计测试验证
        // - 排除不正确的假设
        
        // 3. 对比分析
        // - 对比正常和异常行为
        // - 找出差异点
        

3.3 五问分析

问 1：如何快速定位 Bug？

        // 快速定位的方法：
        
        // 1. 使用日志
        // - 添加 console.log
        // - 查看变量值
        
        // 2. 使用断点
        // - 设置断点
        // - 单步执行
        
        // 3. 缩小范围
        // - 删除一半代码
        // - 确定 Bug 在哪半
        

---

四、常见 Bug 类型

4.1 类型错误

        // 问题：
        // TypeError: Cannot read property 'x' of undefined
        
        // 原因：
        // - 访问了 undefined 的属性
        // - 对象可能为 null
        
        // 修复：
        // ❌ 不好
        const name = user.profile.name
        
        // ✅ 好
        const name = user?.profile?.name
        

4.2 异步错误

        // 问题：
        // Error: Callback was already called
        
        // 原因：
        // - 回调函数被调用多次
        
        // 修复：
        // ❌ 不好
        function readFile(callback) {
          callback(data)
          callback(error) // 再次调用
        }
        
        // ✅ 好
        function readFile(callback) {
          callback(data)
          // 不再调用
        }
        

4.3 五问分析

问 1：如何避免常见 Bug？

        // 避免方法：
        
        // 1. 使用 TypeScript
        // - 类型检查
        // - 编译时发现问题
        
        // 2. 使用 ESLint
        // - 代码规范检查
        // - 静态分析
        
        // 3. 编写测试
        // - 单元测试
        // - 集成测试
        

---

五、修复策略

5.1 最小修改原则

        // 修复 Bug 时：
        
        // 1. 只改必要的代码
        // - 不要顺便重构
        // - 不要添加新功能
        
        // 2. 保持代码风格一致
        // - 遵循项目规范
        // - 不要改变格式
        
        // 3. 添加回归测试
        // - 防止 Bug 再次出现
        

5.2 测试验证

        // 修复后必须验证：
        
        // 1. 原场景测试
        // - 触发 Bug 的步骤
        // - 确认 Bug 已修复
        
        // 2. 边界测试
        // - 空值
        // - 极端值
        
        // 3. 回归测试
        // - 原有功能
        // - 确保没有破坏
        

5.3 五问分析

问 1：为什么修复后要立即测试？

        // 原因：
        
        // 1. 确认修复有效
        // - 立即验证
        // - 避免忘记
        
        // 2. 发现引入的新问题
        // - 修复可能引入新 Bug
        // - 及时发现
        
        // 3. 建立信心
        // - 测试通过
        // - 代码可以发布
        

---

六、实战示例

6.1 场景：用户无法登录

        用户报告：点击登录按钮后，页面没有反应
        

6.2 Claude 的分析过程

        // Claude 问：
        // 1. 期望行为：登录成功后跳转到首页
        // 2. 实际行为：页面没有变化
        // 3. 复现步骤：点击登录按钮
        
        // Claude 检查：
        // 1. 查看登录 API 调用
        // 2. 查看错误处理
        // 3. 查看页面跳转逻辑
        

6.3 Claude 发现的问题

        // 问题代码：
        async function handleLogin() {
          const response = await fetch('/api/login', {
            method: 'POST',
            body: JSON.stringify({ email, password })
          })
          // 缺少错误处理
          router.push('/home') // 直接跳转
        }
        
        // 问题：
        // - 如果 API 返回错误，代码仍然跳转
        // - 没有检查 response.ok
        

6.4 Claude 的修复

        // 修复后：
        async function handleLogin() {
          const response = await fetch('/api/login', {
            method: 'POST',
            body: JSON.stringify({ email, password })
          })
        
          if (!response.ok) {
            const error = await response.json()
            showError(error.message)
            return
          }
        
          router.push('/home')
        }
        

6.5 五问分析

问 1：修复后如何验证？

        // 验证方法：
        
        // 1. 正常登录
        // - 输入正确凭据
        // - 确认跳转成功
        
        // 2. 错误凭据
        // - 输入错误密码
        // - 确认显示错误消息
        
        // 3. 网络错误
        // - 断开网络
        // - 确认有错误处理
        

---

七、调试命令

7.1 Claude Code 调试命令

        # 启用调试模式
        claude --debug
        
        # 启用 verbose 日志
        claude --verbose
        
        # 查看调试日志
        tail -f ~/.claude/debug/latest
        
        # 查看错误日志
        tail -f ~/.claude/logs/errors/latest
        

7.2 日志级别

源码位置：`src/utils/debug.ts`

        // CLAUDE_CODE_DEBUG_LOG_LEVEL 环境变量：
        
        verbose  // 最详细（默认关闭）
        debug    // 默认级别
        info     // 信息
        warn     // 警告
        error    // 仅错误
        

7.3 五问分析

问 1：如何过滤调试日志？

        // 方法：
        
        // 1. 按级别过滤
        CLAUDE_CODE_DEBUG_LOG_LEVEL=error
        
        // 2. 按模块过滤
        --debug=api:*
        
        // 3. 按关键词过滤
        --debug=*User*
        

---

八、思考题

思考题 1：如何处理难以复现的 Bug？

答案：

        // 方法：
        
        // 1. 收集更多信息
        // - 用户环境
        // - 操作步骤
        // - 时间点
        
        // 2. 添加日志
        // - 在可疑位置添加日志
        // - 等待 Bug 再次出现
        
        // 3. 代码审查
        // - 审查可疑代码
        // - 找出潜在问题
        
        // 4. 静态分析
        // - 使用 TypeScript/ESLint
        // - 找出类型错误
        

---

思考题 2：如何处理线上 Bug？

答案：

        // 线上 Bug 处理流程：
        
        // 1. 立即止损
        // - 回滚到稳定版本
        // - 减少影响范围
        
        // 2. 收集信息
        // - 错误日志
        // - 用户报告
        
        // 3. 本地复现
        // - 在测试环境复现
        // - 确认修复
        
        // 4. 灰度发布
        // - 先给一小部分用户
        // - 确认没问题再全量
        

---

思考题 3：如何预防 Bug？

答案：

        // 预防方法：
        
        // 1. 代码审查
        // - Pull Request 必须审查
        // - 至少一人审查
        
        // 2. 自动化测试
        // - 单元测试
        // - 集成测试
        // - E2E 测试
        
        // 3. TypeScript/ESLint
        // - 编译时检查
        // - 静态分析
        
        // 4. 监控和告警
        // - 尽早发现问题
        // - 及时通知
        

---

九、延伸阅读

资源	说明
`/debug` 命令	启用调试模式
`src/utils/debug.ts`	调试工具实现

---

十、下节预告

下一节我们将进入 高级技巧：

- 多模型协作

- 自定义技能开发

- 工作流自动化

---

*- 第一轮：□ 事实准确性*

*- 第二轮：□ 深度与洞见*

*- 第三轮：□ 可读性与价值*