工具-07-调试技巧
这一篇讲什么
调试不是"试到对为止",而是一套可复用的推理方法:观察现象 → 提出假设 → 预测结果 → 做最小实验验证。
本篇覆盖错误信息解读、二分定位、断点调试、日志定位、以及按症状分类的排查手册。
一、是什么:调试的本质
调试(Debugging)是在信息不完整的情况下定位因果链断裂点的过程。
先改变一个习惯
大多数人的"调试"其实是随机修改代码然后重跑。这种做法偶尔奏效,但每次都在重置你的认知,无法积累。
有效的调试必须先形成假设,再设计一个能区分两种假设的实验。
对比一下两种做法:
| 做法 | 过程 | 结果 |
|---|---|---|
| 随机尝试 | 改一行 → 跑 → 还错 → 再改一行 | 平均耗时不可控,且不知道为什么修好了 |
| 假设驱动 | 观察 → 假设 A 或 B → 设计能区分 A/B 的实验 → 定位 | 每步都在缩小范围,可复用 |
二、为什么需要它
写代码的时间 vs 读代码的时间
一个函数你写它花了 10 分钟,未来会读它几十次。同理,一个 bug 你"猜"对了要 2 小时,用二分法定位只要 10 分钟。
调试能力是把不可控的运气变成可控的流程。
具体收益:
- 缩短定位时间:二分法把 的尝试变成
- 避免引入新 bug:随机修改常常"修好一个坏掉两个"
- 沉淀知识:每次定位到的根因都可以变成 工具-04-测试基础 里的一个回归测试
三、核心内容
3.1 读懂错误信息
读栈的顺序
不要从最上面读,也不要从最下面读,先找"你自己的代码"那一帧。
调用栈里绝大部分帧来自框架和标准库,它们通常没问题;从你的代码那一帧开始看,再往下游追。
一条典型的异常信息包含四要素:
| 要素 | 作用 | 例子 |
|---|---|---|
| 异常类型 | 说明错误的类别 | NullPointerException、TypeError |
| 消息 | 说明错误的具体形态 | Cannot read properties of undefined (reading 'id') |
| 栈帧 | 说明错误发生在哪条调用链 | at loadUser (user.js:42) |
| 原因链 | 说明谁触发了它 | Caused by: ... |
三个常见误读
1. 只看最后一行。最后一行往往是最外层的包装异常,真正的根因在
Caused by链的最深处。2. 忽略行号里的"第几列"。长链式调用里,同一行可能有多个调用,列号能救命。
3. 把"报错的位置"当成"错误的位置"。空指针报在使用处,但根因往往是赋值处——值在更早的地方就应该是非空的。
3.2 二分定位法
二分不只用于有序数组,它是通用的排除法。
| 维度 | 做法 | 适用场景 |
|---|---|---|
| 代码二分 | 注释掉一半逻辑,看现象是否消失 | 一大段新写的代码 |
| 数据二分 | 换一半输入数据,看哪一半能触发 | 某条特定数据导致崩溃 |
| 时间二分 | 用 git bisect 找引入 bug 的提交 | 之前能用、某天开始不能用 |
| 配置二分 | 恢复一半配置项 | 环境相关、只在某台机器复现 |
git bisect 是最被低估的工具,它把"翻 200 个提交"变成"跑 8 次":
git bisect start
git bisect bad # 当前版本有问题
git bisect good v1.4.0 # 这个版本还是好的
# Git 会自动检出中间版本,你只需告诉它结果
git bisect good # 或 git bisect bad
# ...重复约 log2(N) 次后
git bisect reset # 结束后回到原分支
自动化 bisect
如果你有一个能判定成败的脚本,可以全自动跑:
git bisect run python -m pytest tests/test_order.py
3.3 断点调试
断点是在程序运行时停下并检查现场的能力,比打印更强大之处在于可以交互式探索。
断点类型与用途:
| 断点类型 | 什么时候停 | 典型用途 |
|---|---|---|
| 行断点 | 执行到该行 | 常规检查 |
| 条件断点 | 该行且条件为真 | 循环第 999 次才出问题 |
| 日志断点 | 不停,只打印 | 不想打断执行流,又想看值 |
| 异常断点 | 抛出指定异常时 | 异常被上层 catch 吞掉,看不到栈 |
| 函数断点 | 进入某函数时 | 只知道函数名,不知道在哪调用 |
条件断点是被低估的利器
循环里第 999 次迭代出错时,不要加
if (i === 999) debugger;再删掉——直接用条件断点,条件写i === 999。
单步操作的选择:
| 操作 | 行为 | 什么时候用 |
|---|---|---|
| Step Over(步过) | 执行完当前行,不进入函数内部 | 确定被调函数没问题 |
| Step Into(步入) | 进入被调函数 | 怀疑问题在被调函数里 |
| Step Out(步出) | 执行完当前函数并返回上层 | 发现进错了函数 |
| Continue | 继续到下一个断点 | 已经确认这段没问题 |
异步与多线程调试的陷阱
- 异步:
await之后栈会断掉,"调用栈"面板可能只显示当前微任务。要顺着async链往回找,或改用日志追踪请求 ID。- 多线程:断点会暂停所有线程,因此可能掩盖竞态条件,也可能制造出新的时序问题。
- "加日志就好了":这叫海森堡 bug——你的观察行为改变了时序。此时应减少观察点,或用低开销的记录方式(环形缓冲、trace)。
3.4 打印调试依然有效
什么时候打印比断点好
- 问题只在生产环境复现(没法挂调试器)
- 问题与时序/并发有关(断点会改变时序)
- 需要看一段时间的趋势而非某一瞬间
- 问题在别人的机器上
打印要有信息量,一条合格的调试输出至少包含:
# 差的写法:不知道是哪个请求、什么值、什么时候
print(value)
# 好的写法:带上定位所需的全部上下文
print(f"[load_user] req={request_id} user_id={user_id!r} value={value!r} len={len(value)}")
加了 print 记得删
更好的做法是用日志框架(
logging/ILogger/console.debug)并设级别,这样调试信息可以按级别开关,不需要改代码,也不会把
见 Python-06-常用标准库 的 logging 小节。
3.5 按症状分类的排查手册
这张表是本文最实用的部分——遇到症状先查表:
| 症状 | 首先怀疑 | 具体动作 |
|---|---|---|
| 空指针 / undefined | 值在更早处就该非空 | 沿调用链回溯赋值点;检查是否有分支没赋值 |
| 类型错误 | 数据来源与预期不符 | 打印实际值与类型(typeof / GetType()),而非只看变量名 |
| 越界 | 长度与下标假设不一致 | 打印 len 与 i;检查是否差一(off-by-one) |
| 死循环 / 卡死 | 循环条件永不终止 | 看 CPU 占用;打印循环变量;设置条件断点看是否前进 |
| 内存不断增长 | 缓存无上限 / 监听器未移除 / 闭包持有 | 看内存曲线斜率;查全局缓存、事件订阅、定时器 |
| 并发结果不稳定 | 竞态 / 共享可变状态 | 减少共享;加锁;用不可变数据 |
| 本地能跑线上不行 | 环境差异 | 逐项比对:依赖版本、环境变量、时区、文件权限、路径大小写 |
| 慢但不知道慢在哪 | 未测量就优化 | 先 profile(火焰图),见 [[后端-09-后端安全与性能]] |
| 网络请求失败 | 分层问题 | 按 DNS → 连通性 → 端口 → TLS → 应用层逐段验证,见 [[计算机网络]] |
网络问题为什么要分层排查
「接口调不通」可能是六种完全不同的原因。逐层验证能把六选一变成一串是非题:
```bash
dig api.example.com # 1. DNS 能解析吗(拿不到 IP 就是 DNS)
ping <ip> # 2. 网络能通吗(不通是路由/防火墙)
nc -vz <ip> 443 # 3. 端口开着吗(拒绝是服务未监听或被拦)
curl -v https://api.example.com/health # 4. TLS 与 HTTP 层(看握手与状态码)
```
3.6 不可复现的问题怎么处理
收集现场比反复重试更有价值
不可复现的问题,第一优先级是在被修复之前把现场固定下来。需要收集:
- 完整堆栈(不要只截一行)
- 触发时的输入数据(脱敏后保存原始报文/参数)
- 环境信息(版本号、操作系统、时区、语言/区域设置)
- 精确时间戳与请求 ID(用于和日志对齐)
无法复现时的三条路:
- 提高可观测性:补充日志与指标,等下次发生时自动留下证据
- 构造性复现:用假设反推需要什么条件才能触发,然后人为制造
- 压力放大:并发/数据量/边界值放大,让概率性 bug 变成必然
3.7 防御性调试工具
调试不只是"事后救火",也包括让错误更难发生:
| 工具 | 作用 | 备注 |
|---|---|---|
| 断言(assert) | 开发期自检不变量 | 生产环境通常关闭,别用它做校验 |
| 静态类型 | 把错误提前到编译期 | 见 [[前端-05-TypeScript]] |
| 静态分析 / Lint | 发现可疑写法 | 见 [[工具-06-编辑器与IDE]] |
| 回归测试 | 固定已修复的 bug | 每个 bug 修完都补一条,见 [[工具-04-测试基础]] |
| 严格空值检查 | 把空指针变成编译警告 | 如 C# 的可空引用类型 |
每修一个 bug 就补一条测试
这条习惯的价值是复利的:它保证同一个 bug 不会以同样的方式回来,
而且测试用例本身就是"这个坑长什么样"的最佳文档。
四、怎么用:一次完整的定位过程
案例:列表页偶发少一条数据
现象:分页列表偶尔少一条,刷新又正常。
1. 观察:不确定是"少查了"还是"少返回了"。先确认现象发生在哪一层。
2. 假设:
- A:SQL 查询本身少了一条(数据层)
- B:查询到了但序列化/过滤丢了(应用层)
- C:并发插入导致分页边界漂移(时序问题)
3. 设计能区分 A/B/C 的实验:在 SQL 执行后立刻打印返回行数,并在响应前再打印一次长度。
- 两次都少 → A
- 前多后少 → B
- 两次都不稳定且与并发写入时间相关 → C
4. 结果:前多后少,是序列化时字段为
null被过滤器剔除 → 定位到 B。5. 修复 + 回归:修正过滤逻辑,并补一条覆盖
null字段的测试。
这个流程的关键在第 3 步:如果只是"随便加几行 print 看看",你可能会同时打印十个值,却依然无法区分三种假设。
五、注意事项与常见坑
调试时的六个坏习惯
1. 一次改多处。改了三处然后好了,你不知道是哪处起的作用;如果更糟,也不知道是哪处害的。
2. 不看错误信息就搜答案。搜索结果匹配的是别人的问题,不是你的。
3. 在错误的地方加日志。日志要加在假设的边界上,而不是随手加。
4. 把警告当噪音。编译警告常常就是 bug 的前兆。
5. 修好了就走。不记录根因,下个月同一个人(可能是你自己)会再踩一次。
6. 在生产环境用调试器乱逛。断点会暂停服务,涉及资金与数据时尤其危险。
生产环境调试的红线
- 不要在连接生产数据库的会话里执行无
WHERE的UPDATE/DELETE- 不要为了"看一眼"而在生产开启详细日志,可能泄露令牌与个人信息
- 不要把生产数据整表导出到本地排查(合规与安全问题)
六、练习题
- 基础题:下面这段代码报
TypeError: Cannot read properties of undefined (reading 'name'),请说明应该先看哪一行,以及如何用打印确认根因。
```js
function render(users) {
return users.map((u) => u.profile.name).join(', ');
}
```
- 进阶题:一个接口在 1000 次请求中有 3 次返回 500,日志里只有一行
Internal Server Error。请设计收集现场的方案,并说明为什么不能只靠重试来"解决"它。 - 进阶题:线上服务内存每小时增长 200 MB,重启后恢复。请给出至少四条可能的根因,以及区分它们的观察手段。
- 思考题:为什么"加日志之后 bug 就不出现了"这件事本身是一条重要线索?它暗示了哪一类问题?
七、常见问题(FAQ)
Q:断点和打印,到底该优先用哪个?
A:能在本地稳定复现的,用断点(信息更全、可交互);生产环境、并发时序、长周期趋势,用日志。两者不是替代关系。
Q:调试花太久,是不是该直接重写这段代码?
A:先给一个时间盒(比如 30 分钟)。如果超时仍无假设,重写往往更划算——但重写前要写下已知的边界条件,否则会把老 bug 一起重写进去。
Q:怎么判断自己是在调试还是在瞎试?
A:问自己:"我这次改动,是为了验证哪个假设?"如果答不上来,就是在瞎试。
Q:同事的代码看不懂导致调试困难,怎么办?
A:先写测试把当前行为固定下来,再改。测试会告诉你哪些行为是"有意为之"的契约,哪些只是巧合。
相关笔记
- 工具-06-编辑器与IDE:断点调试的具体操作与快捷键
- 工具-04-测试基础:把定位到的 bug 固化为回归测试
- 工具-01-Git版本控制:
git bisect与reflog找回现场 - 计算机网络:网络问题的分层排查
- 常见问题FAQ:遇到报错的通用处理顺序
参考来源
- VS Code 官方文档《Debugging》:<https://code.visualstudio.com/docs/editor/debugging>
- Visual Studio 官方调试器文档(中文):<https://learn.microsoft.com/zh-cn/visualstudio/debugger/>
- Python 官方文档《pdb — The Python Debugger》:<https://docs.python.org/3/library/pdb.html>
- MDN Web 开发学习区(含测试与调试章节):<https://developer.mozilla.org/zh-CN/docs/Learn_web_development>
关于版本
各编辑器与调试器的界面细节会随版本变化,具体操作以官方最新文档为准。