VSCode——Debug使用笔记

整体说明

  • VSCode Debug 大型项目是有一定难度和门槛的

Debug 的前置准备

安装必要插件

  • 打开 VSCode，左侧栏扩展（快捷键Ctrl+Shift+X），搜索并安装：
    • Python（微软官方，核心插件）
    • Python Debugger（新版调试核心，微软官方）
    • 可选：Pylance（增强代码提示，大型项目必备）

确认 Python 解释器

  • 大型项目通常用虚拟环境，Debug 是从 terminal 中启动的，需要在 terminal 先配置好环境
  • 快捷键 Ctrl+Shift+P，输入 Python: Select Interpreter

初始化调试配置文件（launch.json）

  • VSCode 调试依赖 launch.json 配置，大型项目需自定义配置以适配项目结构，步骤如下：

  • 1）打开项目根目录（关键：必须打开根目录，而非单个文件）

  • 2）打开调试面板：左侧栏 运行和调试 （快捷键Ctrl+Shift+D）， 点击 创建 launch.json 文件

  • 3）选择调试环境：弹出的下拉框中选 Python，再选 Python File（基础模板，后续修改）

    • 默认生成的 launch.json 在 .vscode 文件夹下

  • 4）自定义 launch.json（这一步是核心！适配大型项目），修改为适合大型项目的配置，示例如下（注释说明关键参数）：

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    {
        "version": "0.2.0",
        "configurations": [
            {
                "name": "Python: 项目主入口", // 配置名称，可自定义
                "type": "debugpy", // 调试器核心，固定值
                "request": "launch", // 启动调试（而非附加进程）
                "program": "${workspaceFolder}/src/main.py", // 项目主入口文件（替换为你的实际路径）
                "cwd": "${workspaceFolder}", // 调试时的工作目录（固定为项目根）
                "args": ["--env", "dev", "--config", "configs/dev.yaml"], // 主程序运行参数（按需添加）
                "justMyCode": false, // 大型项目建议关闭，可调试第三方库/依赖代码
                "env": { // 自定义环境变量（如数据库地址、密钥等）
                    "PYTHONPATH": "${workspaceFolder}", // 关键！解决大型项目模块导入问题
                    "ENV": "development"
                },
                "envFile": "${workspaceFolder}/.env", // 加载.env文件（可选，管理环境变量）
                "stopOnEntry": false, // 启动后是否立即暂停（新手可设为true，熟悉后改false）
                "console": "integratedTerminal", // 调试输出到VSCode集成终端（方便看日志）
                "subProcess": true // 关键！调试子进程/子模块（大型项目多进程必备）
            },
            // 可选：添加调试单个模块/测试文件的配置
            {
                "name": "Python: 调试单个模块",
                "type": "debugpy",
                "request": "launch",
                "module": "src.utils.data_process", // 调试指定模块（替代program）
                "cwd": "${workspaceFolder}",
                "env": {"PYTHONPATH": "${workspaceFolder}"}
            }
        ]
    }
    • PYTHONPATH：将项目根目录加入 Python 路径，解决 模块找不到 问题（大型项目多目录结构必配）；
    • subProcess：开启后可调试项目中通过 subprocess 启动的子进程；
    • args：传递给主程序的命令行参数（如配置文件路径、环境参数）

设置断点

  • 大型项目调试时应该避免 全局断点 ，需针对性设置：

基础断点

  • 点击代码行号左侧的空白处，出现红色圆点即断点生效（调试时运行到此处会暂停）

高级断点（非常好用）

  • 使用：右键断点红点 -> Edit Breakpoint，会出现多个选项可选，默认是 Expression
    • Expression ：
      • 右键断点红点 -> Edit Breakpoint -> Expression -> 输入 Python 表达式（仅当表达式为 True 时暂停）
      • 示例：调试循环处理数据时，设条件 i == 100（仅第 100 次循环暂停，避免逐行调试）
      • 注意这个配置很好用，不需要修改代码，且可以是任意的语句
    • Log Messages ：
      右键断点红点 -> Edit Breakpoint -> Log Messages -> 输入日志内容（如 "处理数据：{data_id}" ）
      • 调试时不暂停，仅输出日志（适合排查循环/批量处理问题，不中断程序）

启动调试

  • 第一步：
    • 确认 launch.json 中选中目标配置
    • 比如调试面板顶部下拉框选 launch.json 中已经配置好的选项
  • 第二步：
    • 点击调试面板的 绿色三角按钮
    • 启动后程序运行到断点会暂停，顶部出现调试控制栏，核心按钮（从左到右）：
  • 第三步：一些调试操作说明
    • 继续（F5）：运行到下一个断点；
    • 单步跳过（F10）：执行当前行，不进入函数内部（适合快速跳过无关代码）；
    • 单步进入（F11）：进入当前行调用的函数内部（调试子模块核心）；
    • 单步退出（Shift+F11）：从当前函数退出到调用处；
    • 重启（Ctrl+Shift+F5）：重新启动调试；
    • 停止（Shift+F5）：结束调试

附录：调试时查看数据

  • VSCode 提供多个面板 查看 查看变量/数据状态

变量面板

  • 自动显示当前作用域的所有变量（局部变量、全局变量、内置变量）
  • 可展开复杂对象（如字典、类实例）查看内部属性
  • 右键变量 -> 添加到监视 ，固定关注核心变量

监视面板

  • 手动输入 Python 表达式（如 len(data_list)、user.id == 123），实时显示结果；
  • 大型项目建议添加 核心状态变量 （如配置是否加载、数据库连接是否正常）
  • 监控面板的变量会固定长期展示（变化也会体现出来）

附录：调试大型项目的进阶技巧（避坑+效率提升）

技巧1：解决 模块导入失败 问题

  • 大型项目多目录结构（如 src/、tests/、configs/）易出现 ModuleNotFoundError，除了配置 PYTHONPATH，还可以尝试
    • 在项目根目录创建 __init__.py（空文件即可，标记为Python包）；
    • 调试单个模块时，用 module 参数替代 program（如 launch.json 中 "module": "src.utils.data_process"，而非直接指定文件路径）

技巧2：调试多线程/多进程项目

  • 多线程 ：调试面板左侧 调用堆栈 -> 展开 线程 列表，切换不同线程查看状态；
  • 多进程 ：
    • 若用 gevent 协程，需在 launch.json 中添加 "gevent": true
    • 普通进程使用 subProcess: true（子进程调试）；
  • 进阶：使用 附加到进程 调试（调试面板 -> 添加配置 -> Python: 附加到进程 ，选择运行中的Python进程）

技巧3：调试测试用例（大型项目单元测试必备）

  • 安装 pytest（pip install pytest）；

  • launch.json 添加配置：

    1
    2
    3
    4
    5
    6
    7
    8
    9
    {
        "name": "Python: test case",
        "type": "debugpy",
        "request": "launch",
        "module": "pytest",
        "args": ["tests/test_data_process.py::test_handle_data", "-v"],
        "cwd": "${workspaceFolder}",
        "env": {"PYTHONPATH": "${workspaceFolder}"}
    }
    • 启动后直接调试指定测试用例（精准定位单元测试失败问题）

技巧4：跳过无关代码（提升效率）

  • 大型项目调试时避免进入第三方库/无关模块：
    • 在 launch.json 中设置 "justMyCode": true（默认），调试时自动跳过 site-packages 中的第三方库代码
    • 若需调试自己写的子模块，确保模块路径在 PYTHONPATH 中，且代码在 ${workspaceFolder} 下

附录：其他问题总结

  • 若断点未触发：检查 launch.json 的 program 路径是否正确、断点是否在执行路径上、PYTHONPATH 是否配置

  • 若变量查看异常：确认当前作用域是否正确（如函数内部只能看局部变量）

  • 若调试卡顿：减少不必要的断点，优先用 日志断点 替代普通断点

  • 断点灰色（未生效）：

    • 原因：文件不在项目根目录、解释器选错、launch.json 的 program 路径错误；
    • 解决：确认打开的是项目根目录，重新选择解释器，检查 program 路径是否为 ${workspaceFolder} 开头

  • ModuleNotFoundError：

    • 解决：配置 PYTHONPATH: "${workspaceFolder}"，或在代码开头添加：
      1
      2
      3
      import sys
      from pathlib import Path
      sys.path.append(str(Path(__file__).parent.parent)) # 向上级目录添加到路径

  • 调试时终端无输出：

    • 解决：launch.json 中设置 "console": "integratedTerminal"（而非 internalConsole）