怎么在VS Code中调试Python代码？断点与变量查看技巧

一、准备工作：插件安装与环境绑定

在进行任何调试之前，VS Code 需要明确两件事：由哪个调试插件驱动 Python 调试协议，以及由系统的哪个 Python 解释器环境（如虚拟环境 venv 或 Conda）来实际执行代码。

1. 安装官方扩展：在 VS Code 左侧活动栏点击扩展图标（快捷键 Ctrl+Shift+X 或 macOS 下的 Cmd+Shift+X），搜索并安装由 Microsoft 官方维护的 Python 扩展与 Python Debugger 扩展。
2. 选择 Python 解释器：按下 Ctrl+Shift+P 打开命令面板，输入并选择 Python: Select Interpreter，在列表中挑选安装了项目依赖的虚拟环境路径。编辑器右下角状态栏会显示当前所选解释器版本。
3. 准备待测代码：新建一个 Python 文件（例如 debug_demo.py），写入具有条件分支和循环逻辑的代码，以便观察状态变化。

# debug_demo.py - 用于调试演示的业务脚本
def calculate_order(user_info, raw_items):
    total = 0.0
    discount_rate = 1.0
    
    # 判断用户会员身份
    if user_info.get("is_vip"):
        discount_rate = 0.85
        
    for item in raw_items:
        item_total = item["price"] * item["count"]
        # 针对单件超过100元的商品额外扣减5元
        if item["price"] >= 100.0:
            item_total -= 5.0
        total += item_total
        
    final_amount = total * discount_rate
    return round(final_amount, 2)

if __name__ == "__main__":
    current_user = {"id": 1001, "name": "张三", "is_vip": True}
    cart = [
        {"name": "机械键盘", "price": 299.0, "count": 1},
        {"name": "鼠标垫", "price": 25.0, "count": 2},
        {"name": "无线鼠标", "price": 120.0, "count": 1}
    ]
    result = calculate_order(current_user, cart)
    print(f"最终订单结算金额: {result}")

二、断点类型与高级设置技巧

断点不仅是让程序简单地“停下来”，面对大量迭代或偶发异常时，盲目单步调试效率极低。VS Code 提供了多种断点形态以适配不同的排查场景：

1. 普通行断点（Standard Breakpoint）

操作方式：将鼠标悬停在编辑器行号左侧的灰色槽（Glyph Margin），点击即可生成一个鲜红色圆点；再次点击即可取消。快捷键为 F9。
触发规则：只要代码执行流推进到该行（执行前一刻），立即中断程序，将控制权交给调试器。

2. 条件表达式断点（Expression Condition）

操作方式：在已有断点上右击（或在行号左侧右击选择“添加条件断点 / Add Conditional Breakpoint”），在弹出的下拉菜单中选择 Expression，输入合法的 Python 表达式，例如 item['price'] > 200 或 len(raw_items) == 3。
触发规则：每次执行到该行时，调试器会在当前上下文隐式计算该表达式。仅当其返回结果判定为真（True）时才挂起，其他情况下直接放行，极大节省了在长循环中手动按“继续”的时间。

3. 命中次数断点（Hit Count）

操作方式：在断点右键菜单选择 Hit Count，输入整数或比较条件，例如 5 或 >= 10。
触发规则：调试器内部维护一个访问计数器。例如输入 10，则代码第 1 至 9 次穿过该行时不中断，恰好在第 10 次到达时暂停。常用于排查循环后期由于状态积累导致的溢出或越界问题。

4. 日志点（Logpoint）

操作方式：在行号左侧空白处右击，选择“添加记录点 / Add Logpoint...”，输入日志模板。支持在大括号 {} 内插入变量表达式，例如：处理商品: {item['name']}, 单价: {item['price']}。
触发规则：显示为红色菱形。代码运行到此不会暂停，而是在“调试控制台（Debug Console）”中输出解析后的文本。这是完全无侵入的调试手段，无需在业务代码中临时写 print() 并承担调试后忘记删除的风险。

三、调试工具条与单步控制技巧

按 F5 启动调试后，VS Code 窗口顶部中央会浮现一个由 6 个按钮组成的控制条。同时，代码行号旁边会出现黄色箭头，指示下一行即将被执行的代码（该行尚未实际运行）。

四、变量查看与运行时状态排查技巧

代码暂停后，调试的真正目的通常是看清内存中各变量是否符合预期。VS Code 提供了四个互为补充的状态检视维度：

1. 编辑器内原位悬停（Hover Inspect）

在断点暂停状态下，直接将鼠标悬停在编辑器中的任何变量名上方，就会弹出一个轻量信息框。它能展示该对象的类型、基础值或嵌套字典/列表的内部结构。对于结构简单的数据项，原位悬停是最直接、最少干扰视线的查看方式。

2. 变量面板（Variables Panel）：局部与全局状态

在左侧调试栏展开 Variables：

• Locals（局部变量）：显示当前函数栈帧内的所有局部变量。每当步过代码时，发生数值变化的变量会以醒目的颜色高亮。右击变量选择 Set Value，甚至可以直接修改内存中的值，用于快速验证临时的边界修复。
• Globals（全局变量）：展示模块级别的变量与内置属性（如 __file__、__name__ 等）。

3. 监视窗口（Watch Window）：定制复杂表达式

当局部变量列表过于冗长，或者需要持续跟踪复合运算结果时，可以使用 Watch 窗口：

• 点击面板右上角的 + 号，输入任何合法的 Python 表达式，例如 len(cart)、item['price'] * item['count'] 或 current_user.get('is_vip')。
• 随着你在代码中单步前行，Watch 窗口会自动重新求值并实时刷新结果。若变量尚未初始化，则会优雅显示 NameError，一旦进入作用域便立即显现。

4. 调用栈（Call Stack）：多层溯源

在复杂的嵌套调用或框架（如 Django/FastAPI）中，当程序在深层函数报错或暂停时，Call Stack 面板会从上到下列出完整的调用链条。点击任意一层历史帧，编辑器会同步跳转到该层的调用代码行，且 Variables 面板也会切换为那一帧当刻的上下文数据。

5. 调试控制台（Debug Console）：交互式 REPL 求值

底部面板切换至 Debug Console。当断点暂停时，控制台底部的输入框便是一个挂接在当前断点上下文中的原生 Python REPL：

• 可以直接输入 type(item)、item.keys() 查看对象自省信息。
• 可以执行复杂的切片、列表推导式甚至导入临时模块（如 import json; json.dumps(user_info)）。
• 可以临时修改变量（例如输入 discount_rate = 0.5 并回车），后续单步执行就会以修改后的值继续运行。

五、常见调试异常与工程化 launch.json 配置

在实际项目调试中，可能会遇到断点未生效或需要自定义启动参数的场景。以下是两类最典型的应对方法：

1. 断点变灰（Unverified Breakpoint）排查

启动调试后，若红色的断点图标变成空心灰色圆圈，并提示 Unverified breakpoint，说明调试器无法将源文件代码行映射到正在运行的字节码上。常见原因与解决办法包括：

• 解释器环境不匹配：运行的 Python 进程所加载的文件与编辑器打开的文件不是同一个副本（如符号链接未解析、Docker 容器或远程 SSH 路径未做路径映射 pathMappings）。
• 代码尚未被执行流加载：在模块导入阶段，某些仅在特定条件分支下才加载的代码文件在初始时刻尚未注册，当触发相关路由或函数调用后断点会自动点亮。
• 启用了代码混淆或字节码缓存异常：清理项目目录下的 __pycache__ 文件夹，确保 Python 读取的是最新的源码文件。

2. 使用 launch.json 定制复杂启动参数

对于需要传入命令行参数（sys.argv）、注入环境变量或指定特定工作目录（cwd）的工程项目，直接按 F5 无法满足需求。此时应在项目根目录生成 .vscode/launch.json：

1. 切换到左侧“运行和调试”视图（Ctrl+Shift+D），点击 create a launch.json file。
2. 选择 Python Debugger -> Python File。
3. 在生成的 JSON 文件中添加 args 与 env 等配置项，示例结构如下：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: 调试当前文件(带参数与环境变量)",
            "type": "debugpy",
            "request": "launch",
            "program": "${file}",
            "console": "integratedTerminal",
            "cwd": "${workspaceFolder}",
            "args": [
                "--config", "config/dev.yaml",
                "--batch-size", "64"
            ],
            "env": {
                "DEBUG_MODE": "True",
                "ENV_NAME": "development"
            },
            "justMyCode": true
        }
    ]
}

通过合理运用行断点、条件断点以及调试控制台的动态求值，开发者能够在无需重复在业务代码中插入临时输出语句的前提下，精准定位逻辑缺陷与边界异常。