---
title: 工具-07-调试技巧
aliases:
  - 调试
  - Debugging
  - 排查问题
tags:
  - 工具/工程化
  - 类型/教程
created: 2026-10-11
updated: 2026-10-11
level: 进阶
prerequisites:
  - "[[工具-06-编辑器与IDE]]"
  - "[[工具-04-测试基础]]"
sources:
  - https://code.visualstudio.com/docs/editor/debugging
  - https://developer.mozilla.org/zh-CN/docs/Learn_web_development
  - https://learn.microsoft.com/zh-cn/visualstudio/debugger/
  - https://docs.python.org/3/library/pdb.html
---

# 工具-07-调试技巧

> [!abstract] 这一篇讲什么
> 调试不是"试到对为止"，而是一套**可复用的推理方法**：观察现象 → 提出假设 → 预测结果 → 做最小实验验证。
> 本篇覆盖错误信息解读、二分定位、断点调试、日志定位、以及按症状分类的排查手册。

## 一、是什么：调试的本质

调试（Debugging）是**在信息不完整的情况下定位因果链断裂点**的过程。

> [!important] 先改变一个习惯
> 大多数人的"调试"其实是**随机修改代码然后重跑**。这种做法偶尔奏效，但每次都在重置你的认知，无法积累。
> 有效的调试必须先形成假设，再设计一个**能区分两种假设**的实验。

对比一下两种做法：

| 做法 | 过程 | 结果 |
|---|---|---|
| 随机尝试 | 改一行 → 跑 → 还错 → 再改一行 | 平均耗时不可控，且不知道为什么修好了 |
| 假设驱动 | 观察 → 假设 A 或 B → 设计能区分 A/B 的实验 → 定位 | 每步都在缩小范围，可复用 |

## 二、为什么需要它

> [!note] 写代码的时间 vs 读代码的时间
> 一个函数你写它花了 10 分钟，未来会读它几十次。同理，一个 bug 你"猜"对了要 2 小时，用二分法定位只要 10 分钟。
> 调试能力是**把不可控的运气变成可控的流程**。

具体收益：

- **缩短定位时间**：二分法把 $O(n)$ 的尝试变成 $O(\log n)$
- **避免引入新 bug**：随机修改常常"修好一个坏掉两个"
- **沉淀知识**：每次定位到的根因都可以变成 [[工具-04-测试基础]] 里的一个回归测试

## 三、核心内容

### 3.1 读懂错误信息

> [!tip] 读栈的顺序
> **不要从最上面读，也不要从最下面读，先找"你自己的代码"那一帧。**
> 调用栈里绝大部分帧来自框架和标准库，它们通常没问题；从你的代码那一帧开始看，再往下游追。

一条典型的异常信息包含四要素：

| 要素 | 作用 | 例子 |
|---|---|---|
| 异常类型 | 说明错误的**类别** | `NullPointerException`、`TypeError` |
| 消息 | 说明错误的**具体形态** | `Cannot read properties of undefined (reading 'id')` |
| 栈帧 | 说明错误**发生在哪条调用链** | `at loadUser (user.js:42)` |
| 原因链 | 说明**谁触发了它** | `Caused by: ...` |

> [!warning] 三个常见误读
> 1. **只看最后一行**。最后一行往往是最外层的包装异常，真正的根因在 `Caused by` 链的最深处。
> 2. **忽略行号里的"第几列"**。长链式调用里，同一行可能有多个调用，列号能救命。
> 3. **把"报错的位置"当成"错误的位置"**。空指针报在**使用处**，但根因往往是**赋值处**——值在更早的地方就应该是非空的。

### 3.2 二分定位法

二分不只用于有序数组，它是**通用的排除法**。

| 维度 | 做法 | 适用场景 |
|---|---|---|
| 代码二分 | 注释掉一半逻辑，看现象是否消失 | 一大段新写的代码 |
| 数据二分 | 换一半输入数据，看哪一半能触发 | 某条特定数据导致崩溃 |
| 时间二分 | 用 `git bisect` 找引入 bug 的提交 | 之前能用、某天开始不能用 |
| 配置二分 | 恢复一半配置项 | 环境相关、只在某台机器复现 |

`git bisect` 是最被低估的工具，它把"翻 200 个提交"变成"跑 8 次"：

```bash
git bisect start
git bisect bad                 # 当前版本有问题
git bisect good v1.4.0         # 这个版本还是好的
# Git 会自动检出中间版本，你只需告诉它结果
git bisect good                # 或 git bisect bad
# ...重复约 log2(N) 次后
git bisect reset               # 结束后回到原分支
```

> [!tip] 自动化 bisect
> 如果你有一个能判定成败的脚本，可以全自动跑：
> `git bisect run python -m pytest tests/test_order.py`

### 3.3 断点调试

断点是**在程序运行时停下并检查现场**的能力，比打印更强大之处在于可以**交互式探索**。

断点类型与用途：

| 断点类型 | 什么时候停 | 典型用途 |
|---|---|---|
| 行断点 | 执行到该行 | 常规检查 |
| 条件断点 | 该行且条件为真 | 循环第 999 次才出问题 |
| 日志断点 | 不停，只打印 | 不想打断执行流，又想看值 |
| 异常断点 | 抛出指定异常时 | 异常被上层 `catch` 吞掉，看不到栈 |
| 函数断点 | 进入某函数时 | 只知道函数名，不知道在哪调用 |

> [!important] 条件断点是被低估的利器
> 循环里第 999 次迭代出错时，不要加 `if (i === 999) debugger;` 再删掉——直接用条件断点，条件写 `i === 999`。

单步操作的选择：

| 操作 | 行为 | 什么时候用 |
|---|---|---|
| Step Over（步过） | 执行完当前行，不进入函数内部 | 确定被调函数没问题 |
| Step Into（步入） | 进入被调函数 | 怀疑问题在被调函数里 |
| Step Out（步出） | 执行完当前函数并返回上层 | 发现进错了函数 |
| Continue | 继续到下一个断点 | 已经确认这段没问题 |

> [!warning] 异步与多线程调试的陷阱
> - **异步**：`await` 之后栈会断掉，"调用栈"面板可能只显示当前微任务。要顺着 `async` 链往回找，或改用日志追踪请求 ID。
> - **多线程**：断点会**暂停所有线程**，因此可能掩盖竞态条件，也可能制造出新的时序问题。
> - **"加日志就好了"**：这叫海森堡 bug——你的观察行为改变了时序。此时应减少观察点，或用低开销的记录方式（环形缓冲、trace）。

### 3.4 打印调试依然有效

> [!note] 什么时候打印比断点好
> - 问题只在**生产环境**复现（没法挂调试器）
> - 问题与**时序/并发**有关（断点会改变时序）
> - 需要看**一段时间的趋势**而非某一瞬间
> - 问题在**别人的机器**上

打印要有信息量，一条合格的调试输出至少包含：

```python
# 差的写法：不知道是哪个请求、什么值、什么时候
print(value)

# 好的写法：带上定位所需的全部上下文
print(f"[load_user] req={request_id} user_id={user_id!r} value={value!r} len={len(value)}")
```

> [!warning] 加了 print 记得删
> 更好的做法是用日志框架（`logging` / `ILogger` / `console.debug`）并设级别，
> 这样调试信息可以按级别开关，不需要改代码，也不会把 `print` 永久留在生产代码里。
> 见 [[Python-06-常用标准库]] 的 logging 小节。

### 3.5 按症状分类的排查手册

这张表是本文最实用的部分——**遇到症状先查表**：

| 症状 | 首先怀疑 | 具体动作 |
|---|---|---|
| 空指针 / undefined | 值在更早处就该非空 | 沿调用链回溯赋值点；检查是否有分支没赋值 |
| 类型错误 | 数据来源与预期不符 | 打印实际值与类型（`typeof` / `GetType()`），而非只看变量名 |
| 越界 | 长度与下标假设不一致 | 打印 `len` 与 `i`；检查是否差一（off-by-one） |
| 死循环 / 卡死 | 循环条件永不终止 | 看 CPU 占用；打印循环变量；设置条件断点看是否前进 |
| 内存不断增长 | 缓存无上限 / 监听器未移除 / 闭包持有 | 看内存曲线斜率；查全局缓存、事件订阅、定时器 |
| 并发结果不稳定 | 竞态 / 共享可变状态 | 减少共享；加锁；用不可变数据 |
| 本地能跑线上不行 | 环境差异 | 逐项比对：依赖版本、环境变量、时区、文件权限、路径大小写 |
| 慢但不知道慢在哪 | 未测量就优化 | 先 profile（火焰图），见 [[后端-09-后端安全与性能]] |
| 网络请求失败 | 分层问题 | 按 DNS → 连通性 → 端口 → TLS → 应用层逐段验证，见 [[计算机网络]] |

> [!example] 网络问题为什么要分层排查
> 「接口调不通」可能是六种完全不同的原因。逐层验证能把六选一变成一串是非题：
> ```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 不可复现的问题怎么处理

> [!important] 收集现场比反复重试更有价值
> 不可复现的问题，第一优先级是**在被修复之前把现场固定下来**。需要收集：
> - 完整堆栈（不要只截一行）
> - 触发时的输入数据（脱敏后保存原始报文/参数）
> - 环境信息（版本号、操作系统、时区、语言/区域设置）
> - 精确时间戳与请求 ID（用于和日志对齐）

无法复现时的三条路：

1. **提高可观测性**：补充日志与指标，等下次发生时自动留下证据
2. **构造性复现**：用假设反推需要什么条件才能触发，然后人为制造
3. **压力放大**：并发/数据量/边界值放大，让概率性 bug 变成必然

### 3.7 防御性调试工具

调试不只是"事后救火"，也包括**让错误更难发生**：

| 工具 | 作用 | 备注 |
|---|---|---|
| 断言（assert） | 开发期自检不变量 | 生产环境通常关闭，别用它做校验 |
| 静态类型 | 把错误提前到编译期 | 见 [[前端-05-TypeScript]] |
| 静态分析 / Lint | 发现可疑写法 | 见 [[工具-06-编辑器与IDE]] |
| 回归测试 | 固定已修复的 bug | 每个 bug 修完都补一条，见 [[工具-04-测试基础]] |
| 严格空值检查 | 把空指针变成编译警告 | 如 C# 的可空引用类型 |

> [!tip] 每修一个 bug 就补一条测试
> 这条习惯的价值是复利的：它保证**同一个 bug 不会以同样的方式回来**，
> 而且测试用例本身就是"这个坑长什么样"的最佳文档。

## 四、怎么用：一次完整的定位过程

> [!example] 案例：列表页偶发少一条数据
> **现象**：分页列表偶尔少一条，刷新又正常。
>
> 1. **观察**：不确定是"少查了"还是"少返回了"。先确认现象发生在哪一层。
> 2. **假设**：
>    - A：SQL 查询本身少了一条（数据层）
>    - B：查询到了但序列化/过滤丢了（应用层）
>    - C：并发插入导致分页边界漂移（时序问题）
> 3. **设计能区分 A/B/C 的实验**：在 SQL 执行后立刻打印返回行数，并在响应前再打印一次长度。
>    - 两次都少 → A
>    - 前多后少 → B
>    - 两次都不稳定且与并发写入时间相关 → C
> 4. **结果**：前多后少，是序列化时字段为 `null` 被过滤器剔除 → 定位到 B。
> 5. **修复 + 回归**：修正过滤逻辑，并补一条覆盖 `null` 字段的测试。

这个流程的关键在**第 3 步**：如果只是"随便加几行 print 看看"，你可能会同时打印十个值，却依然无法区分三种假设。

## 五、注意事项与常见坑

> [!warning] 调试时的六个坏习惯
> 1. **一次改多处**。改了三处然后好了，你不知道是哪处起的作用；如果更糟，也不知道是哪处害的。
> 2. **不看错误信息就搜答案**。搜索结果匹配的是别人的问题，不是你的。
> 3. **在错误的地方加日志**。日志要加在**假设的边界**上，而不是随手加。
> 4. **把警告当噪音**。编译警告常常就是 bug 的前兆。
> 5. **修好了就走**。不记录根因，下个月同一个人（可能是你自己）会再踩一次。
> 6. **在生产环境用调试器乱逛**。断点会暂停服务，涉及资金与数据时尤其危险。

> [!danger] 生产环境调试的红线
> - 不要在连接生产数据库的会话里执行无 `WHERE` 的 `UPDATE` / `DELETE`
> - 不要为了"看一眼"而在生产开启详细日志，可能泄露令牌与个人信息
> - 不要把生产数据整表导出到本地排查（合规与安全问题）

## 六、练习题

1. **基础题**：下面这段代码报 `TypeError: Cannot read properties of undefined (reading 'name')`，请说明应该先看哪一行，以及如何用打印确认根因。
   ```js
   function render(users) {
     return users.map((u) => u.profile.name).join(', ');
   }
   ```
2. **进阶题**：一个接口在 1000 次请求中有 3 次返回 500，日志里只有一行 `Internal Server Error`。请设计收集现场的方案，并说明为什么不能只靠重试来"解决"它。
3. **进阶题**：线上服务内存每小时增长 200 MB，重启后恢复。请给出至少四条可能的根因，以及区分它们的观察手段。
4. **思考题**：为什么"加日志之后 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>

> [!note] 关于版本
> 各编辑器与调试器的界面细节会随版本变化，具体操作以官方最新文档为准。
