企业官网建设流程全解析

• 文档
• 教程

本文围绕 VS Code 官方博客发布的 Remote Repositories 扩展展开，介绍如何在不执行git clone的情况下，直接从 VS Code 打开、浏览、搜索、编辑并提交 GitHub 远程仓库。读完本文，你将掌握远程仓库的打开流程、虚拟工作区下的功能边界、与 GitHub Pull Requests 扩展的协同用法，以及作为扩展作者如何通过FileSystemProvider与virtualWorkspaces能力声明让自己的扩展在虚拟工作区中正常工作。

说明：自本篇博客发布以来，Remote Repositories 扩展已更名为GitHub Repositories（扩展 ID：github.remotehub）。当前仓库中关于该扩展的最新资料见 GitHub 工作流文档，本文在介绍原博客内容的同时，也会结合该文档补充最新能力。

更快、更安全地打开源代码仓库

VS Code 从诞生之初就内置了对 Git 的集成支持，并通过扩展支持了大量其他源代码管理（SCM）提供方，开发者可以直接在 VS Code 中克隆并处理仓库。但开发者日常工作的很大一部分其实是阅读别人的代码：审查 Pull Request、浏览开源仓库、尝试新技术或新项目、检查上游依赖以排查应用问题等。这些场景的第一步通常都是：先在本机克隆仓库，再用编辑器打开代码。

然而，本地克隆存在几个痛点：

• 耗时：克隆整个仓库需要花费时间，尤其对于大型仓库。
• 易过期：如果忘记git pull，你审查的可能是过时版本。
• 安全风险：克隆并执行你不熟悉的代码，存在安全隐患。

由 GitHub 发布的 Remote Repositories（现名 GitHub Repositories）扩展，让“在 VS Code 中打开源代码仓库”这一体验变得即时且安全。借助它，你可以直接在 VS Code 内快速浏览、搜索、编辑并提交到任意远程 GitHub 仓库（原计划还支持 Azure Repos），全程无需克隆。

你可以同时处理任意多个仓库，而不必在本机保存任何源代码——省时间、省磁盘空间，并让你可以始终留在 VS Code 中完成所有源代码控制任务。

在 VS Code 中打开第一个远程仓库

安装扩展并打开仓库

首先安装 Remote Repositories（GitHub Repositories）扩展。安装完成后，点击 VS Code 左下角的远程指示器（remote indicator），即可获得Open Remote Repository命令的即时访问入口（该指示器同时会聚合你已安装的其他远程开发扩展的命令）：

如果你此前没有在 VS Code 中登录过 GitHub，系统会提示你完成 GitHub 账号认证。登录后，搜索一个仓库或 PR，选中它即可开始使用。

最新版本的扩展在 GitHub 工作流文档中是这样描述的：安装扩展后，可通过命令面板（kb(workbench.action.showCommands)）中的GitHub Repositories: Open Repository...命令，或点击状态栏左下角的远程指示器来打开仓库。运行该命令后，你可以选择：

• 打开一个 GitHub 仓库；
• 打开一个 GitHub Pull Request；
• 重新打开一个之前连接过的仓库。

你可以直接输入仓库 URL，也可以在文本框中搜索 GitHub 上的仓库。选中仓库或 PR 后，VS Code 会重新加载窗口，并在资源管理器中显示仓库内容——你可以像在本地克隆中一样打开文件（带语法高亮和括号匹配）、编辑并提交更改。

选择仓库后，VS Code 重新加载，仓库内容就像被本地克隆一样加载出来。你可以在不离开 VS Code 的情况下探索并贡献代码：使用熟悉的 VS Code 界面和 Explorer、搜索、时间线视图、快速打开，以及源代码控制等功能，感觉就像在操作本地代码。

理解虚拟工作区与功能限制

此时你连接到的是一种虚拟工作区（virtual workspace），远程指示器会显示 “GitHub”。将鼠标悬停在远程指示器上，VS Code 会提示你在虚拟工作区中部分功能不可用：

虚拟工作区是一种特殊环境，某些功能（如部分扩展）会被禁用或仅提供有限功能。点击悬停提示中的Some features链接，可以查看哪些扩展被禁用、哪些扩展功能受限（悬停到具体扩展上可以看到受限说明）：

如果你想在虚拟工作区中手动启用某个扩展，可以在用户settings.json中使用extensions.supportVirtualWorkspaces设置：

"extensions.supportVirtualWorkspaces": { "<extensionID>": true }

需要牢记的是：如果扩展的实现依赖本地文件系统访问，那么即使强制启用，它在虚拟工作区中也可能无法按预期工作。

打开仓库之后可以做什么

简化的 Git 工作流，始终保持项目最新

Remote Repositories 帮助你每次都停留在仓库的最新版本，无需复杂 Git 命令：

• 每次打开都是最新版：打开任何新仓库时，你拿到的一定是 GitHub 上的最新内容，不必像本地仓库那样手动git pull刷新。这一点在 GitHub 工作流文档中也有明确说明。
• 自动提示待拉取提交数：每当 Remote Repositories 检测到 GitHub 上有新变更时，状态栏会显示需要拉取的提交数量：

• Explorer 中高亮修改文件：修改过的文件会在资源管理器中获得高亮标记：

• 提交即同步：当你提交更改后，变更会自动出现在 GitHub 上——无需手动git push，也无需发布新创建的分支。这与在 GitHub 网页界面上操作的效果类似。

另外，GitHub Repositories 扩展还支持查看甚至提交 LFS 跟踪的文件，而无需在本机安装 Git LFS（大文件存储）：把需要 LFS 跟踪的文件类型写入.gitattributes文件，即可通过源代码控制视图直接将更改提交到 GitHub。

创建或检出 Pull Request

Remote Repositories 与GitHub Pull Requests and Issues扩展配合良好，后者允许你在 VS Code 中直接审查和管理 GitHub 上的 Pull Request 与 Issue。两个扩展并行使用，即可快速检出 PR、处理 Issue，全程无需在本地克隆代码、也无需离开 VS Code。

你可以修改代码、基于修改创建新分支和 Pull Request，然后检出该 PR——全部只需几次点击。更多详情可参考仓库中的 GitHub 工作流文档，其中包含创建 PR（GitHub Pull Requests: Create Pull Request命令或 Pull Requests 视图）、Review Mode 下的审查流程，以及githubPullRequests.queries查询自定义等细节。

此外，在最新版本的 GitHub Repositories 扩展中，你还可以直接从源代码控制视图创建 Pull Request：系统会提示你填写标题并新建分支。创建完成后，再用 GitHub Pull Requests and Issues 扩展进行审查、编辑和合并。

将更改隔离到不同分支

在典型环境中，切换分支时常需要决定哪些更改要 stash、哪些要提交，比较麻烦。Remote Repositories 让你可以轻松地同时在多个分支上工作：

• 当你在一个分支暂停工作、切换到新分支时，不会被询问是否 stash 更改——更改会自动保留在之前的分支上。
• 当你回到之前的分支时，更改依然还在，你可以从离开的地方继续。
• 新创建的分支不会包含上一分支的任何更改。

具体操作：在状态栏选择当前分支（例如 “main”），打开分支列表：

选择+ Create New Branch...并输入分支名称：

随后确认切换到该新分支：

在最新版本中，这一体验进一步演进：选择状态栏的分支指示器即可切换分支，无需先 stash 未提交的更改——扩展会记住你的更改，并在你返回该分支时自动重新应用。

Remote Explorer 快速重开仓库

最新版本的 GitHub Repositories 扩展还在活动栏提供了Remote Explorer视图，用于快速重开远程仓库：该视图会展示你之前打开过的仓库和分支，方便你随时回到上一次的工作现场。

虚拟工作区中的已知限制

在 Remote Repositories 环境中工作时，存在以下明确限制：

• 调试、终端与任务暂不支持：终端在本机文件系统上打开，无法访问远程仓库的虚拟文件系统，因此依赖终端的调试、任务等功能无法工作。
• 语言智能受限：IntelliSense、Go to Definition等特性可能受影响，因为许多语言服务尚未理解虚拟化环境。
• 搜索的索引机制：GitHub 自身的搜索存在限制（例如不索引分支）。Remote Repositories 可以通过启用索引来规避：索引会从 GitHub 拉取一个浅克隆（shallow clone）并在本地执行全文搜索，比 GitHub 基于默认分支的模糊搜索功能更强大。你可以在搜索视图中启用该索引。
• 扩展限制：并非所有扩展都能在虚拟工作区中运行（依赖本地文件访问的扩展无法支持此环境），但支持面会随时间扩大。

正如发布说明 v1_56.md 中所述：该扩展最初以内置扩展Remote Repositories (RemoteHub)的形式在 Insiders 版预览，允许直接从 VS Code 内浏览、搜索、编辑并提交任意 GitHub 仓库，无需本地克隆。团队当时便表示“功能集将增长、限制将缩小”，并计划扩展支持的提供方（GitHub 是第一个，Azure Repos 紧随其后）。

升级到更强大的开发环境

使用 Remote Repositories 时，VS Code 运行在一个没有物理文件系统的环境中，并非所有功能都可用。这非常适合快速浏览仓库，但当你想进行更“进阶”的工作时——例如主动开发仓库、需要定期从远端拉取以跟踪变更——就需要升级环境。

点击左下角远程指示器，选择Continue Working on...：

随后会出现三个选项：

• Clone Repository Locally：将当前仓库克隆到本机。会弹出本地文件资源管理器，让你选择克隆位置。
• Clone Repository in Container Volume：使用 Dev Containers 扩展将仓库克隆到 Docker 容器卷 中（需要安装 Dev Containers 扩展和 Docker）。VS Code 会重新加载并通过 Dev Containers 连接，远程指示器将显示Dev Container: {镜像名}。
• Open in Codespaces：在 GitHub Codespaces 中继续工作。选择后会打开浏览器，跳转到该仓库的 Codespaces 列表。

在最新版本的 GitHub 工作流文档中，这一能力被称为Continue Working On，同样可通过命令面板或状态栏远程指示器触发，支持：创建 GitHub Codespace（需安装 GitHub Codespaces 扩展）、克隆到本地、或克隆到 Docker 容器（需安装 Docker 与 Microsoft 容器工具扩展）。

文档还提到一个细节：在浏览器版编辑器（VS Code for the Web）中使用Continue Working On时，选项为“在本地打开仓库”或“在 GitHub Codespaces 云托管环境中打开”。首次在存在未提交更改时使用该命令，你还可以选择通过Cloud Changes将待处理更改带到目标开发环境——这些更改存储在与设置同步相同的 VS Code 服务上，一旦应用到目标环境即被删除。若未自动应用，可通过Cloud Changes: Show Cloud Changes命令查看、管理或删除已存储的更改。

虚拟文件系统与虚拟工作区：底层原理

支撑上述远程体验的核心概念是虚拟文件系统（virtual file system）与虚拟工作区（virtual workspace）。作为最终用户，你只需知道要打开哪个仓库或 PR，VS Code 会自动接管虚拟文件系统并管理你的工作区；作为扩展开发者，则需要采用虚拟文件系统 API 来确保扩展行为符合预期。

虚拟文件系统如何工作

在传统 Git 工作流中，你执行git clone后，仓库副本被保存到本机文件系统。而在 Remote Repositories 中，代码并不存在于本地——它仍然只存在于 GitHub 上。你通过虚拟文件系统与代码交互：这是一种对“磁盘上物理文件”的抽象，可以从 GitHub 等代码托管方、云存储或数据库提供内容，并在 VS Code 中无缝呈现为文件。

当你在虚拟文件系统上打开工作区时，就称之为虚拟工作区。在虚拟工作区中，你依然可以使用 VS Code 功能，包括扩展。

仓库中的 虚拟工作区扩展作者指南 对此有更精确的定义：当扩展实现了文件系统提供方（file system provider）后，工作区资源可能并不位于本地磁盘，而是虚拟的——位于服务器或云端，编辑操作也在那里发生。当虚拟工作区在 VS Code 窗口中打开时，左下角远程指示器会显示相应标签，与远程开发窗口类似。

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

要让扩展行为正确，它必须支持虚拟文件系统：

• 纯声明式扩展：没有代码、只是颜色主题、键绑定、代码片段或语法（grammar）扩展，可以直接在虚拟工作区中运行，无需任何适配。
• 含代码的扩展：定义了main入口点、运行实际代码的扩展，需要检查并可能需要适配。

虚拟文件系统的 API 支持来自FileSystemProvider接口（参见仓库 vscode-api.template 中关于 FileSystemProvider 的定义）。文件系统提供方为一个新的 URI scheme 注册（例如vscode-vfs），该文件系统上的资源使用该 scheme 的 URI 表示，例如vscode-vfs://github/microsoft/vscode/package.json。

虚拟文档指南 指出，如果需要更多灵活性和能力，FileSystemProviderAPI 允许你实现一个完整文件系统——包含文件、文件夹、二进制数据、文件删除、创建等操作。与只读的TextDocumentContentProvider（通过vscode.workspace.registerTextDocumentContentProvider注册 scheme 并提供文本内容）相比，文件系统提供方是更完整、更强大的方案。

扩展的package.json中有capabilities属性，其中virtualWorkspaces子属性用于声明扩展是否支持虚拟工作区。根据 虚拟工作区指南，支持三种声明方式：

完全不支持（VS Code 不会在虚拟工作区中启用该扩展）：

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

完全或部分支持（声明true，若功能受限则附加说明）：

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

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

description会显示在扩展视图中。关于默认值：未填写virtualWorkspaces能力的扩展默认视为true，但 VS Code 维护了一个建议在虚拟工作区中禁用的扩展清单（见 issue #122836），这些扩展默认按"virtualWorkspaces": false处理；扩展作者在package.json中显式声明的能力将覆盖该默认清单。

在虚拟工作区中禁用不支持的扩展功能

扩展可以通过when 子句上下文键控制命令与视图的可用性（参见 when-clause-contexts 参考）：

• virtualWorkspace上下文键：当所有工作区文件夹都位于虚拟文件系统上时被置为真。例如，让npm.publish命令仅在非虚拟工作区中出现：

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

• resourceScheme上下文键：记录资源管理器中当前选中元素（或编辑器中打开元素）的 URI scheme。例如，仅在资源位于本地磁盘时显示npm.runSelectedScript命令：

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

程序化检测：要判断当前工作区是否为虚拟工作区，可使用如下代码：

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

指南还提醒扩展作者检查代码对 URI 的处理方式：永远不要假设 URI scheme 是file（URI.fsPath只能在 scheme 为file时使用）；留意对 Nodefs模块的用法，尽可能改用vscode.workspace.fsAPI（它会委派给对应的文件系统提供方）；检查依赖fs访问的第三方组件（如语言服务器或 node 模块）；并评估从命令中运行的可执行文件与任务在虚拟工作区窗口中是否仍有意义。

语言扩展在虚拟工作区中的支持级别

并非所有扩展都能在虚拟资源上完整工作，许多扩展依赖需要同步文件访问和磁盘文件的外部工具。因此只提供有限功能是合理的，支持级别分为三档：

• A. Basic（基础）语言支持：TextMate 分词与着色；语言专属编辑支持（括号配对、注释、回车规则、折叠标记）；代码片段。
• B. Single-file（单文件）语言支持：文档符号（大纲）、折叠、选区范围；文档高亮、语义高亮、文档颜色；基于当前文件与静态语言库的补全、悬停、签名帮助、查找引用/声明；格式化、链接编辑；语法校验与同文件语义校验及 Code Actions。
• C. Cross-file（跨文件、工作区级）语言支持：跨文件引用；工作区符号；对整个工作区/项目所有文件的校验。

VS Code 内置的丰富语言扩展（TypeScript、JSON、CSS、HTML、Markdown）在虚拟资源上工作时被限制为单文件语言支持。语言扩展若无法提供单文件支持，也可以选择在虚拟工作区中整体禁用自身；此时应把基础语言扩展（grammar、语言配置、片段）与富语言支持拆分为两个扩展，前者声明"virtualWorkspaces": true，后者声明false并通过extensionDependencies依赖前者。内置的 JSON 扩展（JSON 扩展 + JSON 语言功能扩展）即采用此拆分模式，这一做法也有助于配合受限模式下的 工作区信任。

对于 LSP（语言服务器协议）访问虚拟资源的问题，相关支持正在推进中，可关注语言服务器协议仓库中的相应 issue。

反馈与延伸阅读

Remote Repositories / GitHub Repositories 扩展持续演进。如果你希望进一步深入，可以继续阅读本仓库中的以下资料：

• GitHub 工作流文档：包含 GitHub Repositories 扩展的最新能力说明、PR 与 Issue 管理、githubPullRequests.queries与githubIssues系列设置。
• 虚拟工作区扩展作者指南：面向扩展作者的完整适配指南，含virtualWorkspaces能力声明、when 子句、程序化检测与语言支持分级。
• 虚拟文档指南：介绍TextDocumentContentProvider与FileSystemProvider两套虚拟内容 API。
• 远程开发概览：了解远程开发整体架构与各类远程窗口。
• VS Code for the Web：浏览器中运行的 VS Code，工作区天然是虚拟的。
• Web 扩展指南：面向 Web 场景的扩展适配指引。
• 发布说明 v1_56：Remote Repositories 最初作为 Insiders 内置扩展预览时的官方说明。

对于扩展作者来说，让扩展适配虚拟工作区不仅是服务 Remote Repositories 用户，也是让扩展在 VS Code for the Web 中良好工作的关键一步——Web 版由于浏览器沙箱限制，工作区同样是虚拟的。

Happy Coding!

• 文档
• 教程