1. 项目概述：搞懂 launch.json 和 tasks.json，才是 VS Code 真正上手的分水岭
刚接触 VS Code 的人，常以为装上插件、写完代码、点一下绿色三角就能运行——结果要么报错“找不到调试器”，要么提示“终端中未定义任务”，要么改了配置却毫无反应。我带过不少刚从其他编辑器转来的开发者，包括某高校计算机系大三学生和某初创公司前端实习生，他们卡在同一个地方：不是不会写代码，而是根本没理解 VS Code 的执行逻辑底层到底靠什么驱动。launch.json 和 tasks.json 这两个文件，就是 VS Code 区别于普通文本编辑器的核心“操作系统级配置”。它们不处理语法高亮，也不管代码补全，但一旦缺失或错配，整个开发流就断在“写完→运行→验证”这个最基础环节。简单说：tasks.json 定义“怎么构建/编译/打包”，launch.json 定义“怎么启动/附加/调试”。二者配合，才构成一个可闭环的本地开发环境。比如你用 TypeScript 写前端，tasks.json 负责调用 tsc 编译成 JS，launch.json 则负责用 Chrome 启动编译后的 HTML 并挂载调试器；又比如你用 Python 写脚本，tasks.json 可能只是清空pycache目录并安装依赖，launch.json 则指定用哪个 Python 解释器、传什么参数、是否等待输入。这不是“高级技巧”，而是每个真实项目每天都要触发的底层动作。很多人花三天学 React Hooks，却不愿花三十分钟理清这两个 JSON 文件的字段含义和协作关系，结果反复重启 VS Code、重装插件、查 Stack Overflow，其实问题全在 .vscode/ 目录下那两百来行 JSON 配置里。本文不讲抽象概念，只拆解真实场景下的字段选择逻辑、参数计算依据、错误日志定位方法，以及我踩过的七个典型坑——全部来自某跨平台桌面应用开发项目的真实日志记录。
2. 核心设计思路：为什么必须分开配置？tasks.json 和 launch.json 的职责边界在哪？
2.1 本质差异：构建流水线 vs 调试会话，是两类完全不同的生命周期管理
很多初学者把 tasks.json 当成“快捷键绑定”，把 launch.json 当成“运行按钮设置”，这是根本性误解。二者在 VS Code 架构中属于不同层级的抽象：tasks.json 对应的是“构建系统（Build System）”，launch.json 对应的是“调试适配器协议（Debug Adapter Protocol, DAP）”。这个区别决定了它们的设计哲学完全不同。
先看 tasks.json。它的核心使命是“执行一个或多个命令，并返回成功/失败状态”。这些命令可以是 shell 脚本、npm 脚本、Makefile 目标，甚至是一个 Python 小程序。VS Code 不关心你执行的是什么，只关心三点：命令路径是否可执行、参数是否合法、退出码是否为 0。因此 tasks.json 的结构极度扁平——只有 "version"、"tasks" 数组、每个 task 的 "label"、"type"、"command"、"args"、"group"、"presentation" 等字段。它没有“上下文”概念，每次执行都是全新进程，不继承上一次的环境变量（除非显式声明）。我曾在一个嵌入式项目中看到有人把烧录固件的命令写进 tasks.json，结果因为串口设备被占用导致失败，根源就在于 tasks.json 无法感知设备状态，它只负责发指令。
再看 launch.json。它的核心使命是“建立一个与目标进程的双向通信通道，并控制其执行流”。这需要更复杂的协议支持：设置断点、读取变量、单步执行、暂停恢复……所有这些操作都通过 DAP 协议完成。因此 launch.json 的结构是深度嵌套的：顶层是 "version" 和 "configurations" 数组，每个 configuration 必须指定 "type"（决定使用哪个 Debug Adapter）、"request"（launch 或 attach）、"name"（调试配置名），再根据 type 动态加载对应字段。比如 type 为 "node" 时，关键字段是 "program"、"args"、"env"；type 为 "pwa-chrome" 时，关键字段变成 "url"、"webRoot"、"runtimeExecutable"；type 为 "cppdbg" 时，则要填 "miDebuggerPath"、"setupCommands"。这种动态字段机制，正是 VS Code 支持数十种语言调试的根本原因——它不硬编码逻辑，而是通过 JSON Schema 声明哪些字段对哪种调试器有效。
提示：tasks.json 的 "type" 字段只有 "shell" 和 "process" 两种取值（VS Code 1.80+ 新增 "shellScript"），而 launch.json 的 "type" 字段值由已安装的调试器扩展决定。如果你装了 Python 扩展，就会有 "python" 类型；装了 C/C++ 扩展，就会有 "cppdbg" 类型。这个细节直接决定了你能否在 launch.json 中看到对应字段的智能提示。
2.2 协作逻辑：tasks.json 是 launch.json 的前置依赖，但不是强制依赖
二者最常见的协作模式是：先执行 tasks.json 中的构建任务，再用 launch.json 启动调试。VS Code 提供了 "preLaunchTask" 字段来显式声明这种依赖关系。例如：
{ "version": "2.0.0", "configurations": [ { "name": "Launch with Build", "type": "node", "request": "launch", "program": "${workspaceFolder}/dist/index.js", "preLaunchTask": "build" } ] }这里 "preLaunchTask": "build" 指向 tasks.json 中某个 task 的 "label" 字段值。当点击调试按钮时，VS Code 会先查找 label 为 "build" 的 task 并执行，成功后才启动 Node.js 调试会话。但如果构建失败（比如 TypeScript 编译报错），VS Code 会直接中断流程，不启动调试——这正是我们想要的“质量门禁”。
但要注意：preLaunchTask 不是必需字段。你可以配置一个纯运行配置（不调试），或者一个 attach 配置（附加到已运行进程），此时就不需要构建步骤。比如调试一个长期运行的后台服务，你可能先手动启动服务，再用 launch.json 的 "request": "attach" 模式连接上去。这时 tasks.json 完全不参与。我曾在某物联网网关项目中这样操作：用 tasks.json 启动模拟传感器数据流（一个 Python 脚本），再用另一个 launch.json 配置 attach 到主服务进程，实现“数据源-业务逻辑”分离调试。
2.3 配置粒度：tasks.json 适合原子操作，launch.json 适合场景化组合
tasks.json 的设计哲学是“小而专”。每个 task 应该只做一件事：编译、打包、格式化、测试、部署。这样便于复用和组合。比如你可以定义三个 task：
- "label": "tsc: watch" —— 启动 TypeScript 监听编译
- "label": "eslint: fix" —— 自动修复 ESLint 错误
- "label": "test: unit" —— 运行单元测试
然后在 launch.json 中，根据需要组合调用。而 launch.json 的设计哲学是“大而全”。每个 configuration 是一个完整调试场景的快照，包含所有必要参数。比如前端项目常见的三种调试场景：
- 本地开发服务器：启动 webpack-dev-server，自动打开浏览器，启用 source map
- 生产构建后调试：构建 dist 目录，用 Chrome 启动 index.html，映射源码
- Node.js 后端调试：启动 Express 服务，监听 3000 端口，设置环境变量 NODE_ENV=development
这三个场景各自独立，互不影响，各自在 launch.json 中定义为一个 configuration。VS Code 的调试启动面板会列出所有 configuration 名称，让你一键切换。这种设计让团队协作变得极其简单：新人拉下代码，打开 launch.json，看到 "Debug Frontend"、"Debug Backend"、"Debug E2E Tests" 三个选项，点哪个就进入对应环境，无需记忆命令行参数。
3. 核心字段解析与实操要点：逐个击破最易出错的 12 个字段
3.1 tasks.json 关键字段详解：从命令执行到终端呈现的全链路控制
tasks.json 的核心字段看似简单，但每个都藏着影响体验的关键细节。下面以一个真实的 TypeScript 项目构建 task 为例，逐字段拆解：
{ "version": "2.0.0", "tasks": [ { "label": "tsc: build", "type": "shell", "command": "npx", "args": ["tsc", "--build", "tsconfig.json"], "group": "build", "presentation": { "echo": true, "reveal": "always", "focus": false, "panel": "shared", "showReuseMessage": true, "clear": true }, "problemMatcher": ["$tsc"] } ] }"label": "tsc: build"
这是 task 的唯一标识符，也是 launch.json 中preLaunchTask引用的名称。命名建议采用“工具名: 动作”格式（如 "eslint: fix"、"docker: build"），便于快速识别。注意：label 值不能含空格或特殊字符，否则在 launch.json 中引用会失败。我曾在一个项目中因 label 写成 "Build App"（含空格）导致 preLaunchTask 不生效，排查两小时才发现是 JSON 字符串解析问题。"type": "shell"
表示在 shell 环境中执行命令。VS Code 会根据操作系统自动选择 cmd.exe（Windows）或 bash/zsh（macOS/Linux）。另一种类型 "process" 表示直接执行二进制文件，不经过 shell，因此不支持管道（|）、重定向（>）等 shell 特性。如果你的命令需要&&连接多个操作（如npm install && npm run build），必须用 "shell" 类型。"command": "npx"
这是实际执行的可执行文件名。关键点在于：VS Code 默认只在系统 PATH 中查找，不会自动识别项目根目录下的 node_modules/.bin。所以写"command": "tsc"会失败（除非全局安装了 TypeScript），而"command": "npx"则能正确调用本地安装的 tsc。同理，对于其他工具，推荐统一用 npx 或 npm exec。"args": ["tsc", "--build", "tsconfig.json"]
参数数组必须严格按命令行顺序排列。特别注意：如果参数本身含空格（如文件路径），不要在 args 中加引号，VS Code 会自动处理。错误写法：["--outDir", "./dist folder"]（空格导致路径截断）；正确写法：["--outDir", "./dist folder"]（VS Code 自动包裹引号）。另外，args 中不能使用 shell 变量（如$HOME），需用 VS Code 变量替代（如${env:HOME}）。"group": "build"
将 task 归类，便于在命令面板（Ctrl+Shift+P）中筛选。VS Code 内置 "build"、"test"、"develop" 三个组，对应快捷键 Ctrl+Shift+B（构建）、Ctrl+Shift+T（测试）等。自定义组名（如 "deploy"）也能被识别，但无默认快捷键。"presentation" 对象
控制终端面板行为，这是最容易被忽略却最影响体验的字段："echo": true：在终端显示执行的完整命令（如npx tsc --build tsconfig.json），方便确认是否执行了预期命令。"reveal": "always"：始终将终端面板置顶显示。可选值还有 "silent"（不显示）、"never"（不自动打开）。我强烈推荐 "always"，因为构建失败时你需要第一时间看到错误日志。"focus": false：执行时不自动聚焦终端输入框。设为 true 会导致你正在编辑代码时突然光标跳到终端，打断思路。"panel": "shared"：所有 task 共享同一个终端实例。设为 "new" 则每次新建终端，容易产生大量标签页。"shared" 更清爽，但要注意：如果前一个 task 还在运行（如 tsc --watch），新 task 会复用该终端并可能中断它。"clear": true：执行前清空终端历史。避免旧日志干扰判断，尤其当你频繁构建时。
"problemMatcher": ["$tsc"]
这是 VS Code 的“错误解析引擎”。$tsc是内置匹配器，能识别 TypeScript 编译错误的格式（如error TS2304: Cannot find name 'xxx'.），并将其转换为编辑器中的红色波浪线和问题面板条目。没有它，编译报错只显示在终端，你得手动滚动查找。其他常见匹配器：$eslint-stylish、$mocha-junit、$go。自定义匹配器需用正则表达式，但绝大多数场景用内置即可。
3.2 launch.json 关键字段详解：从进程启动到调试控制的深度定制
launch.json 的字段更多，且高度依赖调试器类型。以下以 Node.js 和 Chrome 调试为例，解析最常配置的 8 个字段：
{ "version": "0.2.0", "configurations": [ { "name": "Debug Frontend (Chrome)", "type": "pwa-chrome", "request": "launch", "url": "http://localhost:3000", "webRoot": "${workspaceFolder}/src", "sourceMapPathOverrides": { "webpack:///src/*": "${webRoot}/*" }, "env": { "NODE_ENV": "development" }, "runtimeExecutable": "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome", "port": 9222, "timeout": 10000 } ] }"name": "Debug Frontend (Chrome)"
调试配置的显示名称，出现在调试启动面板顶部。建议包含环境（Frontend/Backend）、工具（Chrome/Node）、目的（Debug/Test）三要素，避免模糊命名如 "Launch" 或 "Config 1"。名称中可含空格，不影响功能。"type": "pwa-chrome"
指定使用的 Debug Adapter。"pwa-chrome" 是 VS Code 官方维护的现代 Chrome 调试器，支持 ES6+、Source Map、网络请求拦截等。旧版 "chrome" 类型已弃用。其他常用类型："node"（Node.js）、"python"（Python）、"cppdbg"（C/C++）、"java"（Java）。类型决定后续可用字段，务必先确认已安装对应扩展。"request": "launch"
调试请求类型。"launch" 表示启动新进程并调试；"attach" 表示连接到已运行进程。二者不可混用。例如，调试 Express 服务时，若服务已启动，用 "attach" 并指定 "port"；若需 VS Code 自动启动服务，用 "launch" 并配置 "program" 字段。"url": "http://localhost:3000"
Chrome 启动后访问的 URL。必须是完整 URL（含协议），不能是相对路径。如果服务未启动，Chrome 会显示“无法连接”页面，但调试器仍会等待。此时需确保服务已在其他终端启动，或改用 "preLaunchTask" 自动启动。"webRoot": "${workspaceFolder}/src"
告诉调试器源码根目录在哪里。这是 Source Map 映射的关键。当 Chrome 加载压缩后的 JS（如/static/js/main.abc123.js），调试器需知道它对应源码中的/src/App.tsx。webRoot就是这个映射的基准路径。${workspaceFolder}是 VS Code 内置变量，指向当前工作区根目录。绝对路径写法（如 "/Users/name/project/src"）也可用，但不推荐，缺乏可移植性。"sourceMapPathOverrides": { "webpack:///src/": "${webRoot}/" }
解决 Webpack 生成的 Source Map 路径与实际文件路径不一致的问题。Webpack 默认在 Source Map 中写webpack:///src/App.tsx，但你的文件实际在/project/src/App.tsx。这个对象就是做路径重写：把左边模式匹配到的路径，替换成右边的路径。webpack:///src/*匹配所有webpack:///src/xxx，"${webRoot}/*"替换为/project/src/xxx。不同打包工具路径前缀不同：Vite 用vite:///，Rollup 用rollup:///，需按实际调整。"env": { "NODE_ENV": "development" }
向启动的进程注入环境变量。这对前端框架（如 React/Vue）至关重要，因为NODE_ENV=production会启用代码压缩和禁用警告。注意：env 只影响当前调试会话，不影响系统全局环境变量。如果需要多个变量，直接添加键值对即可。"runtimeExecutable" 和 "port"
"runtimeExecutable"指定 Chrome 可执行文件路径，用于启动特定版本的 Chrome（如 Canary 版）。macOS 路径如示例，Windows 路径为"C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe"。"port"指定 Chrome DevTools 协议监听端口，默认 9222。如果端口被占用（如另一 Chrome 实例已用），调试会失败，此时需改端口或关闭冲突进程。
4. 实操全流程：从零开始配置一个完整的 React + Node.js 全栈调试环境
4.1 项目结构与前提条件：明确起点，避免环境差异导致的配置漂移
我们以一个典型的全栈项目为例，结构如下：
my-fullstack-app/ ├── client/ # React 前端 │ ├── public/ │ ├── src/ │ ├── package.json │ └── tsconfig.json ├── server/ # Express 后端 │ ├── src/ │ ├── package.json │ └── tsconfig.json ├── package.json # 根目录，含跨项目脚本 └── .vscode/ # 配置文件所在目录前提条件（必须满足，否则配置无效）：
- 已全局安装 VS Code（版本 ≥ 1.75）
- 已安装官方扩展：ESLint、Prettier、TypeScript、React Native Tools（可选）、Debugger for Edge（可选）
- 已安装项目依赖：在 client/ 和 server/ 目录分别运行
npm install - 已安装 TypeScript 编译器：
npm install -D typescript（client/server 各自安装） - 已安装调试器扩展：Debugger for Chrome（前端）、@vscode/vsce（后端，VS Code 1.80+ 内置）
注意：VS Code 的调试能力严重依赖扩展。没有安装对应语言的调试器扩展，launch.json 中的 type 字段将无智能提示，且调试会直接失败。切勿跳过此步。
4.2 配置 tasks.json：构建前端与后端的原子任务
在项目根目录创建.vscode/tasks.json，内容如下：
{ "version": "2.0.0", "tasks": [ { "label": "client: build", "type": "shell", "command": "npx", "args": ["tsc", "--build", "client/tsconfig.json"], "group": "build", "presentation": { "echo": true, "reveal": "always", "focus": false, "panel": "shared", "showReuseMessage": true, "clear": true }, "problemMatcher": ["$tsc"] }, { "label": "server: build", "type": "shell", "command": "npx", "args": ["tsc", "--build", "server/tsconfig.json"], "group": "build", "presentation": { "echo": true, "reveal": "always", "focus": false, "panel": "shared", "showReuseMessage": true, "clear": true }, "problemMatcher": ["$tsc"] }, { "label": "client: start dev server", "type": "shell", "command": "npm", "args": ["run", "start"], "group": "develop", "isBackground": true, "problemMatcher": [], "presentation": { "echo": true, "reveal": "never", "focus": false, "panel": "shared", "showReuseMessage": true, "clear": false } }, { "label": "server: start dev server", "type": "shell", "command": "npm", "args": ["run", "dev"], "group": "develop", "isBackground": true, "problemMatcher": [], "presentation": { "echo": true, "reveal": "never", "focus": false, "panel": "shared", "showReuseMessage": true, "clear": false } } ] }关键点说明：
- 两个构建任务（client: build / server: build）使用
--build参数，利用 TypeScript 的项目引用功能，确保增量编译。 - 两个开发服务器任务（client: start dev server / server: start dev server）设置
"isBackground": true，表示它们是长期运行的任务（如 webpack-dev-server、nodemon）。VS Code 会监控其输出，直到看到"ready on http://localhost:3000"这类就绪消息才认为启动成功。为此，需配置problemMatcher为空（[]），否则会因无错误匹配而超时失败。 "reveal": "never"对开发服务器很关键：避免每次启动都弹出终端遮挡代码编辑区。"clear": false保留日志，方便查看请求记录和错误堆栈。
4.3 配置 launch.json：组合前端与后端的调试场景
在项目根目录创建.vscode/launch.json，内容如下：
{ "version": "0.2.0", "configurations": [ { "name": "Debug Client (Chrome)", "type": "pwa-chrome", "request": "launch", "url": "http://localhost:3000", "webRoot": "${workspaceFolder}/client/src", "sourceMapPathOverrides": { "webpack:///src/*": "${webRoot}/*" }, "preLaunchTask": "client: start dev server", "port": 9222, "timeout": 15000 }, { "name": "Debug Server (Node.js)", "type": "node", "request": "launch", "program": "${workspaceFolder}/server/dist/index.js", "preLaunchTask": "server: build", "env": { "NODE_ENV": "development", "PORT": "4000" }, "console": "integratedTerminal", "internalConsoleOptions": "neverOpen", "sourceMaps": true, "outFiles": ["${workspaceFolder}/server/dist/**/*.js"] }, { "name": "Debug Fullstack (Attach)", "type": "node", "request": "attach", "port": 9229, "address": "localhost", "localRoot": "${workspaceFolder}/server/src", "remoteRoot": "${workspaceFolder}/server/src", "sourceMaps": true, "outFiles": ["${workspaceFolder}/server/dist/**/*.js"] } ], "compounds": [ { "name": "Debug Fullstack", "configurations": ["Debug Client (Chrome)", "Debug Server (Node.js)"] } ] }关键点说明：
- "Debug Client (Chrome)"：使用
preLaunchTask启动前端开发服务器，确保 Chrome 启动时服务已就绪。sourceMapPathOverrides适配 Webpack 默认路径。 - "Debug Server (Node.js)"：使用
preLaunchTask构建后端，再启动调试。"program"指向编译后的入口文件（dist/index.js），而非源码（src/index.ts），因为 Node.js 只能执行 JS。"outFiles"告诉调试器在哪里找生成的 JS 文件，以便关联 Source Map。 - "Debug Fullstack (Attach)"：这是一个备用方案。当后端已用
--inspect=9229参数启动（如npm run dev -- --inspect=9229），此配置可直接附加调试，无需重启服务。"localRoot"和"remoteRoot"在本地调试时相同，但若调试远程服务器，需分别设置本地源码路径和远程服务器上的路径。 - "compounds"：复合配置，允许一键启动多个调试会话。选择 "Debug Fullstack"，VS Code 会同时启动 Chrome 调试前端，并启动 Node.js 调试后端，两个终端并排显示，完美模拟真实协作场景。
4.4 验证与调试：三步确认配置是否生效
配置完成后，按以下步骤验证：
检查任务列表：按
Ctrl+Shift+P（Windows/Linux）或Cmd+Shift+P（macOS），输入 "Tasks: Run Task"，回车，在列表中应看到 "client: build"、"server: build" 等选项。选择任一任务，观察终端是否正确执行并显示输出。检查调试配置：按
Ctrl+Shift+D（Windows/Linux）或Cmd+Shift+D（macOS），在调试启动面板顶部，应看到 "Debug Client (Chrome)"、"Debug Server (Node.js)"、"Debug Fullstack" 三个选项。点击下拉箭头旁的齿轮图标，确认launch.json被正确加载，无 JSON 解析错误。执行全栈调试：选择 "Debug Fullstack"，点击绿色三角按钮。预期行为：
- 终端 1：启动前端开发服务器，输出
Compiled successfully!和You can now view...； - 终端 2：执行后端构建，输出
Found 0 errors. Watching for file changes.； - 终端 3：启动 Node.js 调试，输出
Debugger listening on ws://127.0.0.1:9229/...； - Chrome 自动启动，访问
http://localhost:3000，页面正常加载； - 在 client/src/App.tsx 和 server/src/index.ts 中设置断点，刷新页面或发起 API 请求，断点应被命中。
- 终端 1：启动前端开发服务器，输出
如果任一环节失败，立即查看对应终端的错误日志。常见失败原因见下一节。
5. 常见问题与排查技巧实录：七个真实踩坑案例与速查解决方案
5.1 问题速查表：高频故障现象、根本原因与解决步骤
| 故障现象 | 根本原因 | 解决步骤 | 实测耗时 |
|---|---|---|---|
| 点击调试无反应，终端无任何输出 | launch.json 中type字段值对应的调试器扩展未安装 | 1. 打开扩展视图（Ctrl+Shift+X） 2. 搜索 "Debugger for Chrome" 或 "Node.js"，安装并重载窗口 3. 检查 launch.json中type是否拼写正确（如 "pwa-chrome" 不是 "chrome"） | 2 分钟 |
| preLaunchTask 执行后调试不启动 | tasks.json 中 task 的label与 launch.json 中preLaunchTask值不完全一致（含空格、大小写） | 1. 复制preLaunchTask的值2. 在 tasks.json 中搜索该字符串，确认 label字段值完全匹配3. 检查是否有不可见字符（如全角空格） | 5 分钟 |
| Chrome 启动但页面空白，控制台报 "Failed to load resource" | url字段指向的地址无服务响应，或webRoot路径错误导致 Source Map 无法加载 | 1. 手动在浏览器访问http://localhost:3000，确认服务正常2. 检查 webRoot是否指向源码目录（如client/src），而非构建目录（client/dist）3. 在 Chrome 开发者工具 Sources 面板，展开 webpack://，确认能展开源码树 | 8 分钟 |
| Node.js 调试断点不命中，显示 "Unverified breakpoint" | program指向源码（.ts）而非编译后文件（.js），或outFiles路径未覆盖生成的 JS | 1. 确认program值为"${workspaceFolder}/server/dist/index.js"（非.ts）2. 检查 outFiles是否包含"${workspaceFolder}/server/dist/**/*.js"3. 运行 tsc --build server/tsconfig.json，确认dist目录下有生成的 JS 文件 | 10 分钟 |
| 终端报错 "Command 'npx' not found" | 系统未安装 Node.js，或 VS Code 启动时未加载 PATH 环境变量 | 1. 终端中运行which npx（macOS/Linux）或where npx（Windows），确认路径2. 如果 VS Code 是从 Dock/Launcher 启动，PATH 可能未加载。改为终端中运行 code .启动 VS Code3. 或在 VS Code 设置中搜索 "terminal integrated env"，添加 PATH到terminal.integrated.env.os | 15 分钟 |
| Source Map 显示 "No source available" | sourceMapPathOverrides规则未匹配 Webpack 生成的 Source Map 路径 | 1. 在 Chrome 开发者工具 Sources 面板，找到一个.js文件，右键 → "Add source map"2. 查看 Source Map 文件内容，找到 sources字段（如["webpack:///src/App.tsx"]）3. 将 webpack:///src/*替换为实际前缀，如vite:///src/* | 12 分钟 |
| 调试时 CPU 占用 100%，VS Code 卡死 | sourceMaps设为true但outFiles路径过于宽泛（如"**/*.js"），导致调试器扫描整个工作区 | 1. 将outFiles限定为具体目录，如"${workspaceFolder}/server/dist/**/*.js"2. 禁用不必要的 sourceMaps（如仅调试 JS 时设为false）3. 在 VS Code 设置中搜索 "debug.javascript.autoAttachFilter"，设为 "onlyWithFlag" | 3 分钟 |
5.2 独家避坑技巧：那些文档里不会写的实战经验
技巧一：用echo字段做配置自检
在 tasks.json 的每个 task 中，添加"echo": true，并在args中加入一个唯一标识符。例如：
"args": ["--version", "&&", "echo", "=== TASK: client: build ==="]这样每次执行任务，终端都会显示清晰的分隔线。当多个 task 并行时，你能一眼看出哪个任务在输出，避免日志混淆。我在某大型微前端项目中，用此法快速定位到是子应用 A 的构建任务阻塞了整个流水线。
技巧二：presentation.clear的时机陷阱"clear": true很有用，但有个隐藏问题：如果 task 是isBackground: true（如开发服务器），clear会在每次任务启动时清空终端，导致你丢失宝贵的启动日志（如端口号、就绪消息）。解决方案是：对非构建类 task，设"clear": false；对构建类 task，设"clear": true。并在presentation.reveal上做区分——构建任务用"always"，开发服务器用"never"。
技巧三：problemMatcher的精准匹配
内置$tsc匹配器很好，但它会捕获所有 TypeScript 输出，包括警告（warning）。如果你只想在错误（error）时中断构建，需自定义匹配器。在 tasks.json 中添加：
"problemMatcher": { "owner": "typescript", "fileLocation": ["relative", "${workspaceFolder}"], "pattern": { "regexp": "^(.*):([0-9]+):([0-9]+):\\s+(error|warning)\\s+(TS[0-9]+):\\s+(.*)$", "file": 1, "line": 2, "column": 3, "severity": 4, "code": 5, "message": 6 }, "background": { "activeOnStart": true, "beginsPattern": "^.*Compiling.*$", "endsPattern": "^.*Found [0-9]+ error.*$" } }这个正则只匹配error TSxxxx，忽略warning TSxxxx，让构建更“安静”。
技巧四：compounds的启动顺序控制
VS Code 的 compound 配置默认并行启动所有 configuration，但有时你需要严格的先后顺序（如先启后端，再启前端）。此时，将后端配置设为"request": "launch"，前端配置设为"request": "launch"但添加"preLaunchTask": "server: wait for ready"，再在 tasks.json 中定义一个新 task：
{ "label": "server: wait for ready", "type": "shell", "command": "sh", "args": ["-c", "until curl -f http://localhost
