VS Code多根工作区统一配置与任务入口的组织方法

多个相关项目一起开发时，最容易失控的是入口：文件夹要来回切换，任务要分别寻找，公共设置又很难让团队保持一致。VS Code 的多根工作区适合把这些项目放进同一个 Explorer，再用一个 .code-workspace 文件保存统一配置；项目自己的差异则继续留在各根目录的 .vscode 中。

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

最稳妥的组织方式是：工作区文件负责根目录、跨项目设置和公共任务，项目目录负责自己的启动、检查和调试配置。这样既能统一入口，也不会把两个项目的路径和命令硬绑在一起。

步骤一：把多个项目加入同一个工作区

先打开一个项目目录，然后点击 File > Add Folder to Workspace，在文件选择窗口中选择第二个项目。也可以从 Explorer 根目录的右键菜单继续添加。不要把第二个目录直接拖到编辑区：单个目录拖入编辑区仍可能回到单文件夹模式，拖入 Explorer 更容易确认它是新的根目录。

操作完成后，左侧 Explorer 应该同时显示两个可展开的根目录，例如 Web 和 Docs。这个状态说明工作区范围已经建立；以后搜索、打开文件和任务选择都能带上根目录信息。

步骤二：保存并命名工作区

新加入多个根目录后，工作区最初是未命名状态。点击 File > Save Workspace As，把文件保存为例如 team.code-workspace。建议把它放在两个项目的共同上级目录，并使用相对路径；这样同事拿到相同目录结构后，不会因为个人绝对路径不同而失效。

工作区文件还可以用 name 重命名 Explorer 中的显示名称。下面的 JSONC 是结构示例，注释可以保留在 VS Code 的工作区文件里：

{
  "folders": [
    {
      // 前端源码目录，使用相对工作区文件的路径
      "name": "Web",
      "path": "web"
    },
    {
      // 文档与接口说明目录
      "name": "Docs",
      "path": "docs"
    }
  ]
}

保存后可通过 File > Open Recent 重新打开；最近列表中的工作区会带有 Workspace 标识，避免和普通文件夹混淆。

步骤三：把统一设置与公共任务放进 .code-workspace

按 Command Palette > Workspaces: Open Workspace Configuration File 打开工作区配置。跨项目都需要的设置适合写进 settings，例如自动保存和编辑器标签显示；多个项目都能执行的任务适合写进 tasks。工作区层的任务使用 shell 或 process 类型，命令要明确指向目标根目录。

{
  "folders": [
    { "name": "Web", "path": "web" },
    { "name": "Docs", "path": "docs" }
  ],
  "settings": {
    // 让同名文件标签带上根目录，减少误编辑
    "workbench.editor.labelFormat": "medium",
    // 统一保存行为，项目自己的设置仍可单独覆盖
    "files.autoSave": "afterDelay"
  },
  "tasks": {
    // 公共入口只负责调用工作区中的 Web 构建命令
    "version": "2.0.0",
    "tasks": [
      {
        "label": "build-all",
        "type": "shell",
        "command": "npm --prefix ${workspaceFolder:Web} run build",
        "problemMatcher": []
      }
    ]
  }
}

保存后，在设置编辑器中选择 Workspace 范围，或从 Terminal > Run Task 打开任务选择器。能看到 Workspace: build-all，就说明公共入口已被识别。

步骤四：保留项目差异并执行任务

不要为了统一而把所有命令塞进工作区文件。Web 的 lint、Docs 的文档检查等项目专属动作，应放在对应根目录的 .vscode/tasks.json 中，并用 ${workspaceFolder} 表示当前根目录：

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "lint",
      "type": "shell",
      // 变量会解析到当前任务所属的项目根目录
      "command": "npm run lint",
      "options": {
        "cwd": "${workspaceFolder}"
      },
      "problemMatcher": []
    }
  ]
}

再次打开任务选择器时，项目任务会带根目录后缀。选择 Workspace: build-all 执行公共构建，选择 Web: lint 执行 Web 专属检查；底部终端出现成功状态后再继续下一项。两个项目有同名任务时，不要只看任务名，要看它前面的根目录标识。

常见问题

为什么项目自己的设置没有覆盖统一设置？

先确认设置写在哪一层。工作区设置保存在 .code-workspace，根目录设置在该项目的 .vscode/settings.json；具体资源设置可以按项目覆盖，影响整个编辑器界面的设置则不一定适合作为文件夹级配置。

任务选择器里没有显示 tasks.json 的任务怎么办？

检查文件是否位于对应根目录的 .vscode/tasks.json，并确认 version 是 2.0.0。工作区文件里的公共任务还要确认只使用支持的 shell 或 process 类型。

同名文件打开后怎样避免改错项目？

在工作区设置中启用 workbench.editor.labelFormat 为 medium 或 long，让编辑器标签显示根目录。搜索结果和快速打开列表也会带上文件所属根目录。

整理多根工作区时，可以把“是否跨项目共用”作为唯一判断标准：共用的放工作区文件，个别项目需要的留在项目目录。这样重新打开、交接和排查任务时，入口清楚，路径也更容易维护。