---

Python PDB 快速上手指南：告别盲猜，掌控代码执行流

在软件开发过程中，Bug 是不可避免的“伙伴”。当代码行为不符合预期时，我们通常会采取两种方式来找出问题：一种是打印（print）大法，在代码各处插入打印语句，观察变量的值和执行流程；另一种是使用调试器（Debugger），暂停代码执行，逐行查看，检查状态，动态修改变量甚至执行代码。

虽然打印大法在简单场景下非常有效，但面对复杂的 Bug、深层次的调用栈或难以重现的问题时，它就显得捉襟见肘了。此时，一个强大的调试器就成为了我们手中不可或缺的利剑。

Python 标准库中提供了一个命令行调试器——PDB (Python DeBugger)。它虽然不像现代 IDE 中的图形界面调试器那样直观，但其强大之处在于无处不在（Python 环境自带）、轻量级、以及在某些特定场景下（如调试命令行脚本、远程服务器上的代码、或在没有 GUI 的环境中）的无可替代性。掌握 PDB 的基本用法，能极大地提升你解决问题的效率。

本文将带你快速上手 PDB，让你告别盲目猜测，精准定位 Bug。

为什么选择 PDB？

• 无需安装： PDB 是 Python 标准库的一部分，开箱即用。
• 通用性强： 适用于任何 Python 环境，无论是在本地终端、服务器还是其他特殊环境。
• 轻量级： 不依赖图形界面，启动快速，资源占用少。
• 基础牢固： 了解 PDB 的工作原理有助于更好地理解其他调试工具。
• 脚本调试利器： 特别适合调试独立的 Python 脚本或命令行工具。

虽然 IDE 调试器（如 PyCharm, VS Code 的内置调试器）提供了更友好的用户界面和更多高级功能，但 PDB 依然是每一个 Python 开发者都应该掌握的基础技能。

如何启动 PDB？

有两种主要的方式来启动 PDB 调试会话：

方法一：从脚本开头开始调试

这是最简单的方式，适合当你怀疑问题可能出现在脚本的早期阶段，或者你想从头开始观察整个执行流程时。

在终端中运行你的 Python 脚本时，加上 -m pdb 参数：

bash
python -m pdb your_script.py

执行这个命令后，PDB 会启动，并在你的脚本第一行代码执行前暂停。你会看到类似这样的输出：

“`

/path/to/your_script.py(1)()
-> # 这是一个示例脚本
(Pdb)
“`

> /path/to/your_script.py(1)<module>() 表示当前暂停的位置，文件路径、行号以及当前作用域（<module> 表示顶层模块）。
(Pdb) 是 PDB 的命令提示符，表示 PDB 正在等待你输入命令。

方法二：在代码中设置断点

这种方法更为常用和灵活。你可以在代码中你认为可能出错的位置或者你想要开始检查的位置插入一个“断点”。当 Python 执行到这个位置时，PDB 会自动启动并暂停。

设置断点的方式是插入以下两行代码：

python
import pdb
pdb.set_trace()

将这两行代码放在你希望程序暂停的位置之前。例如：

“`python
def calculate_something(data):
result = 0
for item in data:
# 假设你怀疑问题可能出现在这里
import pdb
pdb.set_trace()
result += process(item) # process 是另一个函数

return result

def process(x):
# 这是一个示例函数，可能有 Bug
return x * 2 + 1

my_list = [1, 2, 3, 4]
final_result = calculate_something(my_list)
print(final_result)

“`

运行这个脚本：

bash
python your_script.py

当程序执行到 pdb.set_trace() 那一行时，它会暂停，并进入 PDB 交互模式：

“`

/path/to/your_script.py(9)calculate_something()
-> result += process(item)
(Pdb)
“`

现在，你可以开始检查当前的变量值，单步执行代码等。

重要提示： 在完成调试后，记得删除或注释掉 import pdb; pdb.set_trace() 这两行代码，以免影响正常的程序运行。

PDB 的核心命令

一旦进入 (Pdb) 提示符，你就需要输入命令来控制程序的执行和查看信息。以下是一些最常用和最重要的 PDB 命令：

1. h (help)

   • 作用： 查看 PDB 命令的帮助信息。
   • 用法：
     • h: 显示所有命令的简短列表。
     • h <command>: 显示特定命令（如 h p, h n）的详细帮助。
   • 示例：
     (Pdb) h

2. q (quit)

   • 作用： 立即退出 PDB 调试器，终止程序执行。
   • 用法： q
   • 示例：
     (Pdb) q

3. c (continue)

   • 作用： 继续正常执行程序，直到遇到下一个断点或程序结束。
   • 用法： c
   • 示例：
     (Pdb) c

4. n (next)

   • 作用： 执行当前行的下一行代码。如果当前行是一个函数调用，n 命令会执行整个函数调用，然后停在调用后的下一行。它不会“进入”被调用的函数内部。
   • 用法： n
   • 示例：
     (Pdb) n

5. s (step)

   • 作用： 执行当前行的下一行代码。如果当前行是一个函数调用，s 命令会“步进”到被调用的函数的第一行代码内部暂停。
   • 用法： s
   • 示例：
     (Pdb) s
   • n 和 s 的区别： 理解 n 和 s 的区别非常重要。想象你的代码是一个流程图，n 就像跳过一个子流程块，直接到块的出口；s 就像进入子流程块内部，逐个执行其中的步骤。

6. r (return)

   • 作用： 继续执行，直到当前函数返回。
   • 用法： r
   • 示例：
     (Pdb) r
   • 当你意外地使用 s 进入了一个你不想深入调试的函数时，r 命令可以帮助你快速跳出当前函数，回到调用它的地方。

7. p (print)

   • 作用： 打印某个变量的值或执行某个 Python 表达式并打印结果。这是调试中最常用的命令之一。
   • 用法： p <expression>
   • 示例：
     假设你在调试一个函数，其中有一个变量 my_variable 和一个列表 my_list。
     (Pdb) p my_variable # 打印变量 my_variable 的值
10
(Pdb) p my_list[2] # 打印列表 my_list 索引为 2 的元素
'hello'
(Pdb) p my_variable * 2 + 5 # 执行表达式并打印结果
25
(Pdb) p locals() # 打印当前作用域的所有局部变量
{'item': 1, 'result': 0, 'data': [1, 2, 3, 4]} # 示例输出
   • 你可以使用 p 执行任何合法的 Python 表达式，包括函数调用（请小心，函数调用可能会改变程序状态）。

8. l (list)

   • 作用： 显示当前执行位置周围的源代码。默认显示当前行前后的几行。当前执行的行会用 -> 标记出来。
   • 用法： l
   • 示例：
     (Pdb) l
...
6 result = 0
7 for item in data:
8 import pdb
9 pdb.set_trace()
10 -> result += process(item)
11
12 return result
...
(Pdb)
   • 你也可以使用 l first, last 来显示指定行范围的代码，例如 l 1, 10 显示第 1 行到第 10 行的代码。

9. b (breakpoint)

   • 作用： 设置新的断点，列出已有的断点，或清除断点。
   • 用法：
     • b: 列出所有断点及其状态。
     • b <line_number>: 在当前文件的指定行设置断点。
     • b <file>:<line_number>: 在指定文件的指定行设置断点。
     • b <function_name>: 在指定函数的第一条可执行语句处设置断点。
     • b <line_number>, <condition>: 设置条件断点，只有当条件表达式为 True 时才暂停。
   • 清除断点：
     • cl: 清除所有断点（会询问确认）。
     • cl <breakpoint_number>: 清除指定编号的断点（b 命令列出时会显示编号）。
   • 示例：
     (Pdb) b 15 # 在当前文件第 15 行设置断点
Breakpoint 1 at /path/to/your_script.py:15
(Pdb) b process # 在 process 函数入口设置断点
Breakpoint 2 at /path/to/your_script.py:15 (the same line)
(Pdb) b # 列出断点
Num Type Disp Enb Where
1 breakpoint keep yes at /path/to/your_script.py:15
2 breakpoint keep yes at /path/to/your_script.py:15 (process)
(Pdb) cl 1 # 清除编号为 1 的断点
Cleared: 1
(Pdb) cl # 清除所有断点
Clear all breakpoints? (y or n) y
Cleared all breakpoints
(Pdb)

10. a (args)

    • 作用： 打印当前函数的参数名及其值。
    • 用法： a
    • 示例：
      当你在 calculate_something 函数内部暂停时：
      (Pdb) a
data = [1, 2, 3, 4]
(Pdb)

11. w (where)

    • 作用： 打印当前所在的调用栈（Call Stack）。显示程序是如何一步步调用到当前位置的。
    • 用法： w
    • 示例：
      (Pdb) w
/path/to/your_script.py(19)<module>()
-> final_result = calculate_something(my_list)
/path/to/your_script.py(6)calculate_something()
-> for item in data:
> /path/to/your_script.py(9)calculate_something()
-> pdb.set_trace()
(Pdb)
      输出从最新的调用（当前位置）开始向上追溯，-> 标记的是当前行。

12. 空行 (Enter)

    • 作用： 重复执行上一次输入的非空命令。对于频繁使用 n 或 s 单步执行非常方便。
    • 用法： 直接按 Enter 键。

PDB 调试工作流示例

让我们通过一个简单的例子来演示如何使用 PDB 找到 Bug。

假设我们有以下脚本 example_bug.py：

“`python

example_bug.py

def multiply(x, y):
“””Multiplies two numbers.”””
# Potential bug: maybe I intended to add?
return x * y

def process_list(numbers):
“””Processes a list of numbers.”””
total = 0
for num in numbers:
# We want to double each number and add it to total
doubled = multiply(num, 2)
total += doubled
# The total calculation might be wrong
return total

my_numbers = [1, 2, 3, 4, 5]
result = process_list(my_numbers)
print(f”The final result is: {result}”)

Expected output: (12 + 22 + 32 + 42 + 5*2) = (2 + 4 + 6 + 8 + 10) = 30

Actual output (with the bug): (12 + 22 + 32 + 42 + 5*2) = (2 + 4 + 6 + 8 + 10) = 30. Hmm, the bug isn’t in multiply.

Let’s assume the bug is in the total calculation and we expect (1+2+3+4+5)2 = 152 = 30.

Wait, multiply(num, 2) is correct. The bug is in the concept of the expected output in my head!

Let’s change the multiply function to have a real bug:

def multiply(x, y):
“””Multiplies two numbers.”””
return x + y # Intended to multiply, but wrote add!

Now the expected output is still 30 if we intended (1+2+3+4+5)2 = 152 = 30.

But the actual output with x + y will be ((1+2) + (2+2) + (3+2) + (4+2) + (5+2)) = (3+4+5+6+7) = 25.

Let’s debug this!

Insert breakpoint here:

import pdb
pdb.set_trace()

my_numbers = [1, 2, 3, 4, 5]
result = process_list(my_numbers)
print(f”The final result is: {result}”)
“`

1. 运行脚本，进入 PDB:
   bash
python example_bug.py
   程序会在 pdb.set_trace() 处暂停，进入 PDB 提示符。

2. 查看当前位置：
   > /path/to/example_bug.py(31)<module>()
-> my_numbers = [1, 2, 3, 4, 5]
(Pdb) l
...
27
28 # Insert breakpoint here:
29 import pdb
30 pdb.set_trace()
31-> my_numbers = [1, 2, 3, 4, 5]
32 result = process_list(my_numbers)
33 print(f"The final result is: {result}")
34
[EOF]
(Pdb)
   我们看到程序暂停在第 31 行。

3. 单步执行到 process_list 调用：
   (Pdb) n # 执行 31 行
> /path/to/example_bug.py(32)<module>()
-> result = process_list(my_numbers)
(Pdb) n # 执行 32 行，步过 process_list 调用 (因为它不是内置函数，n 会进入)
# Wait, n will step into user-defined functions. Let's use s instead if we want to go line by line inside!
(Pdb) s # 执行 32 行，步进到 process_list 内部
> /path/to/example_bug.py(13)process_list()
-> total = 0
(Pdb) l # 查看 process_list 函数代码
...
10 def process_list(numbers):
11 """Processes a list of numbers."""
12 total = 0
13-> total = 0
14 for num in numbers:
15 # We want to double each number and add it to total
16 doubled = multiply(num, 2)
17 total += doubled
18 # The total calculation might be wrong
19 return total
...
(Pdb)
   我们已经进入了 process_list 函数，并暂停在第一行。

4. 查看参数和局部变量：
   (Pdb) a # 查看函数参数
numbers = [1, 2, 3, 4, 5]
(Pdb) p total # 查看局部变量 total 的值
0
(Pdb)
   参数和 total 的初始值符合预期。

5. 进入循环，检查关键计算：
   我们想看看 multiply(num, 2) 的返回值以及 total += doubled 这一步是否正确。
   (Pdb) n # 执行 total = 0
> /path/to/example_bug.py(14)process_list()
-> for num in numbers:
(Pdb) n # 执行 for 循环的第一轮，获取 num
> /path/to/example_bug.py(16)process_list()
-> doubled = multiply(num, 2)
(Pdb) p num # 检查当前的 num 值
1
(Pdb) s # 步进到 multiply 函数内部
> /path/to/example_bug.py(5)multiply()
-> return x + y # Intended to multiply, but wrote add!
(Pdb) a # 查看 multiply 的参数
x = 1
y = 2
(Pdb) p x + y # 提前计算一下 return 的值
3
(Pdb) r # 退出 multiply 函数
--Return--
> /path/to/example_bug.py(5)multiply()->3
-> return x + y # Intended to multiply, but wrote add!
(Pdb) p doubled # 检查 multiply 的返回值，赋值给了 doubled
3
(Pdb) l # 回到 process_list 函数，看看当前行
...
14 for num in numbers:
15 # We want to double each number and add it to total
16 doubled = multiply(num, 2)
17-> total += doubled
18 # The total calculation might be wrong
19 return total
20
...
(Pdb) p total # 检查 total 的当前值
0
(Pdb) n # 执行 total += doubled (total += 3)
> /path/to/example_bug.py(14)process_list()
-> for num in numbers:
(Pdb) p total # 再次检查 total 的值
3
(Pdb) n # 进入循环下一轮，获取 num
> /path/to/example_bug.py(16)process_list()
-> doubled = multiply(num, 2)
(Pdb) p num # 检查当前的 num 值
2
(Pdb) s # 步进到 multiply 函数内部
> /path/to/example_bug.py(5)multiply()
-> return x + y # Intended to multiply, but wrote add!
(Pdb) a
x = 2
y = 2
(Pdb) p x + y
4
(Pdb) r # 退出 multiply
--Return--
> /path/to/example_bug.py(5)multiply()->4
-> return x + y # Intended to multiply, but wrote add!
(Pdb) p doubled # multiply 的返回值是 4
4
(Pdb) n # 执行 total += doubled (total += 4)
> /path/to/example_bug.py(14)process_list()
-> for num in numbers:
(Pdb) p total # 检查 total 的值
7 # 3 + 4 = 7. Ah-ha! The total is not doubling the numbers as expected.
   通过上面的单步调试和变量检查，我们发现 multiply(num, 2) 返回的不是 num * 2，而是 num + 2！这证明了 Bug 在 multiply 函数中。

6. 修复 Bug 并退出：
   现在我们找到了 Bug，可以输入 q 退出 PDB，然后去修改 multiply 函数，将 return x + y 改回 return x * y。

PDB 进阶技巧（简述）

• 重复命令： 在 PDB 提示符下直接按 Enter 键会重复上一次执行的命令（通常是 n 或 s），这对于单步执行非常方便。
• 修改变量： 在 PDB 提示符下，你可以直接给变量赋值来修改程序状态。例如：(Pdb) total = 100。请谨慎使用此功能，因为它可能会引入新的问题，但有时对于测试特定场景很有用。
• 执行多行代码： 如果你想执行多行 Python 代码，可以在第一行前面加上 ! 或者使用 interact 命令进入一个交互式 Python 会话。
• 条件断点： 使用 b <line_number>, <condition> 可以设置条件断点，例如 b 17, num == 3 会在第 17 行暂停，但只有当 num 的值等于 3 时才触发。这对于在大量数据中定位特定情况的 Bug 非常有用。
• 忽略次数： b <line_number>, , <ignore_count> 可以设置忽略断点前几次触发，例如 b 17, , 5 会在前 5 次到达第 17 行时不暂停，从第 6 次开始暂停。
• 命令别名： 可以使用 alias 命令为常用的 PDB 命令或命令组合创建别名，提高效率。

PDB vs. IDE 调试器

特性	PDB (命令行调试器)	IDE 调试器 (如 PyCharm, VS Code)
安装	Python 自带，无需额外安装	需要安装 IDE 或相应的扩展
用户界面	命令行界面	图形用户界面 (GUI)，可视化更强
易用性	初学阶段需要记忆命令，上手门槛稍高	通常更直观，易于查看变量、调用栈等
功能	核心调试功能 (断点, 单步, 查看/修改变量)	更多高级功能 (表达式求值窗口, 多线程调试, 条件断点配置更便捷, 集成测试运行等)
适用场景	命令行脚本, 没有 GUI 环境, 远程调试, 轻量级快速调试	大型项目开发, 需要频繁调试, 复杂的调试场景
性能/资源	轻量级，启动快	通常资源占用更高，启动相对慢

掌握 PDB 并不意味着要放弃 IDE 调试器。它们是互补的工具。PDB 在其擅长的领域（如快速检查脚本、服务器端调试、无 GUI 环境）表现出色，而 IDE 调试器则在日常的大型项目开发中提供更便捷、全面的调试体验。

总结

PDB 作为 Python 标准库自带的命令行调试器，是 Python 开发者必备的基础技能之一。通过本文的学习，你应该掌握了以下核心内容：

• 理解 PDB 的作用和优势。
• 学会两种启动 PDB 的方法：python -m pdb script.py 和 import pdb; pdb.set_trace()。
• 熟悉并能运用 PDB 的核心命令，如 h, q, c, n, s, r, p, l, b, a, w。
• 理解 n 和 s 在单步执行时的关键区别。
• 了解如何使用 p 命令查看变量和执行表达式。
• 了解如何设置和管理断点 (b, cl)。
• 能够运用这些命令进行基本的 Bug 定位和调试。

调试是一个需要实践才能精通的技能。建议你立即尝试用 PDB 调试一下你最近遇到的 Bug 或者写一个简单的脚本，故意制造一些错误，然后使用 PDB 来找出它们。多加练习，你将能更高效地解决问题，写出更健壮的代码。

告别 Print 大法，拥抱 PDB，让你的调试之路更加顺畅！