VS Code 工作区怎样配置多根文件夹

VS Code 的多根工作区（Multi-root Workspace）适合把几个有关联、但不在同一个父目录下的文件夹放进同一个窗口。例如把应用代码目录 app 和文档目录 docs 一起打开。配置完成后，Explorer 会把它们显示为并列的根目录；保存工作区后，还可以通过一个 .code-workspace 文件恢复这组目录和工作区级设置。

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

最稳妥的路径是：先打开一个目录，再用“文件 → 将文件夹添加到工作区”加入第二个目录，确认 Explorer 出现两个根目录后执行“将工作区另存为”。如果设置看起来不生效，先判断它是用户级、工作区级还是文件夹级设置。

下面的界面图是为本文生成的原创操作示意图，用来解释界面关系，不代表真实 VS Code 截图，也不是本机运行证据。

什么时候应该使用多根工作区

普通单文件夹模式已经能覆盖大多数项目。只有当几个目录需要在同一个编辑窗口里协作时，多根工作区才更合适，例如前端与接口文档、服务代码与部署配置、源码仓库与独立的测试夹具。

它的核心不是把目录物理合并，而是在一个 VS Code 窗口中登记多个根目录。每个根目录仍保留自己的文件结构；搜索、Explorer、任务和调试配置则可以在工作区范围内组织。

通过菜单添加第二个文件夹

先用 VS Code 打开第一个目录，例如 app。然后在顶部菜单选择“文件 → 将文件夹添加到工作区”（英文界面对应 File > Add Folder to Workspace），在文件选择器中选中 docs。添加成功后，Explorer 中会出现两个并列的根目录。

这个操作不会把 docs 移动到 app 里面，也不会改变磁盘上的目录关系。它只改变当前 VS Code 窗口的工作区上下文。你可以右键某个根目录，选择移除工作区中的文件夹；也可以拖动根目录来调整显示顺序。

如果只是把一个文件夹拖到编辑器区域，VS Code 仍可能以单文件夹模式打开它；要创建多根工作区，可以把文件夹拖到 Explorer，或一次拖入多个文件夹。

用命令行一次加入多个目录

已经在终端中定位到目录时，可以让 code 命令直接把多个文件夹放进一个多根工作区。下面示例假设当前路径下有 app 和 docs 两个目录：

# 一次打开两个目录，VS Code 会创建一个多根工作区
code app docs

# 给最后一个活动的 VS Code 实例追加一个根目录
code --add docs

多目录参数适合从零创建窗口；--add 适合已经打开了一个工作区、只想追加目录的情况。命令行方式仍然只登记工作区关系，不会复制或移动文件。

保存为可复用的 .code-workspace 文件

多个目录加入后，工作区通常会显示为未命名状态。选择“文件 → 将工作区另存为”，为它保存一个例如 project.code-workspace 的文件。保存后，这个文件会成为工作区入口，重新打开它即可恢复 app 和 docs 两个根目录。

工作区文件本质上是 JSON。下面是一个精简结构，路径可以是相对工作区文件的路径，也可以按 VS Code 支持的规则使用绝对路径：

{
  "folders": [
    { "path": "app" },
    { "path": "docs" }
  ],
  "settings": {
    "files.autoSave": "afterDelay"
  }
}

严格 JSON 不支持注释，所以不要为了说明字段而把注释写进这个配置文件。folders 描述根目录列表，settings 保存工作区范围的设置；实际保存时，应以 VS Code 自动生成的文件为准，不要手写不存在的字段。

设置看起来不生效时先看作用域

多根工作区最容易产生的误解是：把任意一个目录下的 .vscode/settings.json 当成整个窗口的设置。VS Code 会区分用户设置、工作区设置和文件夹设置；在多根工作区中，文件夹设置只作用于对应根目录，工作区设置才面向整个工作区。

• 用户设置：通常对所有 VS Code 窗口生效，适合个人编辑习惯。
• 工作区设置：写入 .code-workspace，适合多个根目录共同使用的配置。
• 文件夹设置：放在某个根目录的 .vscode/settings.json 中，只针对该根目录的资源设置。

一些影响整个编辑器窗口的设置不能由两个根目录分别各写一份来解决。例如两个项目不应该试图分别决定同一个窗口的缩放级别。遇到冲突时，可以在设置编辑器中确认当前打开的是 User、Workspace 还是 Folder 选项卡。

另外，工作区设置通常优先于用户设置；文件夹设置则可能覆盖工作区或用户设置。排查时不要只看设置值，还要看设置编辑器顶部显示的作用域。

保存后怎样确认配置成功

完成配置后，可以按下面的顺序做界面确认：

1. Explorer 中能看到 app 与 docs 两个并列根目录。
2. 窗口标题或 Explorer 中能看到已保存的工作区名称，而不是长期停留在未命名工作区。
3. 关闭窗口后重新打开 project.code-workspace，两个根目录仍然存在。
4. 打开设置编辑器，分别查看 User、Workspace、Folder 选项卡，确认配置写入了预期作用域。
5. 在全局搜索中确认结果按根目录分组；只搜索某个根目录时，可在包含文件框使用对应的 ./ 路径范围。

如果不想继续保留这组关系，可以从工作区中移除文件夹；如果要彻底恢复单文件夹模式，则重新打开某一个具体目录，而不是继续打开 .code-workspace 文件。

常见问题

添加第二个文件夹后，原来的项目会被移动吗？

不会。多根工作区只记录目录路径和编辑器上下文，不会把目录移动、复制或合并。

多根工作区一定要保存吗？

不一定。临时工作可以保持未命名状态；需要下次恢复或交给团队复用时，再保存为 .code-workspace 文件。

为什么一个根目录的设置没有影响另一个根目录？

因为根目录下的 .vscode/settings.json 通常是文件夹级设置。要让多个根目录共享配置，应把适用的资源设置写到工作区设置中。

为什么拖入一个目录后还是单文件夹模式？

拖到编辑器区域的单个目录可能会直接打开为单文件夹模式。把目录拖到 Explorer，或者用“将文件夹添加到工作区”菜单命令，更容易得到明确的多根工作区状态。

配置多根工作区可以记成三步：先添加并列根目录，再保存 .code-workspace 文件，最后按 User、Workspace、Folder 三种作用域排查设置。目录关系只在工作区中组织，磁盘上的项目边界仍然保持不变。