系统化 Bug 排查

何时使用

• 程序报错、崩溃、超时;
• 结果与预期不符(算错了、页面不对、数据丢了);
• 用户说"帮我查一下这个问题""这个 Bug 怎么修";
• 间歇性、难复现的问题。

使用步骤

第 1 步:复现

复现是排查的起点:

1. 记录触发条件(输入、环境、操作步骤);
2. 构造最小复现:去掉无关因素,留下最简复现路径;
3. 复现不了就收集现场信息(报错时间、日志、用户操作)。

第 2 步:取证

收集证据,不猜:

• 完整报错栈(前几行和最后几行都要);
• 相关日志(时间窗内);
• 输入数据与预期输出;
• 环境信息(版本、系统、配置)。

第 3 步:定位根因

高频根因清单、二分定位法和报告模板见 references/ROOT_CAUSE_PATTERNS.md。

用"假设 → 验证"循环:

1. 列出候选原因(按可能性排序);
2. 用日志、断点、最小实验逐一验证;
3. 采用二分法:在"输入 → 处理 → 输出"链路上,从中间断点验证,缩小范围;
4. git 场景用 git bisect 定位引入问题的提交;
5. 确认根因,而不是停在"症状"上。

第 4 步:修复与回归

1. 针对根因修复,不掩盖症状(不删除报错、不跳过校验);
2. 先写复现该 Bug 的回归测试,再修复;
3. 修复后运行全量测试;
4. 用最初的复现步骤再验证一遍。

第 5 步:输出排查报告

# Bug 排查报告

## 现象
## 复现步骤
## 根因
## 修复方案
## 回归验证
## 预防措施

输入与输出

• 输入:报错信息 / 异常行为描述 + 相关代码与日志;
• 输出:根因结论 + 修复 + 回归测试 + 排查报告。

示例

现象: 用户下单后优惠金额有时多减 1 分钱。

取证: 日志显示 amount * discount 用浮点数计算。

根因: 浮点精度问题(0.1 * 3 = 0.30000000000000004)。

修复: 金额用分为单位的整数计算,或使用 Decimal。

回归测试:

def test_discount_precision():
    assert calc_discount(1000, "0.1") == 100  # 分,不是浮点

预防: 约定金额一律用整数分存储;code review 时禁止金额浮点运算。

辅助脚本

scripts/stack_parser.py 从报错文本里提取异常类型、错误信息和调用链,标出异常抛出点:

python scripts/stack_parser.py error.log
# 或从管道读入
cat error.log | python scripts/stack_parser.py

脚本只做提取,结论需要人确认。

注意事项

• 先复现再修:无法复现的修复不算完成;
• 禁止猜修:每处修改都要有证据支持;
• 一次只改一个变量:验证因果关系;
• 间歇性问题优先找"时序/并发/缓存"类原因;
• 修复后主动问"还有没有类似的地方",批量预防。

不适用场景

• 用户只想要临时绕过(明确说明可以跳过根因修复);
• 没有代码或日志,只有一句"坏了"(应先收集信息);
• 问题明确属于第三方依赖缺陷(转报上游)。

验证方式

1. 触发:"这个报错怎么排查""帮我查 Bug";
2. 检查:报告含复现步骤、根因、修复、回归验证;
3. 复现验证:用最初步骤重跑,确认问题消失。