怎么在 VS Code 中使用调试模式运行 Python 脚本

一、准备工作：确保调试环境就绪

在开始调试之前，请确保 VS Code 中已完成基础环境配置。VS Code 本身是一个通用编辑器，其对 Python 代码的语法高亮、自动补全与调试支持依赖官方扩展与选定的 Python 解释器。

1. 确认安装 Python 官方扩展

打开 VS Code，点击左侧活动栏的“扩展”图标（快捷键 Ctrl+Shift+X 或 macOS 下的 Cmd+Shift+X），在搜索栏输入 Python。确保由 Microsoft 官方发布的 Python 扩展已处于“已启用”状态。现代版本的 Python 扩展已将 debugpy 作为默认调试内核绑定安装，无需单独下载调试引擎。

2. 选择正确的 Python 解释器

调试时使用的运行环境必须包含脚本所需的依赖包。按快捷键 Ctrl+Shift+P（macOS 为 Cmd+Shift+P）调出命令面板，输入并选择：

Python: Select Interpreter

在弹出的列表中，根据项目需要选择对应的虚拟环境（例如 .venv、conda env）或全局解释器。选定后，VS Code 右下角的状态栏会常驻显示当前 Python 版本与环境名称。

3. 准备演示脚本

为了直观感受断点暂停与变量检查，我们在工作区中新建一个名为 debug_demo.py 的文件，写入以下具有函数调用与循环结构的示例代码：

def calculate_discount(price, discount_rate):
    # 计算折后价
    reduced_amount = price * discount_rate
    final_price = price - reduced_amount
    return round(final_price, 2)

def main():
    cart_items = [
        {"name": "机械键盘", "price": 399.0},
        {"name": "无线鼠标", "price": 129.0},
        {"name": "显示器支架", "price": 249.0},
    ]
    rate = 0.85
    settlement = []

    for item in cart_items:
        current_price = item["price"]
        discounted = calculate_discount(current_price, rate)
        settlement.append({"name": item["name"], "pay": discounted})

    total_cost = sum(x["pay"] for x in settlement)
    print(f"结算完成，总计应付：{total_cost} 元")

if __name__ == "__main__":
    main()

二、核心操作：四步快速进入调试模式

对于单文件 Python 脚本，VS Code 支持免配置即时调试。掌握以下四个动作即可完成常规排查：

步骤一：在代码行号旁设置断点

将光标移至编辑器左侧行号与代码之间的空白区域（即装订线/Gutter）。当鼠标悬停时会浮现一个半透明的红点。在此处单击鼠标左键，即可固定一个鲜红色的实心圆点，这便是断点（Breakpoint）。

例如在示例代码中，我们在第 18 行的 discounted = calculate_discount(current_price, rate) 处设置断点。断点的作用是告知调试器：当程序执行到达该语句之前，必须暂停执行并将控制权交由开发者。

步骤二：选择调试方式启动

启动调试有三种便捷途径，效果完全等价：

• 最常用快捷键：在当前编辑的 Python 文件窗口中，直接按下键盘上的 F5。
• 编辑器右上角按钮：在编辑器窗口右上角找到运行图标旁的下拉小三角形，点击展开并选择 “调试 Python 文件”（Debug Python File）。
• 左侧运行与调试面板：点击活动栏的“运行与调试”图标（带有虫子和播放符号的图标，快捷键 Ctrl+Shift+D / Cmd+Shift+D），点击上方的“运行和调试”大按钮。

步骤三：初次启动时的配置确认

如果是该工作区第一次通过 F5 启动且尚未配置 launch.json，VS Code 会在顶部正中央弹出环境提示：

1. 在“选择调试器”中选择 Python Debugger；
2. 在接下来的调试模板中选择 Python 文件（Python File）- 调试当前活动文件。

此时，底部的集成终端会自动启动，VS Code 借助 debugpy 模块挂载当前 Python 进程并开启监听。

步骤四：命中断点与确认暂停

脚本启动后，执行流在到达第 18 行代码之前停住。此时界面会出现明显的视觉变化：

• 行高亮标注：原本的红点内部出现黄色标记，且第 18 行整行被亮黄色背景覆盖，左侧装订线出现黄色指向箭头。这表明程序正悬停在这一行，该行代码尚未执行。
• 浮动调试控制条：窗口顶部正中央出现包含播放、跳过、进入、停止等按钮的半透明悬浮控制栏。
• 左侧调试面板被激活：活动栏自动切至“运行与调试”，面板中呈现当前时刻的内存数据。

三、运行时掌控：调试工具栏与四大调试面板

程序在断点暂停后，开发者便获得了对运行状态的完全观测与调度权。此时需要协同使用浮动工具栏与侧边栏四大监控视图。

1. 浮动工具栏六大控制命令

2. 四大核心观测面板

在暂停状态下，左侧侧边栏的“运行与调试”视图提供了四个核心观测区域：

• 变量 (Variables)：分为 Locals（当前栈帧局部变量）与 Globals（模块全局变量）。展开 Locals 可以看到当前轮次中 item、current_price 与 rate 的实际数值。更强大的是，双击任意变量的值，可以直接在输入框中修改它，随后按回车，Python 将立刻使用修改后的值继续运行。
• 监视 (Watch)：点击面板右上角的“+”号，可以输入任意合法的 Python 表达式（如 current_price > 200 或 len(settlement)）。每当你按 F10 单步前进时，监视面板会自动求值并更新结果，省去了在源码中临时编写 print() 的繁琐。
• 调用堆栈 (Call Stack)：显示到达当前代码行的完整函数调用链。例如在 calculate_discount 内部暂停时，堆栈会显示第 1 帧是 calculate_discount，第 2 帧是 main。直接在列表中单击 main，编辑区和变量区会自动切回 main 函数的作用域，让你同时核对调用者的入参状态。
• 断点 (Breakpoints)：列出所有设置过的断点。你可以通过复选框临时禁用某个断点而无需将其从代码行删除；右键某个断点还可以设置条件断点（Conditional Breakpoint），例如填写条件 current_price > 300，只有当当前商品价格大于 300 时，程序才会被拦截暂停。

3. 调试控制台 (Debug Console)

点击 VS Code 下方面板区域中的 “调试控制台”（Debug Console） 标签页。这是一个连接到当前暂停断点环境的实时交互式 REPL。在底部的输入行输入任何代码，例如 item["name"].startswith("机械")，回车后即可即时获得布尔结果。这对于在复杂数据结构中现场测试提取逻辑极其高效。

四、进阶场景：配置 launch.json 应对复杂工程需求

使用 F5 快速调试适合单个简单脚本。但当项目遇到需要传入命令行参数（sys.argv）、指定工作目录（os.getcwd()）、加载环境变量或以模块方式启动时，临时会话就无法满足需求。此时应当创建 launch.json 配置文件。

1. 一键生成 launch.json 文件

在左侧“运行与调试”面板中，如果当前没有任何调试配置，点击蓝色文字链接 “创建 launch.json 文件”（create a launch.json file）。VS Code 会在当前项目根目录下自动创建 .vscode/launch.json 文件。

2. 核心参数结构解析

一个标准的 Python 调试配置文件如下所示：

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: 当前文件调试",
            "type": "debugpy",
            "request": "launch",
            "program": "${file}",
            "console": "integratedTerminal",
            "justMyCode": true
        },
        {
            "name": "Python: 带参分析任务",
            "type": "debugpy",
            "request": "launch",
            "program": "${workspaceFolder}/scripts/process.py",
            "args": ["--input", "data/raw.csv", "--workers", "4"],
            "cwd": "${workspaceFolder}",
            "env": {"PYTHONUNBUFFERED": "1", "DEBUG_MODE": "True"},
            "console": "integratedTerminal",
            "justMyCode": true
        }
    ]
}

3. 常见进阶配置项详解

• program：指定要运行的目标脚本绝对或相对路径。使用 "${file}" 代表调试当前正打开的文件，使用固定路径如 "${workspaceFolder}/main.py" 可确保无论光标停在哪个文件，按 F5 都始终启动项目主入口。
• args：传递命令行参数。格式为字符串数组，例如 ["--mode", "eval", "--batch-size", "32"]，脚本执行时会自动解析进 sys.argv。
• cwd：设置当前工作目录（Current Working Directory）。如果不显式配置，工作目录默认可能不是项目根目录，从而导致脚本中的相对路径读取（如 open("data/items.json")）抛出 FileNotFoundError。将其固定为 "${workspaceFolder}" 能彻底避免此问题。
• env：注入局部环境变量。可在字典中传入自定义变量键值对，无需改动操作系统的全局环境。若有现成的 .env 文件，还可使用 "envFile": "${workspaceFolder}/.env" 自动载入。
• module：如果项目是通过 python -m my_package.server 启动的包模块，可以将 program 替换为 "module": "my_package.server"，以正确处理包内部的相对导入（如 from .utils import check）。
• justMyCode：默认为 true。当其为 true 时，单步调试（F11）只会进入开发者自己编写的代码，遇到标准库（如 json、re）或第三方包（如 requests、pandas）会自动单步跳过；若确实需要调试第三方库源码，将其改为 false 即可。

五、常见问题排查与避坑指南

在日常使用调试模式时，读者常会遇到断点不命中或运行报错等情况。以下为典型场景的排查路径：

1. 断点变灰或空心，提示“未验证的断点”（Unverified Breakpoint）

原因与解决：

• 断点打在了不可执行行：断点打在空行、纯注释行或多行文档字符串（docstring）上，Python 解释器在编译字节码时会跳过这些行，导致断点失效。请将断点移动到具体的赋值、函数调用或控制流语句上。
• Python 解释器加载延迟：VS Code 窗口刚打开时 Python 扩展仍在后台扫描环境。可观察底部状态栏是否已显示版本号，若卡死可按 Ctrl+Shift+P 执行 Developer: Reload Window 重新加载。

2. 运行调试时抛出 ModuleNotFoundError 或找不到文件

原因与解决：

• 工作路径（cwd）错位：直接按 F5 时，默认的 cwd 可能是 VS Code 当前打开的工作区根目录，也可能是脚本所在目录。检查代码中的相对路径引用，建议在 launch.json 中明确声明 "cwd": "${workspaceFolder}"。
• PythonPath 缺失：多目录工程未将根目录加入搜索路径时，可在 launch.json 的 env 中加入 "PYTHONPATH": "${workspaceFolder}"。

3. 遇到 input() 函数时调试卡死无响应

原因与解决：如果调试配置中的 console 使用了 internalConsole（即调试控制台），它是只读输出流，无法捕获标准终端输入。必须在 launch.json 中将该项指定为 "console": "integratedTerminal"，这样运行时会调起 VS Code 内置终端面板，支持正常键盘键入并按回车交互。

4. 单步调试误入第三方底层库源码

原因与解决：按 F11 时不慎深入了 site-packages 底层源码。应急处理是立即按下快捷键 Shift+F11（单步跳出） 返回上层自写代码；长久方案是检查 launch.json，确保 "justMyCode": true 处于启用状态。若遇到多进程（multiprocessing）子进程断点未命中的情况，还需在配置中增加 "subProcess": true。

六、调试操作速查表