How to Debug Python in VS Code – wiki大全

作者： /

如何在 VS Code 中调试 Python

调试是软件开发中不可或缺的一环，它能帮助开发者理解代码执行流程、定位错误并修复问题。Visual Studio Code (VS Code) 提供了强大且用户友好的 Python 调试功能，使得开发者能够高效地进行 Python 项目的调试工作。本文将详细介绍如何在 VS Code 中设置和使用 Python 调试器。

1. 前提条件

在开始之前，请确保你的开发环境已满足以下条件：

  1. Python 安装：你的系统上已安装 Python 解释器。
  2. Visual Studio Code：你已安装 VS Code。
  3. Python 扩展：在 VS Code 中安装了官方的 Microsoft Python 扩展。你可以在扩展视图（Ctrl+Shift+X 或 Cmd+Shift+X）中搜索 “Python” 并安装它。

2. 基本调试步骤

配置完成后，你可以开始进行基本的 Python 调试。

2.1 设置断点 (Breakpoints)

断点是调试器暂停代码执行的点，允许你检查程序状态。

  • 添加断点：在代码行号的左侧点击，会出现一个红点，表示断点已设置。
  • 移除断点：再次点击红点即可移除。
  • 禁用断点：在“运行和调试”视图（左侧边栏的虫子图标）的“断点”部分，可以勾选或取消勾选来启用或禁用断点。

2.2 启动调试器

有两种主要方式启动调试：

  1. 直接运行和调试当前文件：

    • 打开你要调试的 Python 文件。
    • 点击 VS Code 左侧边栏的“运行和调试”图标（一个带有虫子的播放按钮）。
    • 点击顶部的绿色播放按钮，或按 F5。VS Code 会自动检测这是一个 Python 文件并尝试使用默认配置启动调试。

  2. 通过 launch.json 文件配置：

    • 对于更复杂的项目或需要特定配置（例如命令行参数、环境变量），你需要创建 launch.json 文件。
    • 在“运行和调试”视图中，点击齿轮图标（“创建 launch.json 文件”）。
    • 选择“Python Debugger”作为环境。
    • VS Code 会在 .vscode 文件夹下生成一个 launch.json 文件。你可以选择一个预设配置（例如 “Python: Current File”）或根据需要进行修改。

    一个简单的 launch.json 配置示例：

    json
    {
    "version": "0.2.0",
    "configurations": [
    {
    "name": "Python: Current File",
    "type": "python",
    "request": "launch",
    "program": "${file}",
    "console": "integratedTerminal",
    "justMyCode": true
    },
    {
    "name": "Python: Module",
    "type": "python",
    "request": "launch",
    "module": "my_module.main", // 替换为你的模块名
    "console": "integratedTerminal",
    "justMyCode": true
    },
    // ... 其他配置
    ]
    }

    • name: 调试配置的名称，显示在调试下拉菜单中。
    • type: 调试器类型，Python 调试器始终为 python。
    • request: launch 用于启动新进程，attach 用于连接到已运行的进程。
    • program: 要调试的 Python 脚本的路径。${file} 是一个变量，表示当前打开的文件。
    • console: 指定调试输出的控制台 (internalConsole, integratedTerminal, externalTerminal)。
    • args: 传递给 Python 脚本的命令行参数（字符串数组）。
    • env: 环境变量（键值对对象）。
    • cwd: 调试器的工作目录。
    • justMyCode: (Python 扩展独有) 默认为 true，跳过第三方库代码，只调试你的代码。设置为 false 可以步进到库代码中。

2.3 调试控制栏

启动调试后，VS Code 会在顶部显示一个调试控制栏，包含以下常用操作：

  • 继续 (Continue / F5)：执行到下一个断点或程序结束。
  • 单步跳过 (Step Over / F10)：执行当前行，如果当前行调用了函数，则不进入函数内部，直接执行完函数并停在下一行。
  • 单步调试 (Step Into / F11)：执行当前行，如果当前行调用了函数，则进入函数内部的第一行。
  • 单步跳出 (Step Out / Shift+F11)：从当前函数中跳出，执行完当前函数的剩余部分，并停在调用该函数的下一行。
  • 重启 (Restart / Ctrl+Shift+F5)：停止当前调试会话并重新启动。
  • 停止 (Stop / Shift+F5)：停止当前调试会话。

2.4 检查变量和状态

在调试过程中，VS Code 的“运行和调试”视图提供了多个有用的面板：

  • 变量 (Variables)：显示当前作用域内的所有局部变量、全局变量和特殊变量的值。当程序暂停时，你可以展开对象来查看其内部属性。
  • 监视 (Watch)：允许你添加特定的表达式或变量，以便在调试过程中持续观察它们的值。即使它们不在当前作用域中，只要它们是可访问的，你就能监视。
  • 调用堆栈 (Call Stack)：显示当前函数的调用链。你可以点击堆栈中的条目，跳转到对应的代码位置。
  • 断点 (Breakpoints)：管理项目中所有断点的列表，可以启用、禁用或删除。

2.5 调试控制台 (Debug Console)

调试控制台（位于 VS Code 面板区域）是一个强大的工具，它允许你在程序暂停时：

  • 执行任意 Python 代码：你可以输入表达式来实时评估变量值、调用函数或修改程序状态（慎用）。
  • 查看程序输出：print() 语句的输出会显示在这里。
  • 查看调试器信息。

3. 高级调试技巧

3.1 条件断点 (Conditional Breakpoints)

只在满足特定条件时才触发的断点。

  • 设置方法：右键点击断点 -> “编辑断点” -> 选择“表达式”。输入一个 Python 表达式，当该表达式评估为 True 时，断点才会触发。
  • 示例：i == 5，当循环变量 i 等于 5 时才暂停。

3.2 日志点 (Log Points)

在不暂停程序执行的情况下，将信息打印到调试控制台的断点。

  • 设置方法：右键点击断点 -> “编辑断点” -> 选择“日志消息”。输入一个字符串，可以使用 {expression} 语法来插入变量值。
  • 示例：Current value of i: {i}。

3.3 异常断点 (Exception Breakpoints)

在抛出或捕获特定异常时暂停程序。

  • 在“运行和调试”视图的“断点”面板中，你可以勾选“捕获到的异常”和/或“未捕获到的异常”，让调试器在这些情况发生时自动暂停。

3.4 调试 Flask/Django 应用

对于 Web 框架，通常需要通过特定的方式启动调试器。

  • Flask：
    json
    {
    "name": "Python: Flask",
    "type": "python",
    "request": "launch",
    "module": "flask",
    "env": {
    "FLASK_APP": "app.py", // 替换为你的主应用文件
    "FLASK_ENV": "development"
    },
    "args": [
    "run",
    "--no-debugger",
    "--no-reload"
    ],
    "jinja": true, // 启用 Jinja 模板调试
    "console": "integratedTerminal",
    "justMyCode": true
    }

  • Django：
    json
    {
    "name": "Python: Django",
    "type": "python",
    "request": "launch",
    "program": "${workspaceFolder}/manage.py",
    "args": [
    "runserver",
    "--noreload",
    "--nothreading"
    ],
    "django": true, // 启用 Django 模板调试
    "console": "integratedTerminal",
    "justMyCode": true
    }
    请注意，"django": true 和 "jinja": true 选项会启用模板调试，允许你在模板文件中设置断点。

3.5 远程调试

VS Code 也支持远程调试，允许你连接到一个在远程服务器或容器中运行的 Python 应用程序。这通常涉及在远程机器上运行一个调试服务器，然后在本地 VS Code 中配置 launch.json 以 attach 到该服务器。具体配置因环境而异，通常会用到 ptvsd 或 debugpy 库。

4. 调试技巧与最佳实践

  • 使用 justMyCode：默认情况下，Python 扩展会跳过第三方库代码，这通常是希望的行为。如果你需要深入探索库的内部，可以将其设置为 false。
  • 逐步细化：先从高层级的断点开始，然后逐步深入，缩小问题范围。
  • 打印调试信息：在复杂的逻辑中，使用日志点或 print() 语句输出关键变量，可以帮助你理解程序流。
  • 理解调用堆栈：当你遇到错误时，调用堆栈能清晰地告诉你代码是如何走到当前位置的，这对于理解错误的根源至关重要。
  • 使用 VS Code 的集成终端：调试时将 console 设置为 integratedTerminal 可以让你在同一个窗口中看到程序输出和与调试器的交互。

结论

VS Code 为 Python 开发者提供了一套全面而强大的调试工具。通过掌握断点、单步执行、变量检查和 launch.json 配置，你可以显著提高代码调试的效率和质量。投入时间熟悉这些功能，将使你在 Python 开发中更加游刃有余。

滚动至顶部