一、概述调试配置的中枢launch.json是 VS Code 调试系统的核心配置文件位于工作区的.vscode/目录下。它定义了如何启动调试会话——包括启动哪个程序、传递什么参数、使用什么调试器、在何种环境下运行等。与临时调试如直接按 F5 让 VS Code 自动推断不同launch.json让你能够精确控制启动行为自定义命令行参数、环境变量、工作目录支持复杂场景多进程调试、远程调试、附加到运行中的进程团队协作共享配置随仓库提交团队成员开箱即用一键切换场景在多个调试配置间快速切换如开发模式 vs “测试模式”二、文件位置与基本结构2.1 文件位置workspace/ ├── .vscode/ │ ├── launch.json ← 调试配置 │ ├── tasks.json ← 构建任务配置 │ └── settings.json ← 编辑器设置 ├── src/ └── package.json注意launch.json支持两个作用域工作区级别.vscode/launch.json推荐随仓库共享用户级别~/.vscode/launch.json全局生效不随仓库共享2.2 顶层结构{version:0.2.0,configurations:[// 单个调试配置数组],compounds:[// 复合配置可选同时启动多个调试会话]}字段类型说明versionstring固定值0.2.0VS Code 用此识别格式版本configurationsarray调试配置列表每个元素是一个独立的调试启动项compoundsarray复合配置可同时启动多个 configurations三、通用核心字段详解无论调试何种语言以下字段是所有launch.json配置的基础3.1 标识与类型字段字段必填说明name✅显示在调试侧边栏下拉框中的名称如Python: Current Filetype✅调试器类型如python、node、cppdbg、gorequest✅启动模式launch启动新程序或attach附加到已有进程3.2 程序定位字段字段说明program要调试的可执行文件或入口脚本路径cwd工作目录Current Working Directory默认为${workspaceFolder}args传递给程序的命令行参数数组如[--port, 8080, --debug]3.3 环境与参数字段字段类型说明envobject环境变量键值对如{NODE_ENV: development}envFilestring环境变量文件路径如${workspaceFolder}/.envpreLaunchTaskstring调试前自动执行的 Task来自tasks.json如npm: buildpostDebugTaskstring调试结束后执行的 TaskruntimeExecutablestring替代默认的运行时如自定义 Python 解释器路径3.4 调试行为字段字段类型默认值说明stopOnEntrybooleanfalse是否在程序入口第一行自动暂停consolestring-输出目标integratedTerminal集成终端、externalTerminal外部终端、internalConsolejustMyCodebooleantrue是否仅调试用户代码跳过库内部subProcessbooleanfalse是否自动调试子进程四、变量替换系统VS Code 在launch.json中支持丰富的预定义变量极大提升了配置的可移植性变量解析结果${workspaceFolder}工作区根目录的绝对路径${workspaceFolderBasename}工作区根目录的文件夹名${file}当前活动编辑窗口文件的绝对路径${fileBasename}当前文件名含扩展名${fileBasenameNoExtension}当前文件名不含扩展名${fileDirname}当前文件所在目录的绝对路径${relativeFile}当前文件相对于工作区根目录的路径${cwd}当前工作目录${env:NAME}环境变量NAME的值如${env:HOME}${command:commandId}执行指定 VS Code 命令并取返回值示例program:${workspaceFolder}/src/main.py,args:[--config,${workspaceFolder}/config/dev.json]五、各语言实战配置示例5.1 Python{version:0.2.0,configurations:[{name:Python: Current File,type:debugpy,request:launch,program:${file},console:integratedTerminal,justMyCode:true,env:{PYTHONPATH:${workspaceFolder}},args:[]},{name:Python: Flask App,type:debugpy,request:launch,module:flask,env:{FLASK_APP:app.py,FLASK_DEBUG:1},args:[run,--no-debugger,--no-reload],jinja:true},{name:Python: Attach to Process,type:debugpy,request:attach,connect:{host:localhost,port:5678}}]}关键说明debugpy是 VS Code Python 扩展的现代调试器取代了旧的python类型module字段用于以python -m module方式启动Flask/Django 等框架有专门的配置模板5.2 Node.js{version:0.2.0,configurations:[{name:Node.js: Current File,type:node,request:launch,program:${file},console:integratedTerminal,env:{NODE_ENV:development}},{name:Node.js: Launch Server,type:node,request:launch,runtimeExecutable:node,args:[${workspaceFolder}/server.js,--port,3000],envFile:${workspaceFolder}/.env,restart:true,runtimeVersion:20.11.0},{name:Node.js: Attach,type:node,request:attach,port:9229,restart:true,protocol:inspector}]}关键说明Node.js 启动时加--inspect或--inspect-brk参数后可用attach模式连接restart: true在 nodemon 等工具重启进程后自动重新附加5.3 C/C使用 GDB/LLDB{version:0.2.0,configurations:[{name:C: Build and Debug,type:cppdbg,request:launch,program:${workspaceFolder}/build/main,args:[],stopAtEntry:false,cwd:${workspaceFolder},environment:[],externalConsole:false,MIMode:gdb,miDebuggerPath:/usr/bin/gdb,setupCommands:[{description:Enable pretty-printing for gdb,text:-enable-pretty-printing,ignoreFailures:true}],preLaunchTask:C/C: g build active file}]}关键说明cppdbg是 VS Code C/C 扩展的调试器类型MIMode可选gdbLinux、lldbmacOS或gdb/lldbWindows 配合 MinGW/ClangsetupCommands向调试器发送初始化命令5.4 Go{version:0.2.0,configurations:[{name:Go: Launch Package,type:go,request:launch,mode:auto,program:${workspaceFolder},env:{},args:[]},{name:Go: Launch Test Function,type:go,request:launch,mode:test,program:${workspaceFolder},args:[-test.run,TestMyFunction]},{name:Go: Attach to Process,type:go,request:attach,mode:local,processId:0}]}关键说明mode: auto自动检测是debug还是test模式mode: test专门用于调试单元测试Go 调试依赖dlvDelve调试器5.5 Rust{version:0.2.0,configurations:[{name:Rust: Launch,type:lldb,request:launch,cargo:{args:[build],filter:{name:my-project,kind:bin}},args:[],cwd:${workspaceFolder}}]}关键说明Rust 扩展推荐使用lldb或cppdbg类型cargo字段让 VS Code 自动调用 Cargo 构建并定位输出二进制六、高级特性6.1 Compound复合配置同时启动多个调试会话典型场景是前后端联调{compounds:[{name:Full Stack: Server Client,configurations:[Node.js: Launch Server,Chrome: Launch Client],preLaunchTask:npm: build,stopAll:true}]}选择Full Stack: Server Client后VS Code 会同时启动两个调试会话stopAll: true表示停止其中一个时全部停止6.2 输入变量Input Variables在启动调试前弹窗让用户输入参数{configurations:[{name:Python: Custom Input,type:debugpy,request:launch,program:${file},args:[${input:targetEnv}]}],inputs:[{id:targetEnv,type:pickString,description:Select target environment,options:[dev,staging,prod],default:dev}]}支持的输入类型promptString自由文本输入pickString下拉选择command执行 VS Code 命令获取值6.3 条件断点与日志点虽然不在launch.json中直接配置但 VS Code 调试器支持通过 UI 设置条件断点右键断点 → 输入条件表达式如i 100 user ! null仅条件满足时暂停日志点右键断点 → “Log Message”不暂停程序仅输出日志如Loop iteration {i}6.4 远程调试{name:Python: Remote Attach,type:debugpy,request:attach,connect:{host:192.168.1.100,port:5678},pathMappings:[{localRoot:${workspaceFolder},remoteRoot:/app}],justMyCode:true}pathMappings将远程路径映射到本地源码确保断点能正确对应七、与tasks.json的协作preLaunchTask是launch.json与tasks.json联动的桥梁.vscode/tasks.json{version:2.0.0,tasks:[{label:npm: build,type:npm,script:build,problemMatcher:[]},{label:CMake: Build,type:shell,command:cmake --build build,group:build}]}.vscode/launch.json{configurations:[{name:C: Debug,type:cppdbg,request:launch,program:${workspaceFolder}/build/myapp,preLaunchTask:CMake: Build}]}执行流程用户按 F5 启动调试VS Code 先执行preLaunchTask编译项目编译成功后启动调试器若编译失败调试不会启动八、最佳实践8.1 配置组织原则按场景命名Python: Unit Tests、Node: Debug API比Launch更清晰善用${file}对于脚本型语言Python、Node用${file}让当前活动文件成为调试目标减少配置数量环境变量外置敏感信息API Key、数据库密码放在.env文件中通过envFile引用避免提交到仓库区分 launch 与 attach开发新功能用launch线上问题排查用attach8.2 常见问题排查问题原因解决断点变灰色空心源码与编译产物不匹配重新编译确保pathMappings正确program does not exist可执行文件路径错误或未编译检查program路径确认preLaunchTask成功执行环境变量未生效env与envFile冲突env优先级高于envFile检查覆盖关系attach 失败目标进程未开启调试端口确认目标程序已加--inspect/--debug等参数启动无法进入库内部代码justMyCode: true设为false以调试第三方库8.3 调试快捷键速查快捷键功能F5启动/继续调试Shift F5停止调试F9切换断点F10单步跳过Step OverF11单步进入Step IntoShift F11单步跳出Step OutCtrl Shift D打开调试侧边栏九、总结launch.json是 VS Code 从代码编辑器升级为全功能 IDE的关键拼图。掌握它的核心在于理解三个层次基础层nametyperequestprogram构成最小可用配置控制层通过args、env、preLaunchTask精确控制启动环境高级层利用compounds、inputs、pathMappings应对复杂工程场景一份精心维护的launch.json能让团队新成员在克隆仓库后按 F5 即可开始调试这种开箱即用的体验是工程成熟度的直接体现。