VS Code launch.json 的 preLaunchTask 为什么没有执行

按 F5 后如果 VS Code 直接进入调试、却没有先执行编译或启动脚本，先别急着重装扩展。preLaunchTask 不是脚本内容，也不是文件名，它必须逐字匹配 .vscode/tasks.json 里的任务 label。另外，任务功能依赖已打开的工作区文件夹；只打开一个源码文件时，任务和调试配置可能不会按预期工作。

官方地址：https://code.visualstudio.com/docs/debugtest/debugging-configuration

先确认入口：工作区和两个配置文件

在资源管理器中确认项目根目录已打开，并检查是否存在 .vscode/launch.json 和 .vscode/tasks.json。运行和调试面板中选择的配置来自 launch.json，而任务列表来自 tasks.json。二者都在项目目录下时，排查结果才稳定。

把 preLaunchTask 和 label 逐字对齐

假设任务真正的标签是“构建调试文件”，调试配置就要引用这个完整字符串。下面是一个可改写的最小示例；代码中的中文注释解释了匹配关系。

// .vscode/tasks.json：任务名称由 label 决定
{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "构建调试文件",
      "type": "shell",
      "command": "npm run build",
      "problemMatcher": []
    }
  ]
}

// .vscode/launch.json：这里必须引用上面的 label
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "启动调试",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder}/dist/app.js",
      "preLaunchTask": "构建调试文件"
    }
  ]
}

如果这里写成 npm run build、Build 或少一个空格，VS Code 就不会把它当成同一个任务。不要只看终端里显示的命令，要回到任务定义确认 label。

从运行任务入口拆分定位问题

打开顶部菜单“终端”>“运行任务”，选择“构建调试文件”。如果任务没有出现在列表中，优先检查工作区和 tasks.json 的 JSONC 结构；如果任务出现但终端报错，先修复命令、工作目录或 PATH，再回到 F5。这个动作能把“没有调用任务”和“任务调用后失败”分开。

后台任务要让调试器知道“完成”

持续运行的 watch 任务不会自然退出，因此不能只写 "isBackground": true 就期待调试器自动继续。应配置与输出格式匹配的后台 problemMatcher，让 VS Code 识别“服务已就绪”。例如：

如果不确定 matcher 是否适合当前工具，先用“终端 > 运行任务”观察任务输出，再查对应扩展或工具文档。不要把一个会长期占用终端的任务误当成已经完成的构建任务。

最后用三处状态确认修复

1. 在“运行和调试”面板选择包含 preLaunchTask 的配置，按 F5。
2. 看集成终端是否先出现任务命令，再出现任务完成或就绪信息。
3. 确认 dist/app.js 等目标文件已更新，并且调试会话已经命中断点或正常启动。

若只看到调试会话启动，没看到任务终端，回到第一步检查配置引用；若任务终端出现但目标文件没更新，问题在构建命令本身；若一直停在任务阶段，重点检查后台 matcher 和任务是否实际会退出。

常见问题

preLaunchTask 可以直接写任务命令吗？

不可以。它引用的是任务的 label；命令应放在 tasks.json 的 command、script 或相关字段中。

只打开单个文件为什么看不到任务？

任务是工作区级能力。请使用“文件 > 打开文件夹”打开项目根目录，再从运行和调试面板选择配置。

后台任务一定要设置 problemMatcher 吗？

作为 preLaunchTask 时通常需要。它负责告诉 VS Code 后台任务何时达到可继续的状态；普通一次性任务则应通过退出状态结束。