一句话定义
断点让执行在指定位置或满足条件时暂停,以便检查栈帧、变量并单步观察后续行为。断点改变执行时序,因此并发故障还需要日志等证据。
为什么重要
- 比 print 信息量大得多:一次暂停就能看到当前所有局部变量、调用栈,不用反复加 print 再重跑。
- 适合复杂状态:循环第 1000 次才出错?用条件断点,只在那一次停下。
- 理解陌生代码的利器:在框架源码里打断点,单步跟进,比读文档更快理解它在干什么。
使用边界
调试器命令会在所选栈帧中求值,有些表达式本身会修改状态。远程调试也必须确认连接的是目标进程;交互体验随 Python 版本和终端能力变化。
原理 / 图解
Python 3.7 起内建 breakpoint() 函数(PEP 553),默认进入 pdb;可通过环境变量 PYTHONBREAKPOINT 切换调试器或设为 0 全局禁用:https://peps.python.org/pep-0553/ ;pdb 命令参考:https://docs.python.org/3/library/pdb.html
pdb 常用命令速查:
| 命令 | 作用 | 命令 | 作用 |
|---|---|---|---|
b 行号[, 条件] |
设置(条件)断点 | n |
下一行(不进入函数) |
c |
继续到下一个断点 | s |
单步进入函数 |
p 表达式 |
打印值 | r |
运行到当前函数返回 |
pp |
美化打印 | w / where |
显示调用栈 |
l / ll |
显示源码 | u / d |
在栈帧间上下移动 |
interact |
进入交互式 Python | q |
退出 |
可运行示例
脚本:examples/14_breakpoint.py。本轮在 Windows / CPython 3.12.14 运行,库版本见末尾环境说明。
# 用非交互方式演示 pdb:向调试器"喂"一串命令,观察断点处的变量
import subprocess, sys, textwrap, pathlib, tempfile
target = textwrap.dedent('''
def accumulate(xs):
total = 0
for i, x in enumerate(xs):
total += x * i
return total
print("结果:", accumulate([5, 6, 7, 8]))
''')
path = pathlib.Path(tempfile.mkdtemp(prefix="tutorial-pdb-")) / "bp_demo.py"
path.write_text(target, encoding="utf-8")
commands = "\n".join([
"b 5, i == 2", # 条件断点:只在 i == 2 时停下
"c", # 继续运行到断点
"p i, x, total", # 打印变量
"where", # 查看调用栈
"c", # 继续直到结束
"q",
]) + "\n"
out = subprocess.run([sys.executable, "-X", "utf8", "-m", "pdb", str(path)], input=commands,
capture_output=True, text=True, encoding="utf-8", timeout=10)
print(out.stdout.replace(str(path), "bp_demo.py"))
本轮输出(任务路径以显示别名替换;完整日志见末尾):
> <用户目录>\appdata\local\temp\tutorial-pdb-8wxpc2j6\bp_demo.py(2)<module>()
-> def accumulate(xs):
(Pdb) Breakpoint 1 at <用户目录>\appdata\local\temp\tutorial-pdb-8wxpc2j6\bp_demo.py:5
(Pdb) > <用户目录>\appdata\local\temp\tutorial-pdb-8wxpc2j6\bp_demo.py(5)accumulate()
-> total += x * i
(Pdb) (2, 7, 6)
(Pdb) <用户目录>\.cache\codex-runtimes\codex-primary-runtime\dependencies\python\lib\bdb.py(627)run()
-> exec(cmd, globals, locals)
<string>(1)<module>()
<用户目录>\appdata\local\temp\tutorial-pdb-8wxpc2j6\bp_demo.py(7)<module>()
-> print("结果:", accumulate([5, 6, 7, 8]))
> <用户目录>\appdata\local\temp\tutorial-pdb-8wxpc2j6\bp_demo.py(5)accumulate()
-> total += x * i
(Pdb) 结果: 44
The program finished and will be restarted
> <用户目录>\appdata\local\temp\tutorial-pdb-8wxpc2j6\bp_demo.py(2)<module>()
-> def accumulate(xs):
(Pdb)
条件断点只在 i==2 时暂停。输出展示该栈帧的变量和调用链;命令通过标准输入自动送入 pdb,并使用独立临时路径与超时限制。
常见误区
- 把
breakpoint()提交进仓库:线上服务会卡住等待输入。可用 Ruff 规则T100检查遗留的调试语句:https://docs.astral.sh/ruff/rules/debugger/ - 在多进程 / 远程环境里用不了就放弃:远程调试可以用
debugpy(VS Code 的 Python 调试后端):https://github.com/microsoft/debugpy - 只会“下一步”:善用条件断点、
r(运行到返回)、u/d(切换栈帧)能省大量时间。 - 断点调试并发/异步代码时误判:暂停一个线程会改变时序,竞态问题可能因此“消失”,此时日志更可靠。
与 AI 开发的关系
- 调试训练代码:在
forward里打断点,检查每层输出的shape、是否出现nan,是定位模型 bug 的常用手段。 - Jupyter 中调试:
%debug魔法命令可以在异常发生后进入事后调试(post-mortem)。https://ipython.readthedocs.io/en/stable/interactive/magics.html#magic-debug - 调试 Agent / LLM 应用:在工具调用函数入口打断点,可以看到模型实际传进来的参数——常常会发现模型给的 JSON 和你预想的不一样。
延伸阅读
- PEP 553 – Built-in breakpoint():https://peps.python.org/pep-0553/
- pdb 文档:https://docs.python.org/3/library/pdb.html
- VS Code Python 调试:https://code.visualstudio.com/docs/python/debugging
理解检查
在断点中运行带副作用的函数,是否只是观察?
参考答案:不是。函数调用可能写文件、修改对象或发送请求,会改变被调试程序的状态。
核验与复现
核验日期:2026-10-14。示例状态:运行通过。本轮日志:14_breakpoint.py。