在 VS Code 中尝试

虚拟工作区

GitHub Repositories这样的扩展会在一个或多个由文件系统提供程序支持的文件夹上打开 VS Code。当扩展实现文件系统提供程序时,工作区资源可能不在本地磁盘上,而是虚拟的,位于服务器或云端,并且编辑操作在那里进行。

此配置称为虚拟工作区。当在 VS Code 窗口中打开虚拟工作区时,左下角的远程指示器中会显示一个标签,类似于其他远程开发窗口。

Remote indicator

并非所有扩展都能使用虚拟资源,有些可能需要资源位于磁盘上。某些扩展使用的工具依赖于磁盘访问,需要同步文件访问,或者没有必要的文件系统抽象。在这些情况下,当处于虚拟工作区时,VS Code 会向用户指示他们正在受限模式下运行,并且某些扩展已被禁用或功能受限。

通常,用户希望尽可能多的扩展能在虚拟工作区中工作,并在浏览和编辑远程资源时获得良好的用户体验。本指南将展示扩展如何针对虚拟工作区进行测试,描述允许它们在虚拟工作区中工作的修改,并介绍 virtualWorkspaces 能力属性。

修改扩展以使其支持虚拟工作区也是在Web 版 VS Code中良好运行的重要一步。Web 版 VS Code 完全在浏览器内运行,并且由于浏览器沙箱,工作区是虚拟的。有关更多详细信息,请参阅Web 扩展指南。

我的扩展会受影响吗?

当扩展没有可执行代码,而是纯声明性的(如主题、键绑定、代码片段或语法扩展)时,它可以在虚拟工作区中运行,无需进行任何修改。

带有代码的扩展,即定义 main 入口点的扩展,需要检查并可能需要修改。

在虚拟工作区中运行你的扩展

安装GitHub Repositories扩展,并从命令面板运行打开 GitHub 仓库...命令。该命令会显示一个快速选择下拉列表,你可以在其中粘贴任何 GitHub URL,或者选择搜索特定的仓库或拉取请求。

这会为虚拟工作区打开一个 VS Code 窗口,其中所有资源都是虚拟的。

检查扩展代码是否已为虚拟资源做好准备

VS Code API 对虚拟文件系统的支持已经存在相当长一段时间了。你可以查看文件系统提供程序 API

文件系统提供程序是为新的 URI 方案(例如 vscode-vfs)注册的,该文件系统上的资源将由使用该方案的 URI(vscode-vfs://github/microsoft/vscode/package.json)表示。

检查你的扩展如何处理从 VS Code API 返回的 URI

  • 切勿假设 URI 方案是 fileURI.fsPath 只能在 URI 方案为 file 时使用。
  • 注意查找 fs Node 模块在文件系统操作中的用法。如果可能,请使用 vscode.workspace.fs API,它会委托给适当的文件系统提供程序。
  • 检查依赖于 fs 访问的第三方组件(例如,语言服务器或 Node 模块)。
  • 如果你从命令运行可执行文件和任务,请检查这些命令在虚拟工作区窗口中是否有意义,或者是否应该禁用它们。

标记你的扩展是否支持虚拟工作区

package.jsoncapabilities 下的 virtualWorkspaces 属性用于指示扩展是否支持虚拟工作区。

不支持虚拟工作区

以下示例声明一个扩展不支持虚拟工作区,并且不应在此设置中由 VS Code 启用。

{
  "capabilities": {
    "virtualWorkspaces": {
      "supported": false,
      "description": "Debugging is not possible in virtual workspaces."
    }
  }
}

部分和完全支持虚拟工作区

当扩展支持或部分支持虚拟工作区时,它应定义 "virtualWorkspaces": true

{
  "capabilities": {
    "virtualWorkspaces": true
  }
}

如果一个扩展能够工作,但功能有限,它应该向用户解释其限制

{
  "capabilities": {
    "virtualWorkspaces": {
      "supported": "limited",
      "description": "In virtual workspaces, resolving and finding references across files is not supported."
    }
  }
}

该描述会显示在“扩展”视图中

Extensions view

然后,扩展应禁用虚拟工作区中不支持的功能,具体方法如下所述。

默认

对于尚未填写 virtualWorkspaces 能力的所有扩展,默认设置为 "virtualWorkspaces": true

然而,在测试虚拟工作区时,我们列出了我们认为应在虚拟工作区中禁用的扩展列表。该列表可在问题 #122836中找到。这些扩展默认设置为 "virtualWorkspaces": false

当然,扩展作者更有能力做出此决定。扩展的 package.json 中的 virtualWorkspaces 能力将覆盖我们的默认设置,我们最终将弃用此列表。

在虚拟工作区打开时禁用功能

禁用命令和视图贡献

命令、视图和许多其他贡献的可用性可以通过when 子句中的上下文键来控制。

当所有工作区文件夹都位于虚拟文件系统上时,会设置 virtualWorkspace 上下文键。以下示例仅在非虚拟工作区中显示命令 npm.publish 在命令面板中

{
  "menus": {
    "commandPalette": [
      {
        "command": "npm.publish",
        "when": "!virtualWorkspace"
      }
    ]
  }
}

resourceScheme 上下文键设置为文件资源管理器中当前选定元素或编辑器中打开元素的 URI 方案。

在以下示例中,仅当底层资源位于本地磁盘上时,npm.runSelectedScript 命令才会在编辑器上下文菜单中显示。

{
  "menus": {
    "editor/context": [
      {
        "command": "npm.runSelectedScript",
        "when": "resourceFilename == 'package.json' && resourceScheme == file"
      }
    ]
  }
}

以编程方式检测虚拟工作区

要检查当前工作区是否由非 file 方案组成且是虚拟的,你可以使用以下源代码

const isVirtualWorkspace =
  workspace.workspaceFolders &&
  workspace.workspaceFolders.every(f => f.uri.scheme !== 'file');

语言扩展和虚拟工作区

对虚拟工作区中的语言支持有什么期望?

所有扩展都能完全支持虚拟资源是不现实的。许多扩展使用需要同步文件访问和磁盘上文件的外部工具。因此,只提供有限的功能是可以的,例如以下列出的基本单文件支持。

A. 基本语言支持

  • TextMate 令牌化和着色
  • 特定语言的编辑支持:括号对、注释、回车规则、折叠标记
  • 代码片段

B. 单文件语言支持

  • 文档符号(大纲)、折叠、选择范围
  • 文档高亮、语义高亮、文档颜色
  • 基于当前文件中的符号和静态语言库的补全、悬停、签名帮助、查找引用/声明
  • 格式化、链接编辑
  • 语法验证、同文件语义验证和代码操作

C. 跨文件、工作区感知语言支持

  • 跨文件引用
  • 工作区符号
  • 验证工作区/项目中的所有文件

VS Code 自带的富语言扩展(TypeScript、JSON、CSS、HTML、Markdown)在处理虚拟资源时,其语言支持仅限于单文件。

禁用语言扩展

如果不支持单文件工作,语言扩展也可以决定在虚拟工作区中禁用该扩展。

如果你的扩展同时提供了语法和需要禁用的富语言支持,那么语法也会被禁用。为了避免这种情况,你可以创建一个基本语言扩展(语法、语言配置、代码片段),将其与富语言支持分开,并拥有两个扩展。

  • 基本语言扩展设置 "virtualWorkspaces": true,并提供语言 ID、配置、语法和代码片段。
  • 富语言扩展设置 "virtualWorkspaces": false 并包含 main 文件。它贡献语言支持、命令,并对基本语言扩展具有扩展依赖 (extensionDependencies)。富语言扩展应保留已建立扩展的 ID,以便用户通过安装单个扩展即可继续获得完整功能。

你可以在内置语言扩展(如 JSON)中看到这种方法,它由一个 JSON 扩展和一个 JSON 语言功能扩展组成。

这种分离还有助于处理在不受信任的工作区中运行的受限模式。富语言扩展通常需要信任,而基本语言功能可以在任何设置中运行。

语言选择器

当为语言功能(例如,补全、悬停、代码操作等)注册提供程序时,请务必指定提供程序支持的方案

return vscode.languages.registerCompletionItemProvider(
  { language: 'typescript', scheme: 'file' },
  {
    provideCompletionItems(document, position, token) {
      // ...
    }
  }
);

语言服务器协议 (LSP) 对访问虚拟资源的支持如何?

正在进行将文件系统提供程序支持添加到 LSP 的工作。在语言服务器协议问题 #1264中进行跟踪。