vscode任务系统仅支持同一.code-workspace内跨文件夹任务编排：1. dependson依赖只在当前工作区tasks.json中解析；2. 跨工作区无共享任务注册表，会静默失败；3. 必须将所有关联项目纳入同一folders数组；4. 依赖${workspacefolder:名称}精准定位路径；5. 需设group标识可被依赖任务。
VSCode 本身不支持跨工作区（即多个独立 .code-workspace 文件之间）直接调用任务，所谓“工作区间跨项目运行”实际是常见误解——真正可行且被官方支持的，只有「多根工作区（multi-root workspace）内跨文件夹任务编排」。
为什么 tasks.json 里的 dependsOn 只能在同一个 .code-workspace 内生效
VSCode 的任务系统基于当前激活的工作区上下文解析 tasks.json。一旦你打开的是单个文件夹（File → Open Folder），或两个完全分离的 .code-workspace 文件（比如 backend.code-workspace 和 frontend.code-workspace），它们彼此隔离：进程、配置、终端、任务注册表全不共享。dependsOn 引用的任务名只在当前工作区的 tasks.json（及其包含的子文件夹任务）中查找，跨工作区会静默失败或报 Task not found 错误。
- 错误现象：
dependsOn: ["build:frontend"]在 backend 工作区里执行时无反应，终端不输出，任务面板显示“已跳过” - 根本原因：VSCode 启动任务时，只加载当前工作区定义的
folders下所有.vscode/tasks.json，不会扫描磁盘上其他位置的 workspace 文件 - 验证方式：打开命令面板（
Ctrl+Shift+P），输入 “Tasks: Run Task”，下拉列表里只出现本工作区能识别的任务
正确做法：把要联动的项目塞进同一个 .code-workspace
所有需要任务协同的项目，必须作为 folders 条目写入同一个 .code-workspace 文件。这是唯一受支持的跨项目任务链路基础。
- 路径必须是相对或绝对有效路径，不能是符号链接（部分系统下会失效）
- 推荐使用相对路径（如
"path": "./services/auth-service"），避免硬编码绝对路径导致团队协作失败 - 每个子项目可保留自己的
.vscode/tasks.json，VSCode 会自动合并识别；也可统一放在工作区根目录的.vscode/tasks.json中集中管理 - 若某项目不需要被构建，但需参与依赖链（如只提供
package.json供其他任务读取），仍需列入folders，否则${workspaceFolder:xxx}变量无法解析
${workspaceFolder:xxx} 是跨文件夹执行的关键变量
当多个项目共存于一个工作区时，VSCode 提供命名空间化变量来精准定位每个项目的根目录。没它，command 很可能在错误路径下执行，导致找不到 package.json 或构建脚本。
- 必须先给每个
folder设置"name"字段，例如：{"name":"frontend", "path":"./web-app"} - 然后在任务中用
${workspaceFolder:frontend}替代模糊的${workspaceFolder} - 错误示例：
"options": {"cwd": "${workspaceFolder}"}—— 这只会取第一个folder的路径，不可靠 - 正确示例：
"options": {"cwd": "${workspaceFolder:backend}"}，确保npm run build真正在 backend 目录下运行
复杂依赖链必须用 dependsOn + group 显式控制顺序
并行任务（如同时构建 frontend 和 backend）默认无序；而生成代码类流程（如先编译 Protobuf，再生成 TS 类型）必须串行。仅靠 shell 脚本拼接容易掩盖错误、无法中断、难以调试。
-
dependsOn支持数组，例如："dependsOn": ["build:auth", "build:user"]，表示当前任务等待这两个完成后才启动 - 被依赖的任务必须设
"group": "build"（或其他一致值），否则 VSCode 不认为它是可被依赖的“构建任务” - 如果某个依赖任务失败，默认会跳过后续任务；如需强制执行（如清理任务），得加
"presentation": {"echo": true, "reveal": "always", "panel": "shared"}并手动处理退出码 - 避免循环依赖：A 依赖 B，B 又依赖 A —— VSCode 不报错，但任务会卡死或无限重试
真正难的不是写配置，而是厘清哪些项目必须物理共存于一个工作区——这决定了你的架构边界。一旦选错粒度（比如把不相关的 SaaS 客户后台和内部运维工具强行塞进同一 workspace），tasks.json 会迅速失控，搜索变慢，Git 面板信息过载。跨项目任务不是万能胶，而是有明确作用域的精密齿轮。
