多根工作区

在 Visual Studio Code 中，您可以通过多根工作区来处理多个项目文件夹。当您同时处理多个相关项目时，这会很有帮助。例如，您可能有一个包含产品文档的代码仓库，并希望在更新产品源代码时保持该文档为最新版本。

注意：如果您想了解有关 VS Code “工作区”概念的更多信息，可以查阅什么是 VS Code “工作区”？。除非您明确创建多根工作区，否则“工作区”通常仅指您项目的单个根文件夹。

添加文件夹

向现有工作区添加另一个文件夹非常简单。有多种添加文件夹的方式：

将文件夹添加到工作区

文件 > 将文件夹添加到工作区命令会打开一个“打开文件夹”对话框，以选择新文件夹。

一旦添加了根文件夹，资源管理器将在文件资源管理器中将新文件夹显示为一个根目录。您可以右键单击任何根文件夹，并使用上下文菜单来添加或删除文件夹。

文件资源管理器的功能和行为应与以前一样。您可以在根文件夹之间移动文件，并使用上下文菜单和资源管理器视图中提供的任何典型文件操作。

如果已配置，像 files.exclude 这样的设置对每个根文件夹都支持；如果配置为全局用户设置，则对所有文件夹都生效。

拖放

您可以使用拖放操作将文件夹添加到工作区。将一个文件夹拖到文件资源管理器中，即可将其添加到当前工作区。您甚至可以选择并拖动多个文件夹。

注意：将单个文件夹拖放到 VS Code 的编辑器区域仍会以单文件夹模式打开该文件夹。如果将多个文件夹拖放到编辑器区域，则会创建一个新的多根工作区。

您还可以使用拖放来重新排列工作区中的文件夹。

通过原生文件打开对话框多选

使用您平台的原生文件打开对话框打开多个文件夹，将会创建一个多根工作区。

命令行 --add

将一个或多个文件夹添加到上一个活动的 VS Code 实例，以创建多根工作区。

  code --add vscode vscode-docs

移除文件夹

您可以使用上下文菜单中的从工作区移除文件夹命令来从工作区中移除一个文件夹。

工作区文件

当您添加多个文件夹时，它们最初会被放置在一个名为未命名工作区的工作区中，该名称将一直保留到您保存工作区为止。您不需要立即保存工作区，除非您想将其保存在一个永久的位置，例如您的桌面上。只要使用未命名工作区的 VS Code 实例保持打开状态，该工作区就会存在。一旦您完全关闭一个包含未命名工作区的实例，如果您计划将来再次打开它，系统会提示您保存它。

当您保存工作区时，它将创建一个 .code-workspace 文件，文件名将显示在文件资源管理器中。

将工作区另存为...

如果您想将工作区文件移动到新位置，可以使用文件 > 将工作区另存为命令，该命令会自动设置相对于新工作区文件位置的正确文件夹路径。

打开工作区文件

要重新打开工作区，您可以：

• 在您平台的资源管理器中双击 .code-workspace 文件。
• 使用文件 > 打开工作区命令并选择工作区文件。
• 从文件 > 打开最近的文件 (⌃R (Windows、Linux 为 Ctrl+R)) 列表中选择工作区。
  • 工作区会带有一个（工作区）后缀，以区别于普通文件夹。

与在 VS Code 中打开单个文件夹时的关闭文件夹类似，有一个关闭工作区 (⌘K F (Windows、Linux 为 Ctrl+K F)) 命令来关闭活动的工作区。

工作区文件结构

.code-workspace 的结构相当简单。它包含一个文件夹数组，路径可以是绝对路径或相对路径。当您想要共享工作区文件时，使用相对路径更好。

您可以使用 name 属性覆盖文件夹的显示名称，以便在资源管理器中为文件夹赋予更有意义的名称。例如，您可以将项目文件夹命名为“Product”和“Documentation”，以便通过文件夹名称轻松识别内容。

{
  "folders": [
    {
      // Source code
      "name": "Product",
      "path": "vscode"
    },
    {
      // Docs and release notes
      "name": "Documentation",
      "path": "vscode-docs"
    },
    {
      // Yeoman extension generator
      "name": "Extension generator",
      "path": "vscode-generator-code"
    }
  ]
}

这将导致以下资源管理器显示效果：

从上面的示例可以看出，您可以在工作区文件中添加注释。

工作区文件还可以在 settings 下包含工作区全局设置，以及在 extensions 下包含扩展推荐，我们将在下面讨论这些内容。

通用用户界面

编辑器

当您使用多根工作区时，VS Code 的用户界面只有一些细微变化，主要是为了消除不同文件夹中文件之间的歧义。例如，如果多个文件夹中的文件存在名称冲突，VS Code 会在选项卡标题中包含文件夹名称。

如果您总是希望在选项卡标题中显示文件夹，可以使用 workbench.editor.labelFormat 设置的 "medium" 或 "long" 值来显示文件夹或完整路径。

"workbench.editor.labelFormat": "medium"

VS Code 的 UI，如打开的编辑器和快速打开 (⌘P (Windows、Linux 为 Ctrl+P)) 列表，都会包含文件夹名称。

如果您正在使用文件图标主题，并且当前主题支持它，您将会看到一个特殊的工作区图标。

下面您可以看到内置的 Minimal (Visual Studio Code) 文件图标主题中的工作区图标。

搜索

VS Code 的功能（如全局搜索）可以跨所有文件夹工作，并按文件夹对搜索结果进行分组。

当您打开一个多根工作区时，可以通过在要包含的文件框中使用 ./ 语法来选择在单个根文件夹中搜索。例如，如果您输入 ./project1/**/*.txt，它将搜索 project1/ 根文件夹下的所有 .txt 文件。

设置

在一个工作区中有多个根文件夹时，每个根文件夹中都可能有一个 .vscode 文件夹，用于定义该文件夹应应用的设置。为避免设置冲突，使用多根工作区时，仅应用资源（文件、文件夹）级别的设置。影响整个编辑器的设置（例如，UI 布局）将被忽略。例如，两个项目不能同时设置缩放级别。

用户设置与单文件夹项目一样受支持，您还可以设置全局工作区设置，这些设置将应用于多根工作区中的所有文件夹。全局工作区设置将存储在您的 .code-workspace 文件中。

{
  "folders": [
    {
      "path": "vscode"
    },
    {
      "path": "vscode-docs"
    },
    {
      "path": "vscode-generator-code"
    }
  ],
  "settings": {
    "window.zoomLevel": 1,
    "files.autoSave": "afterDelay"
  }
}

当您从单文件夹实例切换到多文件夹实例时，VS Code 会将第一个文件夹中适用的编辑器范围设置添加到新的全局工作区设置中。

您可以通过设置编辑器轻松查看和修改不同的设置文件。设置编辑器的选项卡让您可以选择用户设置、全局工作区设置和单个文件夹设置。

您还可以使用以下命令打开特定的设置文件：

• 首选项: 打开用户设置 - 打开您的全局用户设置
• 首选项: 打开工作区设置 - 打开您工作区文件的设置部分。
• 首选项: 打开文件夹设置 - 打开活动文件夹的设置。

全局工作区设置会覆盖用户设置，而文件夹设置可以覆盖工作区或用户设置。

不支持的文件夹设置

不支持的编辑器范围的文件夹设置将在您的文件夹设置中显示为灰色，并会从默认文件夹设置列表中过滤掉。您还会在设置前面看到一个信息图标。

调试

在多根工作区中，VS Code 会在所有文件夹中搜索 launch.json 调试配置文件，并以文件夹名称作为后缀显示它们。此外，VS Code 还会显示在工作区配置文件中定义的启动配置。

上面的示例显示了 TSLint 扩展的调试配置。有一个来自 tslint 扩展文件夹的 launch 配置，用于在 VS Code 扩展宿主中启动该扩展；还有一个来自 tslint-server 文件夹的 attach 配置，用于将调试器附加到正在运行的 TSLint 服务器。

您还可以在 vscode-tslint 工作区中看到针对 tslint、tslint-server 和 tslint-tests 这三个文件夹的添加配置命令。添加配置命令要么会打开文件夹的 .vscode 子文件夹中现有的 launch.json 文件，要么会创建一个新文件并显示调试配置模板下拉菜单。

配置中使用的变量（例如 ${workspaceFolder} 或现已弃用的 ${workspaceRoot}）会相对于它们所属的文件夹进行解析。可以通过将根文件夹的名称附加到变量（用冒号分隔）来为每个工作区文件夹限定变量的作用域。

工作区启动配置

工作区范围的启动配置位于工作区配置文件（在命令面板中选择工作区: 打开工作区配置文件）的 "launch" 部分。

另外，新的启动配置可以通过启动配置下拉菜单中的“添加配置(工作区)”条目添加。

复合启动配置可以通过名称引用单个启动配置，只要这些名称在工作区内是唯一的，例如：

  "compounds": [{
      "name": "Launch Server & Client",
      "configurations": [
        "Launch Server",
        "Launch Client"
      ]
  }]

如果单个启动配置的名称不唯一，可以使用更详细的“folder”语法指定所属文件夹：

  "compounds": [{
      "name": "Launch Server & Client",
      "configurations": [
        "Launch Server",
        {
          "folder": "Web Client",
          "name": "Launch Client"
        },
        {
          "folder": "Desktop Client",
          "name": "Launch Client"
        }
      ]
  }]

除了 compounds，工作区配置文件中的 launch 部分也可以包含常规的启动配置。请确保所有使用的变量都明确地限定于特定文件夹，否则它们对于工作区无效。您可以在变量参考中找到有关明确限定作用域的变量的更多详细信息。

这是一个启动配置的示例，其中程序位于“Program”文件夹中，并且在单步调试时应跳过“Library”文件夹中的所有文件。

"launch": {
  "configurations": [{
      "type": "node",
      "request": "launch",
      "name": "Launch test",
      "program": "${workspaceFolder:Program}/test.js",
      "skipFiles": [
        "${workspaceFolder:Library}/out/**/*.js"
      ]
  }]
}

任务

与 VS Code 搜索调试配置的方式类似，VS Code 也会尝试自动检测工作区中所有文件夹内的 gulp、grunt、npm 和 TypeScript 项目文件中的任务，并搜索 tasks.json 文件中定义的任务。任务的位置会以文件夹名称后缀来标示。请注意，在 tasks.json 中定义的任务必须是 2.0.0 版本。

从上面 TSLint 扩展的工作区示例中，您可以看到有两个来自 tslint 和 tslint-tests 文件夹中 tasks.json 文件的已配置任务，以及许多自动检测到的 npm 和 TypeScript 编译器的已检测任务。

工作区任务配置

工作区范围的任务位于工作区配置文件（在命令面板中选择工作区: 打开工作区配置文件）的 "tasks" 部分。只有 "shell" 和 "process" 类型的任务可以在工作区配置文件中定义。

源代码管理

在多根工作区中，有一个源代码管理提供程序部分，当您有多个活动的仓库时，它会为您提供一个概览。这些仓库可以由多个 SCM 提供程序贡献；例如，您可以将 Git 仓库与 Azure DevOps Server 工作区并排使用。当您在此视图中选择仓库时，您可以在下方看到源代码管理的详细信息。

您可以使用 Ctrl+单击 或 Shift+单击来选择多个仓库。它们的详细信息将显示在下方的独立区域中。

扩展

如果您是扩展开发者，可以查阅我们的采用多根工作区 API指南，了解 VS Code 多根工作区 API 以及如何让您的扩展在多个文件夹中良好运行。

以下是一些已采用多根工作区 API 的热门扩展。

注意：如果某个扩展尚不支持多文件夹，它仍然会在您的多根工作区的第一个文件夹中工作。

扩展建议

VS Code 通过文件夹的 .vscode 子文件夹下的 extensions.json 文件支持文件夹级别的扩展推荐。您还可以通过将全局工作区扩展推荐添加到您的 .code-workspace 文件中来提供这些推荐。您可以使用扩展: 配置推荐扩展 (工作区文件夹)命令来打开您的工作区文件，并将扩展标识符 ({publisherName}.{extensionName}) 添加到 extensions.recommendations 数组中。

{
  "folders": [
    {
      "path": "vscode"
    },
    {
      "path": "vscode-docs"
    }
  ],
  "extensions": {
    "recommendations": ["eg2.tslint", "dbaeumer.vscode-eslint", "esbenp.prettier-vscode"]
  }
}

后续步骤

• 什么是 VS Code “工作区”？ - 更多关于单文件夹和多根工作区的信息。
• 调试 - 了解如何为你的应用程序设置调试。
• 任务 - 任务让您可以在 VS Code 内部运行像编译器这样的外部工具。

常见问题

如何回到处理单个项目文件夹的模式？

您可以关闭工作区并直接打开文件夹，或者从工作区中移除该文件夹。

作为一名扩展开发者，我需要做什么？

请参阅我们的采用多根工作区 API指南。大多数扩展都可以轻松支持多根工作区。