VS Code multi-root 怎样让工作区共享任务配置

当一个仓库同时包含前端、服务端和文档目录时，把它们分别打开会让任务配置散落在多个窗口里。VS Code 的 multi-root 工作区可以把多个根目录放进同一个 .code-workspace 文件，再把跨目录复用的任务集中写在工作区的 tasks 节点中。

这类任务适合统一的构建、检查或测试入口；而只对某一个项目成立的命令，仍然应该留在那个根目录的 .vscode/tasks.json。关键不是把所有任务都搬到一起，而是先分清“工作区共享”与“文件夹专属”。

官方地址：https://code.visualstudio.com/docs/editing/workspaces/multi-root-workspaces

做法是：先用“文件 > 将文件夹添加到工作区”组成 multi-root，再保存为 .code-workspace；随后打开工作区配置文件，在 tasks 中定义 shell 或 process 任务，并用 ${workspaceFolder:根目录名} 指定每个任务的执行位置。

先把多个项目放进同一个工作区

打开第一个项目后，点击顶部菜单“文件”，选择“将文件夹添加到工作区”。在文件选择器中选中第二个项目，资源管理器会把它显示为另一个根目录。也可以从资源管理器的根目录菜单进入同名入口。

刚添加第二个根目录时，工作区可能仍是未命名状态。此时再次打开“文件”菜单，选择“将工作区另存为”，保存成例如 team.code-workspace。保存后，这个文件就是共享配置的载体，使用相对路径更便于提交给团队成员。

确认任务应该写在哪一层

multi-root 有两层任务来源：

工作区级任务只能使用 shell 或 process 类型。每个根目录自己的 tasks.json 则仍按项目边界维护。这样做的好处是：公共任务的入口集中，项目内部任务不会因为另一个根目录加入而互相污染。

打开工作区配置文件

按 ⇧⌘P（Windows/Linux 使用 Ctrl+Shift+P）打开命令面板，输入“Workspaces: Open Workspace Configuration File”。选择后，VS Code 会打开当前 .code-workspace 的配置内容。

如果命令面板里没有这个入口，先确认当前打开的是已经保存的工作区，而不是一个普通单文件夹窗口。未命名工作区也可以工作，但保存后更适合共享和复用。

把共享任务写进 tasks 节点

下面的配置把产品构建和文档测试放在同一个工作区里。示例使用 JSONC，注释是配置文件允许的说明，不要把注释复制到只接受严格 JSON 的其他工具中。

{
  "folders": [
    {
      "name": "Product",
      "path": "product"
    },
    {
      "name": "Documentation",
      "path": "docs"
    }
  ],
  "tasks": {
    "version": "2.0.0",
    "tasks": [
      {
        // 共享入口：只在 Product 根目录执行构建命令。
        "label": "Build Product",
        "type": "shell",
        "command": "npm run build",
        "options": {
          // 用根目录名限定 cwd，避免从当前活动文件夹误执行。
          "cwd": "${workspaceFolder:Product}"
        },
        "problemMatcher": []
      },
      {
        // 共享入口：文档测试使用另一个根目录的依赖环境。
        "label": "Test Documentation",
        "type": "shell",
        "command": "npm test",
        "options": {
          "cwd": "${workspaceFolder:Documentation}"
        },
        "problemMatcher": []
      },
      {
        // 汇总入口：先构建产品，再按顺序运行文档测试。
        "label": "Build And Test",
        "dependsOn": ["Build Product", "Test Documentation"],
        "dependsOrder": "sequence"
      }
    ]
  }
}

这里最容易写错的是 cwd。不写它时，命令可能依赖当前活动文件夹；写成 ${workspaceFolder:Product} 后，任务无论从哪个根目录的文件启动，都会进入 Product 根目录。变量中的名称必须与 folders 里的 name 对应。

dependsOn 列出多个任务时默认可以并行执行；示例显式设置了 dependsOrder 为 sequence，因此先构建再测试。如果两个任务彼此独立，把它们改成并行通常更省时间，但要确认它们不会争用同一个输出目录。

从任务面板执行并确认目录

保存工作区配置后，打开“终端 > 运行任务”，列表中应出现 Build Product、Test Documentation 和 Build And Test。先执行单个任务确认路径，再执行汇总任务。

1. 选择“终端 > 运行任务 > Build Product”。
2. 观察新终端的工作目录是否指向 product 根目录。
3. 确认构建命令退出成功，再运行 Build And Test。
4. 如果任务名称不在列表中，重新打开工作区配置文件并检查 tasks.version 是否为 2.0.0。

需要查看变量实际展开结果时，可以临时增加一个只输出目录的任务：

{
  "label": "Show Product Folder",
  "type": "shell",
  // 诊断变量展开结果；确认后可删除这个临时任务。
  "command": "echo ${workspaceFolder:Product}",
  "problemMatcher": []
}

哪些情况不要放进共享配置

如果命令依赖某个根目录私有的脚本、私有环境变量或只对该项目有意义的输出目录，就把它放在对应根目录的 .vscode/tasks.json。工作区级配置适合表达“团队从同一入口运行”的动作，不适合把每个项目的内部细节全部暴露到公共文件。

还要注意工作区配置中的路径。相对路径默认相对于 .code-workspace 文件解析；移动工作区文件后，建议重新检查各个根目录是否仍能在资源管理器中打开。任务本身则使用明确的 cwd，不要依赖当前编辑器焦点。

最后用这张表做一次验收

一句话记忆：跨根目录的公共入口放在 .code-workspace，项目自己的命令放在对应的 .vscode/tasks.json；只要给共享任务写清 cwd，multi-root 就不会因为活动文件夹变化而跑错目录。

相关问题

工作区任务为什么只能写 shell 或 process？

工作区配置面向多个根目录，官方只允许在其中定义 shell 和 process 类型。依赖特定项目上下文的任务，应放回根目录自己的任务文件。

${workspaceFolder} 和 ${workspaceFolder:Product} 有什么区别？

前者依赖当前任务所属的工作区文件夹，后者明确指定名为 Product 的根目录。共享任务建议使用带名称的写法，减少从错误目录启动的可能。

多个任务为什么没有按顺序执行？

dependsOn 多任务默认可能并行执行。需要严格先后关系时，给汇总任务增加 "dependsOrder": "sequence"，并保证前置任务有清晰的结束状态。

官方资料：https://code.visualstudio.com/docs/editing/workspaces/workspaces

任务文档：https://code.visualstudio.com/docs/debugtest/tasks

变量说明：https://code.visualstudio.com/docs/reference/variables-reference