一文读懂 .vscode/launch.json：配置、属性、示例与使用指南

目录

基本结构

调试配置对象的核心属性

1. 基础标识属性

2. 程序启动配置

3. 环境与运行时配置

4. 调试行为配置

5. 断点与监视配置

6. 附加调试（attach 类型）专用属性

变量引用

常见场景配置示例

1. Node.js 程序调试

2. Python 脚本调试

3. Chrome 浏览器调试（前端页面）

如何使用调试配置

在 VS Code 中，
.vscode/launch.json 是用于配置调试器的核心文件，它定义了如何启动和调试程序，支持多种编程语言（如 JavaScript、Python、Java、C++ 等）和运行环境。通过配置 
launch.json，你可以自定义调试入口、参数、环境变量等，实现断点调试、变量监视、调用栈查看等功能。

基本结构


launch.json 是一个 JSON 文件，最外层是一个对象，主要包含以下关键属性：


version：调试配置的版本（必填），目前固定值为 
"0.2.0"
configurations：调试配置数组（必填），每个元素是一个调试配置对象

调试配置对象的核心属性

每个调试配置对象可包含以下常用属性（不同语言 / 环境可能有差异）：

1. 基础标识属性


name（必填）：

调试配置的名称，将显示在调试面板的配置下拉列表中示例：
"name": "Launch Node.js Program"


type（必填）：

调试器类型，由对应的 VS Code 扩展提供（需提前安装）常见值：

"node"：Node.js 调试（内置）
"python"：Python 调试（需安装 Python 扩展）
"java"：Java 调试（需安装 Java 扩展）
"cppdbg"：C/C++ 调试（需安装 C/C++ 扩展）
"chrome"：Chrome 浏览器调试（需安装 JavaScript Debugger 扩展） 示例：
"type": "node"


request（必填）：

调试请求类型，决定调试器的启动方式常用值：

"launch"：启动一个新的程序进行调试
"attach"：附加到已运行的程序进程进行调试 示例：
"request": "launch"

2. 程序启动配置


program（常用，针对 
launch 类型）：

要调试的程序入口文件路径支持变量引用（见下文）示例：
"program": "${workspaceFolder}/src/index.js"


args（可选）：

传递给程序的命令行参数数组示例：
"args": ["--port", "3000", "--env", "dev"]


cwd（可选）：

程序运行的工作目录（默认是工作区根目录）示例：
"cwd": "${workspaceFolder}/server"

3. 环境与运行时配置


env（可选）：

定义程序运行时的环境变量（键值对）示例：

"env": {
  "NODE_ENV": "development",
  "API_KEY": "123456"
}


envFile（可选）：

从外部文件加载环境变量（如 
.env 文件）示例：
"envFile": "${workspaceFolder}/.env"


runtimeExecutable（可选）：

用于启动程序的运行时可执行文件（如 Python 解释器、Node 二进制文件）示例：
"runtimeExecutable": "python3"（指定 Python 解释器）


runtimeArgs（可选）：

传递给运行时的参数示例：
"runtimeArgs": ["--inspect"]（Node.js 调试时启用检查模式）

4. 调试行为配置


stopOnEntry（可选，布尔值）：

程序启动后是否立即在入口处暂停（默认 
false）示例：
"stopOnEntry": true


preLaunchTask（可选）：

调试开始前自动执行的任务（需在 
tasks.json 中定义）示例：
"preLaunchTask": "build"（调试前先执行 
build 任务）


postDebugTask（可选）：

调试结束后自动执行的任务示例：
"postDebugTask": "cleanup"


externalConsole（可选，布尔值）：

是否使用外部控制台显示程序输出（默认 
false，使用 VS Code 内置终端）示例：
"externalConsole": true


internalConsoleOptions（可选）：

调试控制台的显示时机常用值：
"neverOpen"（从不自动打开）、
"openOnSessionStart"（调试开始时打开）示例：
"internalConsoleOptions": "neverOpen"

5. 断点与监视配置


skipFiles（可选，针对 Node.js）：

调试时跳过的文件（如 node_modules 中的代码）示例：
"skipFiles": ["<node_internals>/**"]


justMyCode（可选，布尔值，针对 Python 等）：

是否只调试用户编写的代码（跳过库代码）示例：
"justMyCode": true

6. 附加调试（
attach 类型）专用属性

当 
request: "attach" 时，需配置以下属性连接到已运行的进程：


port：目标进程的调试端口
host：目标进程所在的主机（默认 
localhost）
processId：目标进程的 ID（可通过 
${command:pickProcess} 动态选择）

示例：

{
  "name": "Attach to Node.js",
  "type": "node",
  "request": "attach",
  "port": 9229,  // 调试端口
  "restart": true  // 进程退出后自动重新附加
}

变量引用


launch.json 支持使用 VS Code 预定义变量，简化路径配置：


${workspaceFolder}：当前工作区根目录
${file}：当前打开的文件
${fileDirname}：当前文件所在目录
${cwd}：调试任务的工作目录
${env:变量名}：引用系统环境变量（如 
${env:HOME}）

常见场景配置示例

1. Node.js 程序调试

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Launch Node App",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder}/app.js",
      "args": ["--mode", "debug"],
      "cwd": "${workspaceFolder}",
      "env": {
        "NODE_ENV": "development"
      },
      "skipFiles": ["<node_internals>/**"],
      "preLaunchTask": "install-deps"  // 调试前先执行安装依赖的任务
    }
  ]
}

2. Python 脚本调试

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Run Python Script",
      "type": "python",
      "request": "launch",
      "program": "${file}",  // 调试当前打开的Python文件
      "console": "integratedTerminal",  // 使用集成终端
      "justMyCode": true,
      "python": "${command:python.interpreterPath}"  // 自动获取Python解释器路径
    }
  ]
}

3. Chrome 浏览器调试（前端页面）

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Launch Chrome",
      "type": "chrome",
      "request": "launch",
      "url": "http://localhost:5173",  // 前端项目启动地址
      "webRoot": "${workspaceFolder}/src",  // 源代码目录
      "preLaunchTask": "dev"  // 调试前先启动开发服务器
    }
  ]
}

如何使用调试配置

创建配置：打开 VS Code 调试面板（
Ctrl+Shift+D），点击 “创建 launch.json 文件”，选择对应的环境（如 Node.js、Python）自动生成模板。选择配置：在调试面板的配置下拉列表中选择定义好的调试配置。启动调试：点击绿色箭头或按 
F5 开始调试，可使用 
F10（单步跳过）、
F11（单步进入）等快捷键控制调试流程。

通过 
launch.json，你可以灵活定制调试流程，适配不同项目的运行环境，大幅提升问题排查效率。实际配置时需根据具体语言和项目结构调整属性。