Python pdb：本地断点、事后调试与帧栈检查

pdb 是 Python 标准库本地调试器

pdb 随 Python 解释器提供，通过 breakpoint()、python -m pdb 和 post_mortem() 控制当前进程。它直接读取和求值帧内对象，适合本地终端与事后异常分析，但不提供 DAP 远程会话、IDE 路径映射或网络监听。

使用 pdb 时首先固定解释器和源码身份，再决定在哪个帧停下、允许执行哪些表达式，以及退出后是否恢复了进程和临时断点。debugpy 是独立安装的调试适配器，远程连接和子进程能力放在另一篇主文。

Python pdb 本地断点与异常帧分析解释器进入断点或异常现场，沿帧栈检查对象，以版本、源码身份、敏感变量和退出状态约束会话。高清原图

先分清 pdb 与 debugpy 的责任

pdb 属于 Python 标准库，直接在终端中操作当前解释器的栈、帧、断点和变量。它适合本地脚本、可控服务副本、异常后的 post-mortem，以及不依赖图形客户端的快速检查。breakpoint() 默认进入 pdb，pdb.set_trace() 在代码中显式停住，python -m pdb script.py 从启动阶段接管脚本，pdb.post_mortem() 则从异常 traceback 进入失败现场。Python pdb 文档是命令和版本行为的基准。

debugpy 是实现 Debug Adapter Protocol 的调试服务。它可以启动脚本或模块、等待 DAP 客户端、主动连接客户端，也可以注入既有 Python 进程。IDE 中的变量窗口、调用栈和断点通过 DAP 与 debugpy 交换状态；因此“TCP 端口能连接”只证明网络可达，不证明源码映射、进程选择和断点已经正确。

两者都能执行代码，不是只读观察器。pdb 中未识别的输入会作为 Python 表达式或语句在当前帧求值，debugpy 客户端也能修改变量、调用表达式和控制进程。调试权限等价于目标进程代码执行权与内存读取权，必须比普通日志查看更严格。

选择方式可以从现场约束出发：本地单进程与异常栈优先 pdb；需要图形客户端、远程主机、复杂线程或子进程时使用 debugpy；进程已经运行且不能重启时才考虑 PID attach；只剩异常日志而没有 traceback、转储或原进程时，调试器无法凭空恢复已经丢失的局部变量。

先确认解释器，再确认 debugpy 包

pdb 随 Python 提供，不需要单独安装。先确认命令指向项目实际解释器，而不是操作系统别名或另一个虚拟环境：

python --version
python -c "import sys; print(sys.executable); print(sys.version)"
python -m pdb --help

项目使用虚拟环境时，先激活环境，或始终用环境中的解释器绝对入口执行 -m。pip 与 python 可能来自不同环境，因此安装 debugpy 应写成：

python -m pip install --upgrade debugpy
python -m pip show debugpy
python -c "import debugpy; print(debugpy.__version__); print(debugpy.__file__)"

debugpy 的 PyPI 页面给出发行版本与 Python 要求，debugpy 仓库提供 CLI 和故障排查入口。个人环境可通过升级命令取得当前兼容版；团队应把验证过的精确版本写入开发依赖或约束文件，并让虚拟环境、容器和 IDE 扩展核对实际加载的 debugpy。IDE 可能携带自己的版本，不能因为项目环境安装成功就假定两者相同。

版本链至少记录：

python --version
python -m pip show debugpy
python -c "import sys, debugpy; print(sys.executable); print(debugpy.__version__)"

升级后若 python -m debugpy 报模块不存在，先比较 sys.executable、pip show 的 Location 与当前虚拟环境。使用系统 Python 时遇到 externally managed environment，应创建项目虚拟环境或通过发行版支持的包入口安装，不要用强制覆盖破坏系统包。

debugpy 作为开发依赖卸载时使用 python -m pip uninstall debugpy，随后重新执行 import 检查；虚拟环境是一次性对象时，删除整个环境更能避免残留依赖。pdb 属于标准库，不能也无需单独卸载。仓库中还要删除临时 breakpoint()、debugpy 启动参数和日志目录，避免工具包消失而阻塞点仍留在运行路径。

用 pdb 看当前帧，也看异常帧

在隔离目录创建一个稳定失败的脚本：

def normalize(record):
    user_id = record["user_id"]
    return user_id.strip().lower()

def main():
    payload = {"User_ID": " Demo "}
    print(normalize(payload))

if __name__ == "__main__":
    main()

从启动阶段进入调试器：

python -m pdb app.py

在 (Pdb) 提示符中执行：

break app.py:2
continue
p record
where
up
p payload
continue

断点会在取键前停住，record 应显示只有 User_ID，where 应展示从 main() 到 normalize() 的调用链。继续后程序抛出 KeyError，python -m pdb 会自动进入 post-mortem；此时再次 where、p record，能证明当前检查的是异常 traceback 中保存的帧，而不是重跑后的新状态。

python -m pdb 在 post-mortem 结束或程序正常退出后会重新启动脚本并保留断点。看到入口再次执行不是业务自动恢复。实验结束用 quit 真正退出，再确认没有 Python 子进程残留。

代码内也可以只在捕获异常后进入现场：

import pdb

try:
    main()
except Exception:
    pdb.post_mortem()
    raise

这种写法只适合本地或一次性诊断分支。共享服务若进入交互提示符而没有终端，会挂住 worker；提交前应删除或用默认关闭、显式授权的诊断开关保护。不要把真实请求体打印到工单来替代调试，变量查看同样要遵守数据分级。

breakpoint() 可由 PYTHONBREAKPOINT 控制。默认值调用 pdb.set_trace()，设为 0 会禁用断点，也可以改成其他可导入的调试入口；环境中断点“完全没反应”时，应检查该变量和 sys.breakpointhook。团队测试脚本可以临时设置 PYTHONBREAKPOINT=0 防止误停，但普通启动环境不应悄悄覆盖它后让开发者误判代码未执行。

pdb -p 有明确的 Python 版本边界

Python 3.14 才新增 python -m pdb -p <pid>。在更早的解释器中照抄这条命令不会得到等价 attach，应先执行 python --version，再从对应版本的pdb 文档确认能力。

python -m pdb -p <pid>

attach 需要平台允许调试该进程。目标若阻塞在系统调用或 I/O 中，调试会等到下一条 Python 字节码执行，或在目标收到信号后才生效；“命令暂时没有提示符”不一定是网络问题。先确认 PID、用户、启动时间和解释器路径，再判断目标是否仍在 Python 执行阶段。

进入后先用 where、up、down 和只读表达式观察，不急于赋值。Python 3.13 起，pdb 在活动作用域中的名称赋值会立即影响运行代码；Python 3.14 还增加了异步停点和 backend 选择等行为。调试器中的实验性赋值可能修复一次请求，也可能破坏后续状态，所有共享环境操作都应记录动作并在隔离副本验证。

PID attach 不是网络服务，不提供 TLS、用户认证或远程租户隔离。跨主机时仍需先进入目标主机的受控 Shell，再由当地 Python 对 PID 附加；不能把 pdb -p 当作 debugpy 端口的替代写法。

从失败现象回到进程、源码和协议

pdb 看不到预期变量时，先用 where 确认当前帧，再用 up 或 down 移动。异常已被 except 转换、traceback 已释放或任务已重试时，原始帧可能不存在；修复是更靠近异常点进入 post-mortem 或保留受控 traceback，而不是在新请求中猜旧变量。

debugpy 端口存在但客户端立即断开时，查看 debugpy*.log 中的 DAP 握手与版本信息，核对连接方向、端口和客户端是否真使用 DAP。把普通 TCP 探针成功当成调试成功，会漏掉 initialize 与 attach 失败。修复后至少要看到断点验证和目标 PID 匹配。

attach 注入失败时，按目标用户、PID namespace、平台保护策略、解释器架构和 debugpy 所在环境逐层排查。不要先修改全局安全参数。若隔离副本能在同用户下 attach，而生产副本被策略拒绝，说明工具本身可用，剩下的是权限决策，不是安装问题。

父进程能停、worker 不能停时，比较父子 PID、启动方式、subProcess 配置时点和每个 debugpy 日志。若 worker 已在客户端连接前创建，晚到的配置无法追回早期执行；在隔离环境重启并提前设置策略，是比在线反复注入更可解释的验证。

断点显示未验证时，先比较 module.__file__、两端提交和 pathMappings。路径映射恢复后仍失败，再检查代码是否已经执行、进程是否正确、模块是否来自 wheel 或挂载副本。只有断点变为已验证且在目标 PID 命中，路径修复才算完成。

内存、日志和变量都按敏感数据处理

变量窗口可能直接展示 token、Cookie、数据库密码、请求正文和个人数据；求值表达式还可能调用具有副作用的函数。共享现场先检查结构、长度、类型和脱敏字段，避免展开整个对象；禁止把变量窗口截图、完整 traceback locals 或调试日志直接贴进公开工单。

debugpy 日志可能包含本机与远端路径、环境、命令行、PID、模块清单和协议消息。启用子进程调试时，每个 child 都可能产生独立日志，容量和敏感面都会扩张。日志目录使用最小权限与短保留期，传输前脱敏，到期删除并复查；需要长期保存的结论应提炼为构建身份、栈位置和修复验证，不保存整份内存上下文。

pdb 与 debugpy 都允许修改活动变量。现场若为了验证假设临时赋值，记录变量名、旧值类别、动作和恢复方式，不记录 secret 明文；随后在隔离副本用代码修复重放。一次调试会话中的手工修正不构成正式修复，也不能替代可评审变更。

清理必须覆盖进程、端口、代码和权限

本地实验结束先在 pdb 中 quit，或让 DAP 客户端继续目标后断开；再停止测试进程和 SSH 隧道。检查 5678 没有监听，删除 .debug/debugpy-logs，移除测试脚本和临时虚拟环境。Windows 清理前用 Get-NetTCPConnection -LocalPort 5678 -ErrorAction SilentlyContinue 确认 owner，Linux 使用 ss -ltnp 定位，不按端口盲杀不相关进程。

共享环境还要撤销临时 attach 权限、容器 capability、网络策略和跳板会话，恢复被摘流实例或按计划重建。若代码临时加入 ENABLE_DEBUGPY 或诊断依赖，合并前确认默认关闭、部署参数已删除、制品不再发布端口。只有 UI 断开而端口、权限或日志仍在，调试并没有结束。

清理后的再验证是：普通启动不等待客户端，越权身份不能 attach，其他主机不能直连调试端口，目标健康状态恢复，日志和临时文件数量回到基线。把这些结果和变更记录关联，而不是保存敏感变量内容。

团队治理从版本矩阵走到退出证明

团队应维护 Python 发行线、debugpy、IDE 客户端和目标平台的兼容矩阵。升级先在隔离环境重跑四组不变量：pdb 能在异常帧读取局部状态；debugpy 本地等待与非等待行为可区分；授权 PID attach 成功而越权失败；子进程与错误路径映射反例能稳定暴露问题。版本号变了但这些证据没有重新建立，不能视为升级完成。

权限按风险分层。本机 pdb 属于开发者权限；共享环境远程调试需要服务 owner 和短时网络入口；PID 注入需要平台调试权限；查看含真实数据的变量和日志还需要数据授权。工具链 owner 维护版本与模板，服务 owner 决定目标和暂停预算，安全 owner 管理临时入口与审计，数据 owner 决定转储和日志保留。

团队模板只提供默认关闭的调试入口、回环监听、日志目录、版本采集和清理动作，不把 0.0.0.0、永久 SYS_PTRACE、无限 wait_for_client 或全量环境输出包装成“开箱即用”。审计记录关联操作者、目标 PID、构建或提交、时限、批准人、端口和清理结果；变量值、密钥和用户数据不进入审计正文。

一次会话最终要能证明五件事：调试的是正确解释器与进程，源码与目标一致，暂停和表达式副作用在预算内，端口与权限已经撤销，日志和敏感现场已按策略保留或销毁。到这个程度，pdb 与 debugpy 才从个人排错技巧变成团队可重复、可审计、可退出的 Python 运行时调试能力。