断点与单步：怎样把程序状态看清楚

程序输出少了一行，或变量在分支里突然不对——在关键处加 print 往往越加越乱。更可控的做法是挂断点，让解释器停下来的那一刻查看局部名字、调用栈，再单步跟过下一行。Python 3.7+ 内置 breakpoint()；底层通常是 pdb。IDE 图形调试器与它同源，学会命令行调试流程，换环境也不慌。调试的目标不是「会按五个键」，而是形成「假设 → 验证 → 缩小范围」的固定节奏。

breakpoint()：一行进入调试 ​

breakpoint() 等价于在默认配置下调用 pdb.set_trace()，运行到此处会进入交互提示符 (Pdb)：

from __future__ import annotations


def normalize(items: list[str]) -> list[str]:
    cleaned: list[str] = []
    for raw in items:
        text = raw.strip().lower()
        breakpoint()  # 停在这里，检查 text
        if text:
            cleaned.append(text)
    return cleaned


if __name__ == "__main__":
    print(normalize(["  Foo", "", "Bar  "]))

执行 python script.py，命中 断点 后终端交给 pdb，程序暂停、等待你的命令。环境变量 PYTHONBREAKPOINT=0 可全局禁用 breakpoint()，便于生产配置；设为 PYTHONBREAKPOINT=pdb.set_trace 则显式指定后端。提交代码前记得删掉临时 断点，或改用 IDE 行 断点（不污染源码）。

pdb 里先看什么 ​

进入 (Pdb) 后，优先弄清「我在哪、周围变量是什么」：

示例会话（节选）：

(Pdb) p raw
'  Foo'
(Pdb) p text
'foo'
(Pdb) n
(Pdb) l
  6         cleaned: list[str] = []
  7         for raw in items:
  8             text = raw.strip().lower()
  9  ->         breakpoint()
 10             if text:

单步 n 适合扫过本函数逻辑；怀疑错在 strip 或调用方时，用 s 进 callee，用 u（up）/d（down）在栈帧间切换。where 输出从下往上是当前帧到入口，快速判断是业务代码错还是库函数错。

条件断点与事后调试 ​

不必每轮循环都停。可在 pdb 里 break 10, value < 0 设条件，或在代码里写 guarded trace：

def process(batch: list[int]) -> int:
    total = 0
    for value in batch:
        total += value
        if value < 0:
            breakpoint()
    return total

更轻量的「事后查看」可用 post_mortem：未捕获异常发生后进栈：

import pdb
import sys


def main() -> None:
    try:
        run_app()
    except Exception:
        pdb.post_mortem(sys.exc_info()[2])
        raise


def run_app() -> None:
    raise RuntimeError("boom")

生产环境慎用交互 调试；本地复现失败用 post_mortem 或日志里的 traceback 往往足够。线上应靠结构化日志与 request id，而不是挂 断点。

IDE 与 pdb 的关系 ​

VS Code、PyCharm 的图形 断点 本质是挂起进程并展示变量窗；底层仍可能用 debugpy 或 pdb 协议。习惯 breakpoint() 后，在 IDE 里点行号设 断点、F10 单步、F11 进入，语义与 n/s 一致。团队里有人只有 SSH、有人只有 IDE，共享「先栈、再局部、再 单步」的顺序即可。

远程 调试 时 debugpy.listen 与 IDE attach 是另一层话题；命令行 pdb 在容器里不依赖图形界面，仍是兜底手段。

调试流程建议 ​

1. 用 traceback 定位最后一帧里你的代码文件与行号。
2. 在该行前加 breakpoint() 或 IDE 断点，用最小输入复现。
3. (Pdb) 里 w 看调用链，p 看怀疑的名字是否已是错值。
4. n/s 跟到变错的那个表达式；修完后去掉 断点，补一条针对该路径的小测试（若项目已有测试习惯）。

避免一次开十个 断点；每次只验证一个假设，比「停住然后乱 p 一遍」快。若 单步 进标准库太深，用 until 或 n 直到回到自己的文件。

日志与 traceback 配合 ​

pdb 适合「逻辑在某一行开始错」；若错误发生在深层库内，traceback 最后一帧是你的代码就先在那里 breakpoint。若全是库帧，用 logging 在边界打印入参，再决定是否 step 进库。不要在不理解的三方代码里单步到底，先缩小输入。

测试里临时断点 ​

pytest 加 --pdb 会在失败时自动进 post_mortem，等价于每个 assert 失败挂断点。开发单个用例时方便，全量 CI 不要开，否则会卡住流水线等人输入。本地复现：pytest tests/test_foo.py --pdb -x 在第一个失败处停。

打印与调试的边界 ​

print 适合一次性确认格式；反复跑的多轮循环里 print 会刷屏，改 breakpoint 加条件更省眼。logging 带级别与模块名，适合长期保留；breakpoint 是临时手段，合并前删掉或换成测试断言。

watch 模式下改代码自动重跑测试，失败时 pytest --pdb 会反复打断；这种时候先关掉 watch，用单次 pytest 复现，再挂 breakpoint。热重载与调试器同时开，栈帧常常对不上心里预期的行号，先简化环境。

调试多线程程序时，pdb 默认只跟当前线程；其他线程仍在跑，可能改共享状态。threading 问题更常用 logging 带 thread name、或专门工具；pdb 仍适合单线程逻辑与「第一现场」冻结。若在 async 代码里 breakpoint，注意停在 await 前后时 event loop 的状态，系列异步章节的调度直觉在这里仍适用。

养成「最小复现 + 单一断点 + 一条假设」的习惯，比堆 print 更接近工程化排错。修完后用回归测试钉住场景，断点可以删，测试留下。长期维护的模块里，可读的错误信息与 narrow 的异常类型，有时比频繁进 pdb 更省时间——调试是手段，不是日常默认路径。

远程 SSH 到服务器排错时，没有 IDE 也能 python -m pdb script.py 或插入 breakpoint() 后 rerun。学会 list、where、p、next、continue 五条命令，比带图形界面的习惯更便携。断点调试与单元测试互补：测试钉住行为，调试理解第一次为什么错。

遇到「偶发、难复现」的 bug，先尽量缩小输入与关闭并发，再在稳定复现路径上挂断点。记录断点处变量的 repr 与调用栈截图，修完后写进 issue 或 PR 描述，比口头「我本地好了」更利于 review。调试技能与读 traceback、写 narrow except 一样，都是日常工程能力，不必等到大故障才练。

IDE 里悬停看变量与 pdb 里 p expr 是同一信息的两种视图；习惯命令行后，远程容器里没有图形界面也能排错。合并前检查代码里是否残留 breakpoint()，CI 若误跑带断点的分支会挂起 job——pre-commit 或 grep 扫 breakpoint 是部分团队的保险。调试是局部手段，测试与清晰错误信息才是长期可维护的基础。

读官方库源码时，在关键分支临时 breakpoint() 能对照文档理解行为，但别在 site-packages 里留修改；用 editable 装 fork 或在 venv 外备份。Python 3.11+ 的异常组与 note 让 traceback 信息更密，配合 pdb 的 where 能更快定位 async 或多 except 场景下的真实原因。

把常用 pdb 命令写进项目 CONTRIBUTING 的「排错」小节，团队口径一致：先 where 再 p，单步用 n 除非要进函数。图形调试与 pdb 可以并存，按场景切换，不必二选一。修完 bug 后问一句「若没有断点，测试能否拦住」——能则补测试，不能则考虑 logging 或更明确的断言消息。

复杂数据结构在 pdb 里用 pp 比 p 可读；长列表可 p len(x) 或 p x[:3] 避免刷屏。断点停住时改局部变量再 continue 能试 quick fix，但别把这种 hack 当最终补丁，仍要回源码改并加测试。调试结束记得 c 或 q 退出，别留 suspended 进程占端口。

系列工程收尾篇之一：调试与打包、工具链一样，都是把「能跑」变成「可协作、可复现」。sync 环境对了、测试绿了，再进 pdb，往往更快看到真实逻辑错误而不是 import 幻觉。

掌握 breakpoint 与 pdb 五条命令，足够覆盖日常同步代码排错；把假设写进 issue、把结论写进测试，调试才算闭环。

收束 ​

断点把程序冻结在可疑时刻；pdb 提供单步与查看栈帧的命令；breakpoint() 是进调试的最短入口。掌握 l / w / p / n / c 足以应付多数逻辑错误；复杂并发问题另需日志与专门工具，但同步代码的路径仍从「停对一行」开始。