05 · 调试方法论：从症状到根因的系统化排障
调试不是"改到不报错为止"，是"定位根因"的过程。 新手靠试错，老手靠二分。本篇给一套跨前端、后端、AI 都通用的排障流程：症状 → 假设 → 最小复现 → 二分 → 根因 → 修复与回归。
速览卡
| 项 | 内容 |
|---|---|
| 一句话定位 | 用"症状 → 假设 → 最小复现 → 二分定位 → 根因 → 修复回归"六步，把排障从碰运气变成可重复的流程 |
| 核心内容 | 调试心态、症状 vs 根因、最小复现、二分法、日志与观测、常见思维陷阱、跨端调试对照 |
| 读完能回答 | 拿到一个 bug 先做什么？怎么从海量代码里定位？怎么确认真的修好了？ |
| 相关板块 | N11 · 抓包与网络调试 ｜ A12 · 前端可观测性 ｜ C08 · 服务端可观测性 |
一、先校正心态：三个"调试自觉"
1.1 症状不是根因
"页面白屏"是症状，"某个接口返回 500"是症状，"构建失败"也是症状。根因藏在调用链里。看到症状的第一反应不是"我知道原因了"，而是"我要怎么验证"。
1.2 别猜，用证据
"可能是缓存问题""可能内存泄漏"——猜测本身没错，但猜测之后必须设计验证。没有验证的猜测，和瞎改一样危险。
1.3 改一行只验证一个假设
同时改三处，出问题了不知道是哪处引入的。一次改一个变量，是调试纪律的底线。
二、六步排障流程
① 描述症状 → ② 生成假设 → ③ 最小复现 → ④ 二分定位 → ⑤ 确认根因 → ⑥ 修复并回归① 描述症状：能写下来才算看清
把症状写成"可复现的描述"：什么操作、什么环境、什么数据、什么报错。写不清楚，往往就是还没定位。
② 生成假设：列 2~3 个候选原因
按"可能性从高到低"列假设，给每个假设配一个验证方法：
| 假设 | 验证方法 |
|---|---|
| 接口返回了错误数据 | curl 直接调接口看响应 |
| 前端渲染逻辑 bug | 打印数据，或单测驱动 |
| 缓存用了旧数据 | 清缓存/换参数复现 |
③ 最小复现：把问题缩到最小
最小复现 = 去掉所有非必要因素，仍能稳定复现。它让"调试"变成"可重复实验"，也让后面的二分有基准。
④ 二分定位：在怀疑区间中间切一刀
在海量代码/调用链里，二分法比线性排查快一个量级：
在链路中间打点（日志/断点），看结果偏哪边 → 缩小一半范围 → 重复二分不只在"代码行"上可用：也可以二分"版本"（git bisect）、二分"输入数据"、二分"环境变量"。
⑤ 确认根因：证明"改了它就能好"
根因成立的标准是可证伪：在最小复现上做最小改动，症状消失；改回去，症状回来。只出现一次不能算确认。
⑥ 修复并回归：把经验变成资产
修复后做三件事：跑回归（相关测试 + 手工复现路径）、写测试防回归、记录根因（踩坑区就是干这个的）。
三、排障三板斧：日志、观测、抓包
跨端调试的共同基础设施：
| 工具 | 回答什么问题 | 相关文章 |
|---|---|---|
| 日志/打印 | "走到这步了吗？值是多少？" | C08 服务端、B20 异常捕获 |
| 指标/追踪 | "哪里慢？耗时分布？" | A12 前端、C08 服务端 |
| 抓包/链路 | "请求到底发出去了没？响应是什么？" | N11 抓包 |
前端转全栈的调试优势：你能同时看前端网络面板 + 后端日志 + 数据库慢查询，把调用链从头到尾打通。缺哪一环，就先用哪一环的工具补上证据。
四、常见思维陷阱
| 陷阱 | 表现 | 对策 |
|---|---|---|
| 过早结论 | "我一眼看出是 XX" | 先列假设再验证 |
| 一次改多处 | 修好了一个又冒出新的 | 一次改一个变量 |
| 复现不了就放弃 | 偶现 bug 直接绕过 | 加日志/监控抓现场，扩大采集 |
| 修症状不修根因 | 报错消失但逻辑还是错的 | 用最小复现验证根因 |
| 环境依赖 | "我本地好的" | 对比环境差异（版本/配置/数据） |
五、跨端调试对照
| 场景 | 前端做法 | 后端做法 | AI 场景 |
|---|---|---|---|
| 定位数据问题 | 网络面板看响应 | curl + 日志 | 打印 prompt/response |
| 定位慢 | Performance 面板 | 慢查询 + APM | 看 token 耗时与重试 |
| 定位偶现 | 埋点 + 录屏 | 结构化日志 + 全链路 ID | 评测集回归 + 采样日志 |
AI 调试多一个维度：模型输出不是确定性的。同一个输入两次结果可能不同，排障要先确认"这是代码 bug 还是模型波动"，再决定修什么。
自检清单
- [ ] 能区分症状与根因，并把症状写成可复现描述
- [ ] 每个假设都配了验证方法，验证后才下结论
- [ ] 能构造最小复现，并说清它为什么"最小"
- [ ] 会用在链路中间打点做二分定位
- [ ] 根因确认满足"改了就好、改回去复发"
- [ ] 修复后做了回归，并把经验记到踩坑区
常见误区
| 误区 | 事实 |
|---|---|
| "排障 = 改代码" | 排障 = 定位根因，改代码只是最后一步 |
| "日志打多了就好了" | 日志要打在分界点，打错地方反而误导 |
| "偶现的没法查" | 加观测扩大采样，偶现也能抓现场 |
| "本地好的就不是我的问题" | 环境差异本身就是重要证据，要对比版本/配置/数据 |
动手练习
练习 A：走一遍六步
找一个已知 bug，按六步写排障记录：症状 → 假设 → 最小复现 → 二分 → 根因 → 修复。重点写"怎么验证的"。
练习 B：用 git bisect 定位
在项目里找一个历史引入的 bug，用 git bisect 二分提交定位到引入 commit，记录二分了几次。
练习 C：写一条踩坑记录
把练习 A 的根因按"症状 / 原因 / 解法 / 预防"写成一条踩坑记录，参照 踩坑区格式。
相关文档
本区
- 01 · 工程方法论全景 —— 闭环定位
其他域
- N11 · 抓包与网络调试 —— 网络层定位
- A12 · 前端可观测性与线上排障 —— 前端线上排障
- C08 · 服务端可观测性 —— 日志/指标/链路
- 踩坑区 —— 排障经验的沉淀形态