VSCode 调试配置详解：launch.json 完全解析

launch.json是VSCode调试核心配置文件，位于项目根目录的.vscode文件夹中，通过version、configurations定义调试行为；每个配置包含name、type、request等字段，支持launch或attach模式，可设置program入口、args参数、env环境变量、cwd工作目录及console输出位置；结合preLaunchTask、skipFiles、sourceMaps等实现高级控制；多配置可通过compounds组合启动，适用于复杂项目调试。

在使用 VSCode 进行开发时，调试功能是提升效率的关键。而 launch.json 文件正是调试配置的核心。它位于项目根目录下的 .vscode 文件夹中，定义了启动调试会话时的行为。下面全面解析 launch.json 的结构与常用配置项，帮助你精准掌控调试流程。

launch.json 基本结构

一个典型的 launch.json 文件包含一个名为 configurations 的数组，每个元素代表一种可选的调试配置：

version 指定配置文件格式版本，当前固定为 "0.2.0"。configurations 数组中的每一项是一个独立的调试配置，可在调试面板中选择。

核心配置字段详解

每个调试配置对象包含多个关键字段，决定调试器如何运行程序。

Felvin

AI无代码市场，只需一个提示快速构建应用程序

下载

• name：显示在 VSCode 调试配置下拉菜单中的名称，自定义即可，如 "Debug Backend" 或 "Run Tests"。
• type：指定调试器类型。常见值包括：
  • node：用于调试 Node.js 应用
  • python：配合 Python 扩展调试 Python 脚本
  • chrome 或 msedge：前端调试，附加到浏览器实例
  • php、go 等：对应语言需安装相应扩展
• request：请求类型，决定调试启动方式：
  • launch：启动并调试目标程序
  • attach：附加到已运行的进程（如本地服务或远程服务器）
• program：程序入口文件路径，常与变量结合使用，如 ${workspaceFolder}/index.js。仅 request: "launch" 时需要。
• args：传递给程序的命令行参数数组，例如：["--port", "3000"]。
• cwd：程序运行时的工作目录，默认为 ${workspaceFolder}。某些脚本依赖相对路径资源时需显式设置。
• env：设置环境变量，格式为键值对。例如： "env": { "NODE_ENV": "development", "DEBUG": "app*" }
• console：控制程序输出位置，可选值：
  • integratedTerminal：在集成终端中运行（推荐，支持交互输入）
  • internalConsole：在调试控制台运行（不支持输入）
  • externalTerminal：在外部终端窗口运行

高级调试场景配置

针对复杂项目，launch.json 支持更精细的控制。

• preLaunchTask：在启动调试前自动运行构建任务。需确保 tasks.json 中已定义对应任务。例如： "preLaunchTask": "npm: build"
• postDebugTask：调试结束后执行清理或通知任务。
• stopOnEntry：设为 true 时，程序启动后立即在入口文件第一行暂停，便于观察初始化过程。
• skipFiles：跳过指定文件的断点，避免进入第三方库。例如跳过 node_modules： "skipFiles": ["${workspaceFolder}/node_modules/**/*.js"]
• sourceMaps：启用后可调试 TypeScript、Babel 等编译型语言源码。通常配合 outFiles 指向生成的 map 文件。
• runtimeExecutable 和 runtimeArgs：自定义运行时，比如使用特定版本的 Node.js 或添加启动参数（如 --inspect-brk）。

多环境与复合配置

大型项目可能需要多个调试模式。可在 configurations 中定义多种配置，如开发、测试、生产等。

还可通过 compounds 字段同时启动多个调试配置，适用于微服务或多进程应用：