VSCode Debug进阶：从launch.json配置到多环境参数调试实战

1. 为什么需要定制launch.json调试配置

第一次用VSCode调试Python脚本时，我也习惯性直接点右上角的调试按钮。直到遇到需要传入命令行参数的场景——比如用YOLOv5训练模型时，必须指定weights、cfg等参数文件路径，直接调试根本跑不起来。这时候就需要launch.json这个调试配置文件来帮忙了。

launch.json相当于调试器的"食谱"，告诉VSCode：

• 要调试哪个程序文件（program）
• 使用哪个Python解释器（python）
• 需要哪些命令行参数（args）
• 在什么环境下运行（env）

没有它就像让厨师做菜不给菜谱，只能做最简单的家常菜。举个例子，调试深度学习项目时常见的痛点：

1. 每次调试都要手动输入一长串参数（--weights xx --cfg xx --data xx）
2. 需要切换不同虚拟环境（比如用conda管理的tf和pytorch环境）
3. 需要设置特殊环境变量（如CUDA_VISIBLE_DEVICES）

通过合理配置launch.json，可以实现：

• 一键启动带参数的复杂调试
• 快速切换不同Python环境
• 保存多套调试配置方案

2. 创建基础调试配置

2.1 生成launch.json模板

在VSCode中按F5启动调试时，如果项目没有launch.json文件，会提示创建。更推荐手动创建：

1. 打开项目根目录
2. 新建.vscode文件夹（注意前面的点）
3. 在.vscode内创建launch.json

基础模板长这样：

json复制{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: 当前文件",
            "type": "debugpy",
            "request": "launch",
            "program": "${file}",
            "console": "integratedTerminal"
        }
    ]
}

关键字段说明：

• version：配置版本号，固定0.2.0
• configurations：调试配置数组
• name：配置显示名称（在调试下拉菜单中可见）
• type：调试器类型，Python用debugpy
• request：launch表示启动新进程
• program：要调试的文件，${file}表示当前打开的文件

2.2 调试带参数的程序

以YOLOv5的train.py为例，需要传入参数才能运行。修改args字段：

json复制{
    "name": "训练YOLOv5模型",
    "type": "debugpy",
    "request": "launch",
    "program": "train.py",
    "args": [
        "--weights", "yolov5s.pt",
        "--cfg", "models/yolov5s.yaml",
        "--data", "coco128.yaml",
        "--batch-size", "16"
    ]
}

参数传递的两种方式：

1. 固定参数：直接写在args数组中
2. 交互式参数：使用"args": "${command:pickArgs}"，调试时会弹出输入框

实测建议：固定参数用方式1，频繁变化的参数用方式2

3. 多环境调试实战技巧

3.1 指定Python解释器路径

当项目需要特定虚拟环境时，通过python字段指定解释器绝对路径：

json复制{
    "python": "/opt/miniconda3/envs/yolov5/bin/python",
    "args": ["--weights", "yolov5s.pt"]
}

获取路径的方法：

• Linux/macOS：which python
• Windows：where python

建议将路径设为相对路径（如"${workspaceFolder}/venv/bin/python"），方便团队共享配置

3.2 环境变量管理

通过env字段设置环境变量，比如指定GPU：

json复制{
    "env": {
        "CUDA_VISIBLE_DEVICES": "0,1",
        "TF_CPP_MIN_LOG_LEVEL": "2"
    }
}

常见使用场景：

• 控制GPU可见性
• 设置日志级别
• 配置API密钥

3.3 复合调试配置

当需要同时调试多个关联进程时，使用compounds配置：

json复制{
    "version": "0.2.0",
    "configurations": [...],
    "compounds": [
        {
            "name": "客户端+服务端",
            "configurations": ["启动服务端", "启动客户端"],
            "preLaunchTask": "初始化环境"
        }
    ]
}

典型应用场景：

• 前后端联调
• 微服务系统
• 多进程应用

4. 高级调试场景解决方案

4.1 条件断点与日志点

在launch.json中配置调试器特性：

json复制{
    "stopOnEntry": true,
    "showReturnValue": true,
    "logToFile": true
}

实用技巧：

1. 条件断点：右键断点→编辑条件
2. 日志点：右键行号→添加日志点（不中断执行）
3. 函数返回值查看：在CALL STACK面板查看

4.2 远程调试配置

调试远程服务器代码的配置示例：

json复制{
    "name": "远程调试",
    "type": "debugpy",
    "request": "attach",
    "host": "192.168.1.100",
    "port": 5678,
    "pathMappings": [
        {
            "localRoot": "${workspaceFolder}",
            "remoteRoot": "/remote/path"
        }
    ]
}

操作步骤：

1. 在远程启动debugpy：python -m debugpy --listen 5678 --wait-for-client train.py
2. 本地连接远程端口
3. 设置路径映射

4.3 调试Jupyter Notebook

特殊配置项：

json复制{
    "type": "debugpy",
    "request": "launch",
    "program": "${file}",
    "notebook": "embedded",
    "justMyCode": false
}

注意事项：

• 需要安装Jupyter插件
• 支持.ipynb文件直接调试
• 可以调试Notebook中的单个cell

调试复杂项目时，最痛苦的不是写代码，而是反复修改参数重启调试。用好launch.json就像拥有了调试瑞士军刀，最近在做一个计算机视觉项目时，我设置了5种不同的参数组合配置，通过下拉菜单一键切换，效率提升非常明显。