w wyl123ly 的博客
MD

工具-07-调试技巧

15 KB 2026.10.11 原文件

工具-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)并设级别,

这样调试信息可以按级别开关,不需要改代码,也不会把 print 永久留在生产代码里。

见 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(用于和日志对齐)

无法复现时的三条路:

  1. 提高可观测性:补充日志与指标,等下次发生时自动留下证据
  2. 构造性复现:用假设反推需要什么条件才能触发,然后人为制造
  3. 压力放大:并发/数据量/边界值放大,让概率性 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

- 不要为了"看一眼"而在生产开启详细日志,可能泄露令牌与个人信息

- 不要把生产数据整表导出到本地排查(合规与安全问题)

六、练习题

  1. 基础题:下面这段代码报 TypeError: Cannot read properties of undefined (reading 'name'),请说明应该先看哪一行,以及如何用打印确认根因。

```js

function render(users) {

return users.map((u) => u.profile.name).join(', ');

}

```

  1. 进阶题:一个接口在 1000 次请求中有 3 次返回 500,日志里只有一行 Internal Server Error。请设计收集现场的方案,并说明为什么不能只靠重试来"解决"它。
  2. 进阶题:线上服务内存每小时增长 200 MB,重启后恢复。请给出至少四条可能的根因,以及区分它们的观察手段。
  3. 思考题:为什么"加日志之后 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>

关于版本

各编辑器与调试器的界面细节会随版本变化,具体操作以官方最新文档为准。