调试这件事儿估计每个写 Python 的人都有一本血泪史。我早些年也是从 print 大法开始的后来项目越来越复杂有些 bug 只在特定参数组合下出现print 打印一堆中间变量还得自己在脑补执行流程。直到有一次在远程服务器上排查一个只在凌晨出现的数据处理任务没有图形界面我硬着头皮用 pdb 在命令行里把整个函数调用链捋了一遍才发现原来标准库自带的调试器这么能打。pdb 是 Python 内置的交互式调试器直接通过命令行驱动不需要安装第三方包也不挑操作系统特别适合线上临时排查、脚本开发和纯命令行工作流。这篇文章我会用它实际调试一个带 bug 的小程序把平时用到的命令、技巧和踩过的坑一次说清楚。1. 为什么我最终选择了命令行 pdb1.1 零依赖随时随地开聊很多人第一次听说 pdb 是在 IDE 的调试按钮旁边其实它早就在你装的 Python 解释器里躺着了。你不需要 pip install不需要配环境只要命令行能敲 python就能敲python -m pdb your_script.py。这在服务器排查问题时特别关键生产环境不敢乱装东西标准库自带的 pdb 就是最稳妥的选择。我记得有次线上的定时任务在深夜挂掉日志里只有一行IndexError: list index out of range但完整堆栈被后续任务冲掉了。我登录服务器后第一反应是找到那个脚本用python -m pdb重新跑一遍pdb 会在异常发生前自动进入调试状态我沿着调用栈往回看几分钟就定位到一个边界条件判断写反了。整个过程没有改动任何业务代码也没有往环境里塞任何依赖这种“零成本介入”是 IDE 调试器很难给你的。1.2 和 IDE 调试器比pdb 赢在哪输在哪我不是否定 IDE 调试器PyCharm 和 VS Code 的可视化断点、变量监视、逐帧堆栈确实好用。但我个人体会是pdb 在下面这几个场景里反而更顺手服务器和容器环境没有桌面只有 shellIDE 根本起不来。长时间运行的脚本比如爬虫、数据处理任务手动跑一遍成本高用 pdb 定位异常位置后可以立即修复。教学和理解代码pdb 的命令行交互强迫你逐行思考执行流比鼠标点点更能建立对代码执行顺序的直觉。配合终端复用工具tmux 里开一个 pdb 会话同时保留另一个面板查日志或文档效率不比 IDE 差。对比项IDE 调试器pdb是否需要安装需要下载安装 IDE不需要Python 内置图形界面有无纯命令行断点管理点击行号直观命令设置稍显繁琐服务器场景很难使用天然支持自定义扩展受 IDE 插件限制可通过 Python 代码自由定制脚本化调用弱强可嵌入代码当然pdb 的缺点也很明显在复杂工程里看变量关系不如 IDE 直观多文件跳转没有图形化支持新手初学命令记不住。但它作为兜底方案我认为所有 Python 开发者都应该掌握。2. pdb 基础用法从启动到第一条命令2.1 三种启动方式分别应对什么场景pdb 进入调试的方式大致有三种我在不同场景下会选不同的方式。第一种python -m pdb script.py。这种方式会让 Python 在执行脚本的第一行指令前就停下来适合从头开始完整跟踪一次脚本。如果脚本本身能正常结束你会看到一路执行到最后的输出如果脚本中途抛异常pdb 会自动停在异常处方便你查看当时的堆栈和变量。这意味着你不必预先在代码里加任何断点就能捕获异常现场。第二种breakpoint()。这是 Python 3.7 之后引入的内置函数等价于import pdb; pdb.set_trace()。我一般在写代码时就预埋几个关键位置比如循环的入口、处理完毕后的校验逻辑。运行到这一行pdb 就接管当前终端进入交互模式。这种方式的优势是断点精准不用重复输入脚本完整参数缺点是如果忘记删掉正常部署时就会卡住所以建议配合环境变量控制后面我会讲具体做法。第三种import pdb; pdb.set_trace()。和第二种本质一样但可以在任意 Python 版本使用而且能显式导入模块适合需要兼容旧版 Python 的脚本。我平时在调试第三方库内部逻辑时也会用这个姿势因为可以临时在 site-packages 里的源码中插入一行再运行。2.2 20 个高频命令覆盖 90% 调试需求刚开始接触 pdb 的人容易被命令数量劝退其实核心就 20 个左右而且大多有短路命令。我按使用频率列了这张表命令缩写作用示例listl打印当前行附近的源码lnextn执行下一行不进入函数nsteps执行下一行进入函数sreturnr执行到当前函数返回rcontinuec继续执行直到下一个断点cuntilunt跳过当前循环执行到指定行unt 12printp打印表达式值p len(items)pp无美化打印pp configargsa打印当前函数参数awherew打印调用栈wbreakb设置断点b 15clearcl清除断点cl 1condition无设置条件断点condition 1 item is Nonedisable无禁用断点disable 1enable无启用断点enable 1quitq退出调试器qinteract无启动 Python 交互 shellinteractcommands无指定断点触发时的命令commands 1display无每次停止时打印表达式display item!无执行 Python 语句!x 1使用技巧p和pp是最常用的调试时多打印中间值w能帮你理清调用链r适合跳出深层函数until在处理循环时比连续按n高效得多。2.3 断点可以玩出花行号、函数、条件断点是调试的核心。pdb 的break命令不仅可以按行号设置还能按函数名设置。比如break process_user会在函数第一行停下。这在没有源码行号的情况下特别方便比如调试第三方库时我常常break某个函数的入口。条件断点更能救命。调试循环时只有某个变量满足一定条件才需要看这时用condition 1 len(node.children) 0只有满足条件时才在 1 号断点停下。或者设置断点时直接写break 25 if total 42节省了无数次无意义的next。另一个容易被忽略的是ignore命令可以跳过某断点前面若干次触发比如ignore 1 100表示第 1 号断点前 100 次不触发适合排查循环 200 次后才会出现的诡异问题。不要小看这些功能。有一次调试一个批量导入脚本脚本处理到第 873 条数据时总会触发异常但前面的 872 条都正常。我直接在异常可能发生的那一行设置了一个条件断点break base.py:156 if index 872一次就定位到脏数据。如果没有条件断点光是按next或者一行行看变量能把人逼疯。2.4 不只能查还能改变量pdb 里执行p x只是读变量真正厉害的是!前缀它允许你在当前作用域执行任意 Python 表达式和赋值。打个比方你调试到某一步发现offset算错了但后面逻辑还依赖它可以!offset correct_value然后继续跑验证后续流程。还有interact命令会进入一个交互式 Python shell你可以在这里面任意试验代码退出后回到 pdb 上下文。这对于尝试重构一个函数体特别有用先贴一段临时逻辑验证不行再推倒重来。命令行调试的快乐就在于你能在同一进程里边查边改立刻看到结果。我之前调试一个图像处理脚本某段计算出来的gamma值始终偏小导致后面所有像素映射都不对。我没有急着改源码而是在 pdb 里用!gamma 2.2强行修正后继续跑发现输出恢复正常。于是判定问题出在 gamma 的计算步骤而不是后续应用逻辑节省了一大段排查时间。3. 实战案例揪出一个隐蔽的列表越界 bug理论说多了容易困我直接弄一个带 bug 的小程序用 pdb 从零走一遍。3.1 一个有问题的脚本假设我要处理一段数据逻辑大致是输入一个字符串列表把连续相同的元素压缩成“元素:次数”的形式输出。比如compress([a,a,b,c,c,c])应该输出[a:2,b:1,c:3]。我写一个缩小版源码def compress(items): result [] count 1 for i in range(len(items)): if items[i] items[i1]: count 1 else: result.append(f{items[i]}:{count}) count 1 return result if __name__ __main__: data [a, a, b, c, c, c] print(compress(data))如果你稍微熟悉列表会发现循环里比较了items[i]和items[i1]当i到最后一个索引时items[i1]必然越界。这就是典型的边界 bug平时写代码眼睛没盯住就会漏掉。3.2 用 pdb 观察每一步的状态我直接用python -m pdb bug.py跑一次pdb 会在第一行停下来。为了聚焦我设置一个函数断点break compress然后continue直接跳到compress函数入口。此时输入list会显示当前函数源码输入args能看到items参数的值是[a, a, b, c, c, c]。我用display i让每次停止时自动打印当前i再连续按next。前面几轮一切正常当i等于 5 时items[i]是c但items[i1]已经越界了所以执行if items[i] items[i1]就抛出IndexError。pdb 会在抛出异常的行停下此时输入where能看到当前调用栈compress被主程序调用病根一目了然。再输入p i确认是最后一个索引问题就定位了。实际会话像这样(Pdb) break compress Breakpoint 1 at /home/user/bug.py:3 (Pdb) continue /home/user/bug.py(4)compress() - for i in range(len(items)): (Pdb) args items [a, a, b, c, c, c] (Pdb) display i display i: 0 (Pdb) next /home/user/bug.py(5)compress() - if items[i] items[i1]: (Pdb) next /home/user/bug.py(4)compress() - for i in range(len(items)): (Pdb) next /home/user/bug.py(5)compress() - if items[i] items[i1]: (Pdb) i 1 (Pdb) next ... (Pdb) next /home/user/bug.py(5)compress() - if items[i] items[i1]: (Pdb) i 5 (Pdb) next IndexError: list index out of range /home/user/bug.py(5)compress() - if items[i] items[i1]: (Pdb) where /home/user/bug.py(11)module() - print(compress(data)) /home/user/bug.py(5)compress() - if items[i] items[i1]: (Pdb) p i 5这里的display i功能再怎么强调都不过分尤其在循环里。它能在每次停下时自动打印你关心的表达式省去手动输入p i的重复劳动。3.3 修复和验证修复方案很简单把循环范围从range(len(items))改为range(len(items) - 1)循环结束后再把最后一组元素追加进result。修改后再用python -m pdb -- bug.py或者直接运行脚本验证就能得到正确输出。def compress(items): if not items: return [] result [] count 1 for i in range(len(items) - 1): if items[i] items[i1]: count 1 else: result.append(f{items[i]}:{count}) count 1 result.append(f{items[-1]}:{count}) return result这个案例很基础但我想说明的是调试思路用 pdb 不是为了“找错”而找错而是通过逐步观察变量和流程理解代码真正做了什么。很多时候你盯着代码想象执行一万遍都不如亲自跑一遍来得快。4. 进阶技巧让 pdb 融入你的工作流基础命令会了接着讲几个能真正提升日常效率的进阶用法。4.1 不写脚本也能调试表达式在交互式 shell 或者 IPython 里想快速验证一段表达式是否能跑通可以用pdb.run()。比如import pdb pdb.run(compress([a, a, b]))这样会立刻进入 pdb 环境并且断在表达式执行的第一步。你可以逐步执行step进入函数内部查看状态。这对测试某个函数的具体分支很有用不用专门写测试文件。我也习惯用它来调试 machine learning 里的一些数据变换比如想确认某个正则替换后的中间结果直接在 pdb 里把那个表达式跑一遍再决定是否改代码。比重新跑一个训练脚本快得多。4.2 异常后进入倒放模式post_mortem是 pdb 的一个宝藏功能意思是“尸检”程序已经崩了但你仍然可以在崩溃现场查看堆栈和变量。常见的用法是在脚本里捕获异常后调用import pdb, traceback try: run_task() except Exception: traceback.print_exc() pdb.post_mortem()这样一来即使没有提前布置任何断点只要程序抛出未捕获异常pdb 就会自动接管让你在当前堆栈里检查args、locals()、表达式结果。python -m pdb script.py本身就是这个逻辑的简化版脚本异常退出时自动进入 post-mortem。在 CI 日志里看到异常然后本地执行相同命令复查比对着堆栈猜爽太多。有一次我就是在崩溃现场打印了一个列表的长度和内容才发现上游传入的是一个生成器被前面消费过一次后就为空了而堆栈里压根看不出这个状态。4.3 用 .pdbrc 打造自己的快捷键pdb 支持用户级配置文件.pdbrc和.bashrc一样每次启动会自动加载。你可以在里面定义 alias 设置别名比如alias hh help alias pv pp locals().get(self) alias vt pp self.__dict__还可以默认设置断点、定义自定义函数。我自己的.pdbrc里有一个别名用来打印当前函数内所有局部变量alias locals pp {k: v for k, v in locals().items() if not k.startswith(__)}这样每次输入locals就能快速观察当前作用域。给 pdb 做配置文件它就会越用越顺手跟你的编码习惯紧密绑定。4.4 环境变量控制断点开关前面提到breakpoint()容易忘记删。我在项目里常用一个封装import os import pdb if os.getenv(DEBUG): pdb.set_trace()这样生产环境只要不设置DEBUG环境变量断点就不会触发。配合python script.py和DEBUG1 python script.py两种运行方式就能做到“平时正常跑需要调试时同一份代码直接进断点”。比手动删加代码安全很多。如果临时想在某一行调试我会在代码里写breakpoint()跑完就删。但核心逻辑的调试入口我倾向于用环境变量控制因为排查问题时不需要反复改文件直接带环境变量重跑一遍就好。多服务场景下我还会用DEBUG_MODULEworker这样的变量只在指定模块里进入调试。4.5 用标准输入传递调试命令pdb 不是只能交互式使用也可以把命令通过管道喂给它。例如echo -e break compress\ncontinue\np items\nquit | python -m pdb bug.py这听起来有点“野”但在批量复现 bug 时很管用把一组 pdb 命令写进文件用重定向依次执行相当于半自动调试。真正写自动化测试时我会用pdb.Pdb(stdoutio.StringIO())实例化一个不接终端的调试器捕获输出并断言实现更精细的单元测试。比如我写过一个回归测试专门复现某次越界 bugimport io import pdb def test_compress_debug(): out io.StringIO() debugger pdb.Pdb(stdinio.StringIO(break compress\ncontinue\np len(items)\nquit\n), stdoutout) debugger.run(compress([a,a,b])) assert 3 in out.getvalue()虽然平时不会这么干但关键时刻能帮你把复现步骤固化下来。4.6 类对象和属性太多看不过来怎么办调试面向对象代码时p self往往刷出一大屏属性。我用得比较多的是pp self.__dict__只看实例的字典或者pp vars(self)效果一样。想检查某个类或实例的可调用属性可以用dir(self)。如果想在 pdb 里快速调用一个对象的辅助方法直接p self._validate()就行这比在代码里加日志方便很多。5. 常见问题与排查技巧实录5.1 断点为什么没触发最常见的原因是脚本在到达断点前就出了错或者断点所在行的代码根本没有被执行到。另外如果你在函数内部设置了断点但该函数从未被调用自然也不会停下。还有一个坑是标准输入被占用脚本里如果有input()读取用户输入启动 pdb 后输入会被调试命令系统截走表现为“按回车没反应”。解决方法是启动时用--区分脚本参数或者避免让 pdb 和脚本抢占 stdin。我会先看 pdb 是否真的进入了调试状态输入w打印当前堆栈然后确认断点是否被正确设置输入b查看断点列表最后观察程序是否走到了断点前的代码。排查断点不触发本质是“代码路径 断点设置 执行环境”三件事逐个核对。5.2 多线程程序只在主线程停下pdb 默认的set_trace()只影响当前线程。多线程执行时其他线程可能继续运行导致你无法观察全局状态。我的做法是在需要观察的子线程入口也加上pdb.set_trace()或者用breakpoint()配合线程名称条件判断。复杂情况下考虑用logging记录关键数据pdb 只做最后手段。也可以用threading模块给每个线程设置名字然后在 pdb 里p threading.current_thread().name确认当前停下来的是哪个线线程。想要调试某一个线程可以在该线程的执行函数里加断点并在break条件里加上线程名的判断。5.3 循环次数太多next 按到手指酸这种时候不要死磕next用条件断点更明智。比如每第 1000 次循环才停下就在循环体设置断点并添加条件for i in range(1000000): # 此处设置断点条件是 i 999 pass命令行可以这样设置break bug.py:8 if i 999。这样只会停在你关心的地方过程快很多。除了条件外还可以配合display i让调试器每次自动报告当前索引避免自己反复敲命令。5.4 pdb 输出的 Unicode 乱码在处理中文或 emoji 字符串时终端可能显示乱码。首先确保终端编码是 UTF-8Linux/macOS 一般没问题。Windows 上可能需要先执行chcp 65001再运行脚本。pdb 中打印中文行内常量时如果显示\uXXXX转义可以用p repr(变量)或pp查看但最终显示还取决于终端。我通常在 Windows 上会把终端切到 Windows Terminal然后确认环境变量PYTHONUTF81这样 Python 默认用 UTF-8 模式运行中文乱码的概率会小很多。5.5 pdb 和测试框架结合如果项目使用 pytest在用例里临时调试可以用pytest --pdb。它能在测试失败时自动进入 pdb比自己在代码里写断点更省事。也可以用pytest --pdb -x在第一个失败处停下来非常方便。对于 unittest则可以在tearDown里加pdb.set_trace()但不如 pytest 那条链路顺手。另外pytest 有个插件pytest-pdb可以控制进入 pdb 的时机比如只在某个标记的用例里进入。不过我一般懒得引额外依赖直接--pdb就够了。5.6 我踩过的一些坑pdb.set_trace()在循环里通常被反复触发如果你直接把它写在无限循环内打算用c继续执行却可能一直停在同一处。此时最好用条件断点或者用jump调整程序执行位置但jump可能造成状态不一致少用为妙。post_mortem需要保存的变量可能在异常处理后就被回收了。所以捕获异常时尽量保留traceback对象并尽快进入调试会话。使用python -m pdb时如果脚本需要读取标准输入调试命令和脚本输入会互相干扰。我一般会把脚本输入改从文件读取或者用pdb.run包一层。在 Windows 命令行里上箭头查看历史命令有时不生效需要配置 readline 后端。Windows 上 pdb 的体验确实差一截有条件可以在 WSL 里跑。5.7 一个小技巧配置 sticky 模式pdb 支持一些 UI 相关配置在较新的 Python 版本里可以通过.pdbrc或环境变量启用 sticky 风格让每次命令停止时都自动带出完整代码上下文类似 IDE 里的当前行高亮。但如果你终端比较老建议还是用简单的list替代。我个人更习惯关闭 sticky因为有时候输出太多反而干扰注意力。最后分享一点我现在的调试习惯写到最后分享一点我现在的使用习惯。日常开发我还是会用 IDE 调试器但只要是 SSH 登录、容器排查、或者线上问题的第一现场我脑子里第一反应就是python -m pdb script.py。它像一把永远随身带的小军刀也许不花哨但关键时刻真的很顶。建议你也花半小时把常用命令练熟一旦遇到 print 解决不了的“幽灵 bug”它一定能帮你节省大量时间。