Python 调试需理解 breakpoint()依赖 PYTHONBREAKPOINT 环境变量、sys.settrace()底层机制及 pdb 栈帧劫持原理；多线程中仅当前线程暂停；n 跳过函数调用，s 进入函数体；VS Code 调试须配置 justMyCode 和 subProcess。

Python 调试不是靠 print() 硬堆出来的，真正可控的调试必须理解 sys.settrace()、breakpoint() 底层如何挂钩到 CPython 的执行循环，以及 pdb 是怎么劫持 栈帧并注入交互式上下文的。

为什么 breakpoint() 在某些环境下不生效？

它本质是调用 import pdb; pdb.set_trace()，但会先查 环境变量 PYTHONBREAKPOINT。如果被设成 0，就直接返回，什么也不做；如果指向一个自定义函数（比如 ipdb.set_trace），就必须确保该模块已安装且可导入。

• PYTHONBREAKPOINT=0 → 完全静默跳过，常被 CI/CD 或生产镜像默认设置
• PYTHONBREAKPOINT=ipdb.set_trace → 需提前 pip install ipdb，否则抛 ImportError
• 在多线程中，breakpoint() 只影响当前线程，其他线程照常运行，容易误判“断点没停住”

pdb 里 n 和 s 的行为差异到底在哪？

两者都单步执行下一行，但触发条件完全不同：n（next）跳过函数调用，s（step）会进入函数体。这个 区别 在异步代码或装饰器嵌套时极易引发困惑。

• n：执行当前行，遇到函数调用直接运行完并停在下一行，不进函数内部
• s：只要当前行有可进入的代码（包括内置函数如 len() 的 Python 实现、用户函数、生成器表达式），就跳入第一行
• 对 async def 函数，s 会停在 async def 行，但不会自动进入事件循环；要调试协程体，得先 step 到 await 行再 s 进去

如何用 sys.settrace() 实现轻量级函数入口日志？

它比装饰器更底层，能捕获所有函数调用（包括内置函数调用），但代价是显著性能损耗——每行 字节 码都会触发回调，不适合长期开启。

立即学习“Python 免费学习笔记（深入）”；

import sys 
def trace_calls(frame, event, arg): if event == 'call': func_name = frame.f_code.co_name if func_name not in ['', '']: print(f"→ {func_name}({list(frame.f_locals.keys())})") return trace_calls
sys.settrace(trace_calls)
后续代码开始被追踪
def foo(x): return x + 1 foo(42) sys.settrace(None)  # 记得关闭！

• 回调函数 必须返回自身（或另一个 trace 函数），否则追踪立即终止
• 不能在 trace 函数里修改 frame.f_locals，CPython 会忽略写入
• 若需过滤特定模块，检查 frame.f_code.co_filename，避免追踪 标准库

VS Code 的 launch.json 调试配置最容易漏掉的关键字段

很多人只配 module 或 program，却忘了 justMyCode 和 subProcess——前者控制是否跳进标准库，后者决定子进程是否也被调试。

• "justMyCode": true（默认）→ 自动跳过 site-packages 和 Python 标准库，但如果你正在调试 requests 源码，就得设为 false
• "subProcess": true → 启用对 subprocess.Popen 启动的子进程的调试支持，否则子进程完全脱离控制
• 调试 pytest 时，必须加 "env": {"PYTHONPATH": "${workspaceFolder}"}，否则测试文件可能 import 失败

真正卡住人的从来不是“怎么下断点”，而是当 step 进去发现帧对象 f_locals 是空的，或者 breakpoint() 像没写一样继续跑——这时候得立刻怀疑 trace 状态、环境变量、或是否在优化模式（python -O）下运行。