debugging-and-error-recovery

调试与错误恢复（Debugging and Error Recovery）

技能概述

提供一套系统化的根因调试方法，通过结构化的检查清单和停线规则，帮助开发者从测试失败、构建中断、运行时异常到生产事故中找到并修复根本原因，而不是靠猜测浪费时间。

适用场景

1. 测试失败或构建中断

当代码修改后测试失败、CI 构建报错，或者出现类型错误、依赖问题时，使用六步检查清单从重现、定位、简化到根因修复和验证，避免跳过问题继续开发导致错误累积。

2. 运行时行为异常

应用出现 TypeError、网络错误、渲染崩溃或白屏，以及时灵时不灵的间歇性 Bug 时，按照分层定位流程（前端/后端/数据库/外部服务）找到问题所在，并使用 Git Bisect 等工具定位引入问题的具体提交。

3. 生产事故和 Bug 报告

遇到用户报告的 Bug 或线上错误时，通过降级模式和安全后备模式优先保障服务可用性，同时使用系统化方法重现、定位并修复根因，添加回归测试防止复发，最后端到端验证整个场景。

核心功能

1. 六步结构化调试流程

提供不可跳过的检查清单：重现问题、定位故障层、创建最小化复现用例、修复根本原因而非症状、编写回归测试防护复发、端到端验证修复效果。流程适用于测试失败、构建错误、运行时异常和生产事故等各类问题场景。

2. 不可复现问题的排查策略

针对时灵时不灵的 Bug，提供时间依赖、环境依赖、状态依赖和真正随机的分类处理方法：添加日志时间戳、使用人工延迟扩大竞态窗口、对比环境差异、检查状态泄漏、设置错误告警和监控，帮助开发者在无法稳定复现时也能缩小范围并监控问题。

3. 错误分类处理模式

针对测试失败、构建失败和运行时错误提供专门的分流决策树：判断是否修改了相关代码、是否是测试本身问题、是否是副作用导致的共享状态污染，以及 TypeError、网络错误、渲染错误和无报错的异常行为的具体定位路径，避免盲目猜测。

常见问题

什么时候应该使用停线规则？

当任何意外情况发生时——测试失败、构建中断、日志出现错误、之前正常的功能停止工作——都应该立即停线。停线规则要求停止添加新功能、保留证据（错误输出、日志、复现步骤）、使用检查清单诊断、修复根因、添加防护测试、验证后才能恢复。不要跳过失败的测试继续开发，错误会累积。

如何重现一个不可复现的 Bug？

首先判断不可复现的原因：时间依赖（加日志时间戳、人工延迟扩大竞态窗口、负载测试增加碰撞概率）、环境依赖（对比版本/OS/环境变量、检查数据库状态、在 CI 干净环境尝试）、状态依赖（检查测试间的状态泄漏、全局变量和单例、独立运行失败场景）、真正随机（添加防御日志、设置错误告警、记录条件等待下次出现）。

症状修复和根因修复有什么区别？

症状修复只解决表现，不解决根本原因，容易复发。例如用户列表显示重复，症状修复是在 UI 组件中去重，根因修复是找到 API 查询的 JOIN 问题、添加 DISTINCT 或修复数据模型。调试时应该不断问"为什么会这样"直到找到真正的原因，而不是仅仅在表象处修补。修复后应添加回归测试，确保问题不会再次出现。