VS Code 调试 launch.json 解析

Python调试时配置文件构造与指南

深入理解VS Code调试配置文件，掌握Python开发调试的核心技能

本文就下面这盘醋包了一盘饺子，主体应用以下面为主，扩展可看详细解析：

json 复制代码

{
    // ============================================================
    // VS Code 调试配置文件 (launch.json)
    // 用于配置 Python 程序的调试环境
    // 文件位置: .vscode/launch.json
    // ============================================================

    // version: 调试配置文件的版本号
    // 固定为 "0.2.0"，表示使用 VS Code 的调试配置格式
    "version": "0.2.0",

    // configurations: 调试配置数组
    // 可以包含多个调试配置，每个配置对应一种调试场景
    "configurations": [
        {
            // ============================================================
            // 调试配置项 1: Python:Megacollect
            // 用于运行和调试 Python 脚本
            // ============================================================

            // name: 配置名称
            // 显示在 VS Code 调试下拉菜单中的名称
            // 用户可以通过这个名称选择要使用的调试配置
            "name": "Python:Megacollect",

            // type: 调试器类型
            // "debugpy" 表示使用 Python 的调试器（基于 debugpy 库）
            // 这是 VS Code 官方推荐的 Python 调试器
            "type": "debugpy",

            // request: 调试请求类型
            // "launch" 表示启动一个新的调试会话（而非附加到已运行的进程）
            // 另一个可选值是 "attach"，表示附加到已运行的进程
            "request": "launch",

            // program: 要调试的程序文件路径
            // "${file}" 是一个变量，表示当前在编辑器中打开的文件
            // 即：调试当前正在编辑的 Python 文件
            "program": "${file}",

            // console: 控制台类型
            // "integratedTerminal" 表示使用 VS Code 的内置终端
            // 其他选项: "internalConsole"（调试控制台）、"externalTerminal"（外部终端）
            "console": "integratedTerminal",

            // cwd: 当前工作目录
            // "${workspaceFolder}" 表示项目根目录（即打开的工作区文件夹）
            // 程序运行时，相对路径将基于此目录解析
            "cwd": "${workspaceFolder}",

            // python: Python 解释器路径
            // 指定使用哪个 Python 解释器来运行程序
            // 这里是 miniconda3 环境 "jxvla" 下的 Python 解释器
            // 如果省略此项，VS Code 将使用 settings.json 中配置的默认解释器
            "python": "/home/ubuntu/miniconda3/envs/jxvla/bin/python"
        }

        // ============================================================
        // 可以在此添加更多的调试配置
        // 示例: 
        // {
        //     "name": "Python: Current File (Default)",
        //     "type": "debugpy",
        //     "request": "launch",
        //     "program": "${file}",
        //     "console": "integratedTerminal"
        // }
        // ============================================================
    ]
}

前言

作为Python开发者，调试是我们日常工作不可或缺的一部分。VS Code作为最流行的代码编辑器之一，其强大的调试功能离不开launch.json配置文件的支持。本文将深入解析一个典型的launch.json文件，帮助读者理解每个配置项的含义、作用以及如何灵活运用。

一、什么是 launch.json？

launch.json是VS Code中用于配置调试会话的配置文件，位于项目根目录下的.vscode文件夹中。它告诉VS Code如何启动、运行和调试你的程序。

核心作用：

定义调试环境（Python解释器、工作目录）
配置调试行为（控制台类型、命令行参数）
管理多个调试场景（不同项目的调试配置）

二、完整配置解析

让我们逐层拆解一个完整的Python调试配置：

2.1 根结构：版本与配置列表

json 复制代码

{
    "version": "0.2.0",
    "configurations": [ /* 配置数组 */ ]
}

字段	类型	说明
`version`	string	固定为"0.2.0"，表示调试配置文件的版本格式
`configurations`	array	包含一个或多个调试配置对象，支持多场景调试

2.2 单个配置项详解

基础信息

json 复制代码

{
    "name": "Python:Megacollect",
    "type": "debugpy",
    "request": "launch"
}

name - 配置显示名称

显示在VS Code调试下拉菜单中
建议命名规则：[语言]:[功能描述]
示例："Python: Django Server"、"Python: Unit Tests"

type - 调试器类型

Python项目固定使用 "debugpy"
debugpy是微软官方维护的Python调试适配器
其他语言示例："node"（Node.js）、"java"（Java）

request - 调试请求类型

值	说明	使用场景
`"launch"`	启动新进程调试	日常开发，启动程序进行调试
`"attach"`	附加到已有进程	调试已运行的程序、生产环境问题排查

程序与运行环境

json 复制代码

{
    "program": "${file}",
    "console": "integratedTerminal",
    "cwd": "${workspaceFolder}",
    "python": "/home/ubuntu/miniconda3/envs/jxvla/bin/python"
}

program - 入口程序路径

${file} 变量：当前编辑器中打开的文件
支持绝对路径："${workspaceFolder}/src/main.py"
也可以指定固定文件："app.py"

console - 输出控制台类型

选项	特点	适用场景
`"integratedTerminal"`	VS Code内置终端，支持完整输入输出	大多数开发场景（推荐）
`"internalConsole"`	调试控制台，不能交互输入	纯输出调试
`"externalTerminal"`	系统独立终端窗口	需要完整终端功能

cwd - 当前工作目录

${workspaceFolder} 指向项目根目录
影响相对路径的解析
示例：如果你的程序有open('data/file.txt')，会从工作目录开始查找

python - Python解释器路径

指定具体解释器，确保环境一致性
示例路径结构：/home/ubuntu/miniconda3/envs/jxvla/bin/python
如果不指定，VS Code会使用默认选中的解释器

三、进阶配置参数

3.1 命令行参数 `args`

json 复制代码

{
    "args": ["--input", "data.csv", "--output", "result.json", "--verbose"]
}

对应命令行执行：python script.py --input data.csv --output result.json --verbose

3.2 环境变量 `env`

json 复制代码

{
    "env": {
        "PYTHONPATH": "${workspaceFolder}/src",
        "DATABASE_URL": "postgresql://localhost:5432/mydb",
        "DEBUG": "true",
        "API_KEY": "sk-xxx123"
    }
}

应用场景：

设置PYTHONPATH让Python能找到自定义模块
注入数据库连接字符串
控制调试模式开关

3.3 调试行为控制

json 复制代码

{
    "justMyCode": true,
    "stopOnEntry": false,
    "redirectOutput": true
}

参数	说明	推荐值
`justMyCode`	仅调试用户代码，跳过库源码	`true`（避免进入第三方库调试）
`stopOnEntry`	启动时自动暂停在第一行	`false`（减少干扰）
`redirectOutput`	将print输出重定向到调试控制台	`true`（方便查看）

四、多配置实战示例

4.1 完整的多场景配置

json 复制代码

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: 当前文件",
            "type": "debugpy",
            "request": "launch",
            "program": "${file}",
            "console": "integratedTerminal",
            "cwd": "${workspaceFolder}"
        },
        {
            "name": "Python: Django服务器",
            "type": "debugpy",
            "request": "launch",
            "program": "${workspaceFolder}/manage.py",
            "args": ["runserver", "--noreload"],
            "console": "integratedTerminal",
            "cwd": "${workspaceFolder}",
            "env": {
                "DJANGO_SETTINGS_MODULE": "myproject.settings"
            }
        },
        {
            "name": "Python: 单元测试",
            "type": "debugpy",
            "request": "launch",
            "program": "${workspaceFolder}/tests/run_tests.py",
            "args": ["--verbose"],
            "console": "integratedTerminal",
            "cwd": "${workspaceFolder}",
            "justMyCode": false
        },
        {
            "name": "Python: 生产环境调试",
            "type": "debugpy",
            "request": "attach",
            "connect": {
                "host": "localhost",
                "port": 5678
            }
        }
    ]
}

4.2 配置解读

配置1：通用场景

调试当前打开的任何Python文件
最常用的配置，适合快速测试

配置2：Django项目

指定manage.py作为入口
--noreload避免Django热重载干扰调试
设置Django专属环境变量

配置3：单元测试

justMyCode: false 允许进入测试框架调试
便于排查测试框架本身的问题

配置4：远程调试

使用attach模式连接到运行中的进程
适合排查生产环境问题

五、常用变量大全

变量	含义	示例值
`${workspaceFolder}`	工作区根目录	`/home/user/project`
`${workspaceFolderBasename}`	工作区文件夹名	`project`
`${file}`	当前文件完整路径	`/home/user/project/main.py`
`${fileBasename}`	当前文件名	`main.py`
`${fileBasenameNoExtension}`	当前文件名（无扩展名）	`main`
`${fileDirname}`	当前文件所在目录	`/home/user/project`
`${relativeFile}`	相对于工作区的路径	`src/main.py`
`${cwd}`	当前工作目录	`/home/user/project`

六、常见问题与解决方案

6.1 找不到模块

问题： ModuleNotFoundError: No module named 'xxx'

解决方案：

json 复制代码

{
    "env": {
        "PYTHONPATH": "${workspaceFolder}"
    }
}

6.2 无法输入内容

问题： 使用input()时无法输入

解决方案： 将console改为：

json 复制代码

{
    "console": "integratedTerminal"
}

6.3 Conda环境激活失败

问题： 指定的conda环境Python路径失效

解决方案：

json 复制代码

{
    "python": "/home/ubuntu/miniconda3/envs/your_env/bin/python"
}

七、最佳实践建议

版本控制 ：将.vscode/launch.json提交到Git仓库，团队共享调试配置
敏感信息保护 ：使用环境变量文件（.env）存储敏感配置，通过envFile引入
json 复制代码
```
{
    "envFile": "${workspaceFolder}/.env"
}
```
配置命名规范：使用清晰、描述性的名称，便于团队成员理解
多配置管理：为不同的开发场景（开发、测试、生产）准备独立的配置
相对路径优先 ：使用${workspaceFolder}等变量，确保配置在不同机器上通用

八、总结

launch.json是VS Code调试功能的"控制中心"，理解其配置结构和使用方法能显著提升开发效率。本文从一个具体配置出发，逐步扩展到完整的参数体系，希望能帮助读者：

✅ 理解每个配置项的作用和用法
✅ 掌握多场景配置的组织方法
✅ 学会运用变量和高级参数
✅ 解决常见的配置问题

调试是开发的重要组成部分，好的调试配置能让排查问题变得更加轻松高效。建议读者在实际项目中多尝试不同的配置组合，找到最适合自己工作流的调试方案。

延伸阅读：

作者：您的技术伙伴 | 发布日期：2026年8月5日

VS Code 调试 launch.json 解析

Python调试时配置文件构造与指南

前言

一、什么是 launch.json？

二、完整配置解析

2.1 根结构：版本与配置列表

2.2 单个配置项详解

基础信息

程序与运行环境

三、进阶配置参数

3.1 命令行参数 args

3.2 环境变量 env

3.3 调试行为控制

四、多配置实战示例

4.1 完整的多场景配置

4.2 配置解读

五、常用变量大全

六、常见问题与解决方案

6.1 找不到模块

6.2 无法输入内容

6.3 Conda环境激活失败

七、最佳实践建议

八、总结

3.1 命令行参数 `args`

3.2 环境变量 `env`