虛擬工作區

Name: Visual Studio Code
Author: Microsoft

像 GitHub Repositories 這樣的擴充套件透過檔案系統提供程式在一個或多個資料夾上開啟 VS Code。當擴充套件實現檔案系統提供程式時，工作區資源可能不在本地磁碟上，而是虛擬的，位於伺服器或雲上，編輯操作也在此處進行。

這種配置稱為 虛擬工作區。當虛擬工作區在 VS Code 視窗中開啟時，將在左下角的遠端指示器中顯示一個標籤，這與其他遠端開發視窗類似。

Remote indicator

並非所有擴充套件都能處理虛擬資源，並且可能需要本地磁碟上的資源。一些擴充套件使用依賴於磁碟訪問的工具，需要同步檔案訪問，或者缺乏必要的檔案系統抽象。在這些情況下，當處於虛擬工作區時，VS Code 會向用戶指示他們正在以受限模式執行，並且某些擴充套件已被停用或功能受限。

總的來說，使用者希望儘可能多的擴充套件能在虛擬工作區中工作，並在瀏覽和編輯遠端資源時獲得良好的使用者體驗。本指南展示了擴充套件如何針對虛擬工作區進行測試，描述了允許它們在虛擬工作區中工作的修改，並介紹了 virtualWorkspaces 功能屬性。

修改擴充套件以支援虛擬工作區也是在 VS Code for the Web 中良好工作的關鍵一步。VS Code for the Web 完全在瀏覽器中執行，由於瀏覽器沙箱的限制，工作區是虛擬的。有關更多詳細資訊，請參閱 Web 擴充套件指南。

我的擴充套件受到影響嗎？

當擴充套件不包含可執行程式碼，而僅是宣告性的（如主題、鍵繫結、片段或語法擴充套件）時，它可以在虛擬工作區中執行，無需修改。

包含程式碼的擴充套件，即定義了 main 入口點的擴充套件，需要進行檢查，並可能需要修改。

針對虛擬工作區執行你的擴充套件

安裝 GitHub Repositories 擴充套件，並透過命令面板執行 Open GitHub Repository... 命令。該命令會顯示一個 Quick Pick 下拉選單，你可以貼上任何 GitHub URL，或選擇搜尋特定儲存庫或拉取請求。

這將開啟一個 VS Code 視窗，用於虛擬工作區，其中所有資源都是虛擬的。

審查擴充套件程式碼是否已準備好處理虛擬資源

VS Code API 對虛擬檔案系統的支援已經存在相當長一段時間了。你可以檢視檔案系統提供程式 API。

為新的 URI 方案（例如 vscode-vfs）註冊一個檔案系統提供程式，並且該檔案系統上的資源將由使用該方案的 URI 表示（vscode-vfs://github/microsoft/vscode/package.json）。

檢查你的擴充套件如何處理從 VS Code API 返回的 URI

永遠不要假設 URI 方案是 file。只有當 URI 方案是 file 時，才能使用 URI.fsPath。
留意對 fs Node.js 模組的檔案系統操作的使用。如果可能，請使用 vscode.workspace.fs 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."
    }
  }
}

描述顯示在擴充套件檢視中

Extensions view

擴充套件應停用在虛擬工作區中不支援的功能，如下所述。

預設值

對於尚未填寫 virtualWorkspaces 功能的所有擴充套件，"virtualWorkspaces": true 是預設值。

然而，在測試虛擬工作區時，我們發現了一些我們認為在虛擬工作區中應該停用的擴充套件列表。該列表可以在 issue #122836 中找到。這些擴充套件的預設設定為 "virtualWorkspaces": false。

當然，擴充套件作者在做出此決定時處於更有利的地位。擴充套件 package.json 中的 virtualWorkspaces 功能將覆蓋我們的預設設定，並且我們將最終淘汰我們的列表。

在開啟虛擬工作區時停用功能

停用命令和檢視貢獻

命令和檢視以及許多其他貢獻的可用性可以透過 when clauses 中的上下文鍵進行控制。

當所有工作區資料夾都位於虛擬檔案系統上時，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 新增檔案系統提供程式支援。在語言伺服器協議 issue #1264 中進行跟蹤。

12/10/2025