systematic-debugging

系统化调试

核心原则

不要猜测。要系统地调查。

修复尝试失败 3 次后，立即停下来审视架构。

阶段 1：了解问题

收集信息

1. 预期行为是什么？
2. 实际行为是什么？
3. 问题从什么时候开始出现？
4. 最近有哪些变化？

稳定复现

• 创建最小复现案例
• 记录复现问题的确切步骤
• 确认问题是确定性出现还是偶发出现

先检查显而易见的问题

• 接通了吗？（服务正在运行，依赖项已安装）
• 你在正确的环境中吗？
• 文件保存了吗？
• 缓存清除了吗？

阶段 2：追踪根本原因

反向追踪技巧

1. 错误值出现在哪里？
2. 是什么用这个错误值调用了这里？
3. 不断向上追踪，直到找到源头
4. 从源头修复，而不是处理症状

查找可用示例

• 在同一代码库中找到类似的可用代码
• 类似的问题中，哪些情况是正常的？
• 与参考内容进行比较

找出差异

• 正常情况与异常情况有什么不同？
• 列出每一处差异，无论多么细微
• 不要想当然地认为“这不可能有影响”

阶段 3：形成假设

科学方法

1. 形成一个假设
2. 预测假设成立时会看到什么
3. 设计测试来验证
4. 运行测试
5. 如果不成立，根据新数据形成新的假设

不要同时提出多个假设

• 一次只验证一个假设
• 完整测试后再继续
• 不要混用调试方法

阶段 4：实施修复

先编写失败测试

• 编写能复现错误的测试
• 修复前，测试应该失败
• 修复后，测试应该通过

一次只进行一项修复

• 只做一项改动
• 不要顺手做改进
• 不要捆绑重构

完整验证

• 原有测试通过
• 其他测试未受影响
• 问题确实已解决
• 已覆盖边缘情况

阶段 5：修复无效时

每次尝试失败后

1. 停下来
2. 统计：你尝试了多少次修复？
3. 如果少于 3 次：返回阶段 1，根据新信息重新分析
4. 如果达到或超过 3 次：停下来审视架构

修复尝试失败 3 次或更多后

以下模式表明可能存在架构问题：

• 每次修复都会在其他地方暴露新问题
• 修复需要“大规模重构”
• 每次修复都会引发新的症状

停下来并自问：

• 这种模式从根本上是否合理？
• 这是合适的抽象吗？
• 是否应该重新设计？

调试工具

日志策略

// Add context to logs
console.log('[ComponentName] methodName:', {
  input,
  state: relevantState,
  timestamp: Date.now()
});

二分调试法

1. 在可疑代码的中间位置添加日志
2. 判断问题出现在前面还是后面
3. 重复上述步骤，直到定位问题

橡皮鸭调试法

大声解释问题：

• 应该发生什么？
• 实际发生了什么？
• 我尝试了什么？
• 我在做出哪些假设？

常见陷阱

避免这些错误

• 同时更改多项内容
• 假定自己知道原因
• 只修复症状，而不解决根本原因
• 不验证修复是否确实有效
• 不添加回归测试

危险信号

• “在我的机器上能正常运行”
• “昨天还好好的”
• “我什么都没改”
• “问题不可能出在这里”