虚拟工作区
诸如 GitHub Repositories 等扩展会在一个或多个由文件系统提供程序支持的文件夹上打开 VS Code。当扩展实现文件系统提供程序时,工作区资源可能不在本地磁盘上,而是虚拟的,位于服务器或云中,编辑操作在那里发生。
这种配置被称为虚拟工作区。当虚拟工作区在 VS Code 窗口中打开时,左下角的远程指示器中会有一个标签进行指示,类似于其他远程开发窗口。
并非所有扩展都能处理虚拟资源,它们可能要求资源位于磁盘上。一些扩展使用依赖磁盘访问、需要同步文件访问或缺乏必要文件系统抽象的工具。在这些情况下,当处于虚拟工作区时,VS Code 会向用户指出他们正运行在受限模式下,并且某些扩展已被禁用或功能受到限制。
通常,用户希望尽可能多的扩展能在虚拟工作区中工作,并在浏览和编辑远程资源时获得良好的用户体验。本指南展示了扩展如何针对虚拟工作区进行测试,描述了使其能够在虚拟工作区中工作的修改,并介绍了 virtualWorkspaces
能力属性。
修改扩展使其能够处理虚拟工作区也是在 VS Code for the Web 中良好工作的重要一步。VS Code for the Web 完全在浏览器内部运行,由于浏览器沙箱的限制,工作区也是虚拟的。有关更多详细信息,请参阅 Web 扩展指南。
我的扩展受影响吗?
当一个扩展没有可执行代码,而完全是声明性的,例如主题、键绑定、代码片段或语法扩展,它可以在虚拟工作区中运行,无需任何修改。
带有代码的扩展,即定义了 main
入口点的扩展,需要检查,并可能需要修改。
在虚拟工作区中运行您的扩展
安装 GitHub Repositories 扩展,并从命令面板运行 Open GitHub Repository... 命令。该命令会显示一个快速选择下拉列表,您可以在其中粘贴任何 GitHub URL,或选择搜索特定的仓库或拉取请求。
这将打开一个 VS Code 窗口,用于虚拟工作区,其中所有资源都是虚拟的。
检查扩展代码是否已为虚拟资源做好准备
VS Code API 对虚拟文件系统的支持已经存在一段时间了。您可以查看文件系统提供程序 API。
文件系统提供程序会为新的 URI Scheme(例如,vscode-vfs
)注册,该文件系统上的资源将由使用该 Scheme 的 URI 表示(vscode-vfs://github/microsoft/vscode/package.json
)
检查您的扩展如何处理从 VS Code API 返回的 URI
- 切勿假定 URI Scheme 是
file
。URI.fsPath
只能在 URI Scheme 是file
时使用。 - 注意使用
fs
Node.js 模块进行文件系统操作的代码。如果可能,请使用vscode.workspace.fs
API,该 API 会委托给适当的文件系统提供程序。 - 检查依赖
fs
访问的第三方组件(例如,语言服务器或 Node.js 模块)。 - 如果您从命令运行可执行文件和任务,检查这些命令在虚拟工作区窗口中是否有意义,或者是否应该禁用它们。
声明您的扩展是否可以处理虚拟工作区
package.json
中 capabilities
下的 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."
}
}
}
描述显示在扩展视图中
然后,扩展应禁用在虚拟工作区中不受支持的功能,如下所述。
默认值
对于尚未填写 virtualWorkspaces
能力的所有扩展,"virtualWorkspaces": true
是默认值。
然而,在测试虚拟工作区时,我们列出了一份我们认为在虚拟工作区中应该禁用的扩展列表。该列表可以在 问题 #122836 中找到。这些扩展的默认值为 "virtualWorkspaces": false
。
当然,扩展作者更适合做出此决定。扩展的 package.json
中的 virtualWorkspaces
能力将覆盖我们的默认设置,我们最终将移除我们的列表。
在打开虚拟工作区时禁用功能
禁用命令和视图贡献点
命令、视图以及许多其他贡献点的可用性可以通过when 子句中的上下文键进行控制。
当所有工作区文件夹都位于虚拟文件系统上时,会设置 virtualWorkspace
上下文键。以下示例仅在非虚拟工作区中显示命令面板中的 npm.publish
命令
{
"menus": {
"commandPalette": [
{
"command": "npm.publish",
"when": "!virtualWorkspace"
}
]
}
}
resourceScheme
上下文键被设置为文件资源管理器中当前选定元素的 URI Scheme 或编辑器中打开的元素的 URI Scheme。
在以下示例中,只有当底层资源位于本地磁盘上时,npm.runSelectedScript
命令才会显示在编辑器上下文菜单中。
{
"menus": {
"editor/context": [
{
"command": "npm.runSelectedScript",
"when": "resourceFilename == 'package.json' && resourceScheme == file"
}
]
}
}
通过编程方式检测虚拟工作区
要检查当前工作区是否包含非 file
Scheme 且是虚拟的,您可以使用以下源代码
const isVirtualWorkspace =
workspace.workspaceFolders &&
workspace.workspaceFolders.every(f => f.uri.scheme !== 'file');
语言扩展和虚拟工作区
虚拟工作区对语言支持有什么期望?
期望所有扩展都能完全处理虚拟资源是不现实的。许多扩展使用需要同步文件访问和磁盘上文件的外部工具。因此,只提供有限的功能是可以接受的,例如下面列出的基本和单文件支持。
A. 基本语言支持
- TextMate 分词和着色
- 语言特定的编辑支持:括号对、注释、按 Enter 键规则、折叠标记
- 代码片段
B. 单文件语言支持
- 文档符号(大纲)、折叠、选择范围
- 文档高亮、语义高亮、文档颜色
- 补全、悬停提示、签名帮助、基于当前文件符号和静态语言库查找引用/声明
- 格式化、关联编辑
- 语法验证和同文件语义验证及代码操作
C. 跨文件、工作区感知语言支持
- 跨文件引用
- 工作区符号
- 验证工作区/项目中的所有文件
VS Code 内置的富语言扩展(TypeScript, JSON, CSS, HTML, Markdown)在处理虚拟资源时,其语言支持仅限于单文件。
禁用语言扩展
如果仅处理单个文件不是一个选项,语言扩展也可以决定在虚拟工作区中禁用该扩展。
如果您的扩展同时提供语法和需要禁用的富语言支持,那么语法也将被禁用。为了避免这种情况,您可以创建一个与富语言支持分开的基本语言扩展(语法、语言配置、代码片段),从而拥有两个扩展。
- 基本语言扩展设置为
"virtualWorkspaces": true
,并提供语言 ID、配置、语法和代码片段。 - 富语言扩展设置为
"virtualWorkspaces": false
并包含main
文件。它提供语言支持、命令,并对基本语言扩展有扩展依赖 (extensionDependencies
)。富语言扩展应该保留已有的扩展 ID,这样用户通过安装一个扩展就可以继续获得完整功能。
您可以在内置语言扩展中看到这种方法,例如 JSON,它由一个 JSON 扩展和一个 JSON 语言功能扩展组成。
这种分离也有助于在受限模式下运行的不受信任的工作区。富语言扩展通常需要信任,而基本语言功能可以在任何设置下运行。
语言选择器
注册语言功能提供程序(例如,补全、悬停提示、代码操作等)时,请确保指定提供程序支持的 Schemes
return vscode.languages.registerCompletionItemProvider(
{ language: 'typescript', scheme: 'file' },
{
provideCompletionItems(document, position, token) {
// ...
}
}
);
关于语言服务器协议 (LSP) 对访问虚拟资源的支持如何?
正在进行一项工作,将文件系统提供程序支持添加到 LSP。相关进展在语言服务器协议 问题 #1264 中跟踪。