如何配置 launch.json:一份 VS Code 调试指南
launch.json 是 Visual Studio Code(VS Code)中用于配置调试设置的核心文件,它定义了当你按下调试按钮(F5 或“运行” > “启动调试”)时,调试器应该如何启动你的程序、附加到进程以及初始化调试环境,正确配置 launch.json 是高效调试代码的关键一步,无论是简单的脚本还是复杂的应用程序。
为什么需要配置 launch.json?
默认情况下,按下 F5 时,VS Code 会尝试根据你当前打开的文件类型(如 JavaScript、Python、C++ 等)使用一个默认的调试配置,这往往不能满足复杂项目的需求,通过自定义 launch.json,你可以精确控制:
- 程序的启动方式:直接运行脚本、启动一个新进程、附加到已运行的进程等。
- 程序启动时的参数:命令行参数、环境变量等。
- 调试器的行为:是否停在断点、是否加载特定符号文件等。
- 不同运行环境的配置:开发环境、测试环境等。
如何创建和编辑 launch.json
- 打开/创建项目文件夹:在 VS Code 中打开你的项目文件夹。
- 启动调试:按下
F5或点击侧边栏的“运行”图标,然后点击“启动调试”。 - 选择环境:VS Code 会检测到你项目中的文件类型,并提示你选择一个调试环境(Python、Node.js、C/C++、Java 等),选择与你项目匹配的环境。
- 自动生成 launch.json:选择环境后,VS Code 会在项目根目录下的
.vscode文件夹中自动创建一个launch.json文件(如果该文件夹不存在,会一并创建),它会包含一个或多个预设的调试配置示例。
如果你已经存在 launch.json 文件,可以直接在 VS Code 中打开它进行编辑,VS Code 会提供智能提示和自动补全功能,帮助你快速配置。
launch.json 的核心配置项解析
一个典型的 launch.json 文件包含一个 JSON 数组,每个对象代表一个调试配置,以下是一些最常用和重要的配置项:
{
"version": "0.2.0",
"configurations": [
{
"name": "Python: Current File", // 配置名称,会在调试启动下拉菜单中显示
"type": "python", // 调试器类型 (e.g., "python", "node", "cppdbg")
"request": "launch", // 请求类型: "launch" (启动新进程) 或 "attach" (附加到已有进程)
"program": "${file}", // 要调试的主程序文件路径
"console": "integratedTerminal", // 调试控制台输出位置: "integratedTerminal", "externalTerminal" 或 "none"
"justMyCode": true, // 是否只调试用户代码 (Python 特有)
"args": ["--arg1", "value1"], // 传递给程序的命令行参数
"env": { // 设置环境变量
"ENV_VAR": "value"
},
"cwd": "${workspaceFolder}", // 程序的工作目录 (当前工作目录)
"stopOnEntry": false, // 是否在程序入口处暂停
"internalConsoleOptions": "openOnSessionStart" // 内部控制台选项
}
]
}
关键配置项详解:
name:配置的显示名称,方便你在调试启动选择器中识别。type:指定使用的调试器,常见的有:python:Python 调试器(Pylance/Pyramid)。node:Node.js 调试器。cppdbg:C/C++ 调试器(通常配合 GDB 或 LLDB)。java:Java 调试器(JDK)。coreclr:.NET Core 调试器。
request:launch:启动一个新的进程进行调试,适用于调试可执行文件、脚本等。attach:附加到一个已经运行的进程上,适用于调试 Web 服务器(如 Node.js 的 Express、Java 的 Tomcat)或后台服务。
program:要调试的程序的入口文件路径或可执行文件路径。${file}:当前打开的文件。${workspaceFolder}:当前工作空间根目录。${workspaceFolder}/src/main.py:工作空间下的特定文件路径。
args:一个字符串数组,表示传递给程序的命令行参数。cwd:程序启动时的工作目录,设置为${workspaceFolder}通常是个好选择,确保程序能正确找到相对路径下的资源。console:指定调试输出的控制台类型。integratedTerminal:VS Code 集成的终端。externalTerminal:系统外部终端。none:不显示控制台输出(适用于某些 GUI 应用或 Web 应用)。
env:一个键值对对象,用于设置程序运行时的环境变量。stopOnEntry:如果设置为true,调试器会在程序入口处立即暂停,允许你逐步执行。justMyCode(Python 特有):如果设置为true,调试器只会暂停在你自己的代码中,跳过库代码,设为false可以调试库代码。port(Node.js/Attach 模式):附加到的端口号。host(Node.js/Attach 模式):附加到的主机名或 IP 地址。
常见场景下的 launch.json 配置示例
示例 1:Python 脚本调试
{
"name": "Debug Python Script",
"type": "python",
"request": "launch",
"program": "${workspaceFolder}/main.py",
"console": "integratedTerminal",
"args": ["input.txt", "--verbose"],
"cwd": "${workspaceFolder}"
}
示例 2:Node.js 应用调试
{
"name": "Debug Node.js Express App",
"type": "node",
"request": "launch",
"program": "${workspaceFolder}/app.js",
"cwd": "${workspaceFolder}",
"console": "integratedTerminal",
"env": {
"NODE_ENV": "development"
}
}
示例 3:附加到已运行的 Node.js 进程
确保你的 Node.js 应用以 --inspect 或 --inspect-brk 参数启动:
node --inspect app.js
然后在 launch.json 中配置 attach:
{
"name": "Attach to Node Process",
"type": "node",
"request": "attach",
"port": 9229, // 默认 inspect 端口
"cwd": "${workspaceFolder}"
}
示例 4:C/C++ 程序调试(使用 GDB)
{
"name": "C/C++: gdb Build and Debug Active File",
"type": "cppdbg",
"request": "launch",
"program": "${workspaceFolder}/build/my_program", // 编译后的可执行文件路径
"args": [],
"stopAtEntry": false,
"cwd": "${workspaceFolder}",
"environment": [],
"externalConsole": false,
"MIMode": "gdb",
"miDebuggerPath": "/usr/bin/gdb", // GDB 的路径,根据系统调整
"setupCommands": [
{
"description": "Enable pretty-printing for gdb",
"text": "-enable-pretty-printing",
"ignoreFailures": true
}
]
}
调试技巧与注意事项
- 使用变量:充分利用
${workspaceFolder},${fileDirname},${file}等变量,让你的配置更具可移植性。 - 多配置管理:你可以在
configurations数组中定义多个配置,然后通过调试启动下拉菜单快速切换,可以为“开发”、“测试”、“生产”环境分别配置。 - 调试 Web 应用:对于前端或全栈应用,通常需要同时配置
launch.json(用于启动后端服务)和tasks.json(用于构建前端代码),调试前端时,可能会使用浏览器开发者工具的远程调试功能。 - 检查路径:确保
program、cwd等路径配置正确,这是最常见的调试失败原因之一。 - 查看调试控制台:如果调试失败,记得查看 VS Code 的“调试控制台”(“视图” > “调试控制台”),它会显示调试器的错误信息或输出。
- 保存配置:修改 `launch



还没有评论,来说两句吧...