在 VS Code 中试用

多根工作区

你可以在 Visual Studio Code 中通过多根工作区处理多个项目文件夹。当你在同一时间处理多个相关项目时,这会很有用。例如,你可能有一个包含产品文档的仓库,你希望在更新产品源代码时保持其最新状态。

multi-root hero

注意:如果你想了解更多关于 VS Code“工作区”概念的信息,可以查阅什么是 VS Code“工作区”?除非你明确创建一个多根工作区,否则“工作区”只是你项目的单个根文件夹。

添加文件夹

将另一个文件夹添加到现有工作区很容易。有几种添加文件夹的方法:

将文件夹添加到工作区

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

Add Root Folder

添加根文件夹后,“资源管理器”会将新文件夹显示为文件资源管理器中的根。你可以右键单击任何根文件夹,并使用上下文菜单添加或删除文件夹。

Remove Root Folder

文件资源管理器应像以前一样工作和表现。你可以在根文件夹之间移动文件,并使用上下文菜单和资源管理器视图中提供的任何常见文件操作。

如果配置了文件,则每个根文件夹都支持 files.exclude 等设置;如果配置为全局用户设置,则所有文件夹都支持这些设置。

拖放

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

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

你还可以使用拖放功能重新排序工作区中的文件夹。

多选本机文件打开对话框

使用平台本机文件打开对话框打开多个文件夹将创建一个多根工作区。

命令行 --add

将一个或多个文件夹添加到多根工作区的最后一个活动 VS Code 实例。

  code --add vscode vscode-docs

删除文件夹

你可以通过“从工作区中删除文件夹”上下文菜单命令从工作区中删除文件夹。

工作区文件

当你添加多个文件夹时,它们最初会被放置在一个名为 UNTITLED WORKSPACE(无标题工作区)的工作区中,该名称将一直保留,直到你保存工作区。你不需要保存工作区,除非你想将其放置在永久位置,例如桌面。无标题工作区只要其使用的 VS Code 实例保持打开状态就会存在。一旦你完全关闭一个带有无标题工作区的实例,如果你计划将来再次打开它,系统会要求你保存它。

save workspace dialog

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

工作区另存为...

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

打开工作区文件

要重新打开工作区,你可以:

  • 在平台的资源管理器中双击 .code-workspace 文件。
  • 使用“文件”>“打开工作区”命令并选择工作区文件。
  • 从“文件”>“打开最近的”(⌃R (Windows, Linux Ctrl+R))列表中选择工作区。
    • 工作区带有“(工作区)”后缀,以区别于文件夹。

open recent workspace list

就像在 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"
    }
  ]
}

这将导致以下资源管理器显示:

named folders

如你从上面的示例中看到的,你可以在工作区文件中添加注释。

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

workspace file schema

通用 UI

编辑器

当你使用多根工作区时,VS Code UI 只有一些变化,主要是为了区分不同文件夹之间的文件。例如,如果多个文件夹中的文件存在名称冲突,VS Code 将在选项卡标题中包含文件夹名称。

tabbed headers

如果你始终希望在选项卡标题中显示文件夹,可以使用 workbench.editor.labelFormat 设置的“medium”或“long”值来显示文件夹或完整路径。

"workbench.editor.labelFormat": "medium"

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

quick pick has folder name

如果你正在使用文件图标主题,并且活动主题支持,你将看到一个特殊的工作区图标。

下面你可以看到内置的“极简 (Visual Studio Code)”文件图标主题中的工作区图标:

custom workspace icon

VS Code 的功能,例如全局搜索,适用于所有文件夹,并按文件夹对搜索结果进行分组。

multi-root search results

当你打开一个多根工作区时,你可以通过在“要包含的文件”框中使用 ./ 语法来选择在单个根文件夹中搜索。例如,如果你输入 ./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 会将第一个文件夹中相应的编辑器范围设置添加到新的全局工作区设置中。

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

settings dropdown

你也可以通过以下命令打开特定的设置文件:

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

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

不支持的文件夹设置

不支持的编辑器范围的文件夹设置将在你的文件夹设置中显示为灰色,并从“默认文件夹设置”列表中筛选掉。你还将在设置前面看到一个信息图标。

unsupported setting information

调试

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

debugging dropdown

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

你还可以在 vscode-tslint 工作区中看到 tslinttslint-servertslint-tests 文件夹的三个“添加配置”命令。“添加配置”命令将打开文件夹的 .vscode 子文件夹中现有的 launch.json 文件,或者创建一个新文件并显示调试配置模板下拉菜单。

debugging template dropdown

变量用于配置(例如 ${workspaceFolder} 或现已废弃的 ${workspaceRoot})时,是相对于它们所属的文件夹解析的。可以通过将根文件夹的名称附加到变量(用冒号分隔)来为每个工作区文件夹限定变量范围。

工作区启动配置

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

Workspace Settings

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

Add Config

复合启动配置可以通过名称引用各个启动配置,只要名称在工作区中是唯一的,例如:

  "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 版本。

tasks dropdown

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

工作区任务配置

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

源代码管理

对于多根工作区,有一个“源代码管理提供程序”部分,当你有多个活动存储库时,它会提供一个概述。这些可以由多个 SCM 提供程序贡献;例如,你可以让 Git 存储库与 Azure DevOps Server 工作区并存。当你在此视图中选择存储库时,你可以在下方看到源代码管理详细信息。

multiple scm providers

你可以使用 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"]
  }
}

后续步骤

常见问题

如何回到单个项目文件夹的工作模式?

你可以关闭工作区并直接打开文件夹,或者从工作区中删除该文件夹。

作为扩展作者我需要做什么?

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