现已发布！阅读 10 月份的新功能和修复。

支持远程开发和 GitHub Codespaces

Visual Studio Code 远程开发 允许您透明地与位于其他机器（无论是虚拟的还是物理的）上的源代码和运行时环境交互。 GitHub Codespaces 是一项服务，它扩展了这些功能，提供了托管在云中的环境，可以通过 VS Code 和基于浏览器的编辑器访问。

为了确保性能，远程开发和 GitHub Codespaces 都透明地在远程运行某些 VS Code 扩展。但是，这可能会对扩展的工作方式产生微妙的影响。虽然许多扩展无需任何修改即可正常工作，但您可能需要进行更改才能使扩展在所有环境中正常工作，尽管这些更改通常很小。

本文总结了扩展作者需要了解的关于远程开发和 Codespaces 的信息，包括扩展的 架构、如何在远程工作区或 Codespaces 中 调试扩展，以及 如果扩展无法正常工作该怎么办 的建议。

架构和扩展类型

为了使用户尽可能透明地使用远程开发或 Codespaces，VS Code 区分了两种类型的扩展

  • UI 扩展：这些扩展为 VS Code 用户界面做出贡献，并且始终在用户的本地机器上运行。UI 扩展无法直接访问远程工作区中的文件，也无法运行该工作区或机器上安装的脚本/工具。UI 扩展的示例包括：主题、代码段、语言语法和键映射。

  • 工作区扩展：这些扩展在与工作区所在的机器相同的机器上运行。在本地工作区中，工作区扩展在本地机器上运行。在远程工作区中或使用 Codespaces 时，工作区扩展在远程机器/环境中运行。工作区扩展可以访问工作区中的文件，以提供丰富的多文件语言服务、调试器支持，或对工作区中的多个文件执行复杂操作（直接或通过调用脚本/工具）。虽然工作区扩展不侧重于修改 UI，但它们也可以贡献资源管理器、视图和其他 UI 元素。

当用户安装扩展时，VS Code 会根据其类型自动将其安装到正确的位置。如果扩展可以作为两种类型之一运行，VS Code 将尝试为当前情况选择最佳类型；UI 扩展将在 VS Code 的 本地扩展主机 中运行，而工作区扩展将在一个 远程扩展主机 中运行，该主机位于一个小型 VS Code 服务器 中（如果远程工作区中存在），否则将在 VS Code 的本地扩展主机中运行（如果本地存在）。为了确保最新的 VS Code 客户端功能可用，服务器需要与 VS Code 客户端版本完全匹配。因此，当您在容器中、远程 SSH 主机上、使用 Codespaces 或在 Windows Subsystem for Linux (WSL) 中打开文件夹时，远程开发或 GitHub Codespaces 扩展会自动安装（或更新）服务器。（VS Code 还自动管理服务器的启动和停止，因此用户不会察觉其存在。）

Architecture diagram

VS Code API 旨在从 UI 或工作区扩展调用时，自动在正确的机器（本地或远程）上运行。但是，如果扩展使用 VS Code 未提供的 API（例如使用 Node API 或运行 shell 脚本），它可能在远程运行时无法正常工作。建议您测试扩展的所有功能是否在本地和远程工作区中都能正常工作。

调试扩展

虽然您 可以在远程环境中安装扩展的开发版本 进行测试，但如果您遇到问题，您可能需要直接在远程环境中调试扩展。在本节中，我们将介绍如何在 GitHub Codespaces、本地容器、SSH 主机 或 WSL 中编辑、启动和调试扩展。

通常，测试的最佳起点是使用限制端口访问的远程环境（例如 Codespaces、容器或带有限制性防火墙的远程 SSH 主机），因为在这些环境中工作的扩展往往在 WSL 等限制性较小的环境中也能工作。

使用 GitHub Codespaces 调试

在 GitHub Codespaces 预览版中调试扩展可能是一个很好的起点，因为您可以使用 VS Code 和 Codespaces 基于浏览器的编辑器进行测试和故障排除。如果您愿意，也可以使用 自定义开发容器。

请按照以下步骤操作

  1. 导航到 GitHub 上包含您扩展的存储库，并 在 Codespace 中打开它，以便在基于浏览器的编辑器中使用它。如果您愿意，也可以 在 VS Code 中打开 Codespace。

  2. 虽然 GitHub Codespaces 的默认映像应该具有大多数扩展所需的所有必要先决条件，但您可以在新的 VS Code 终端窗口中安装任何其他必需的依赖项（例如，使用 yarn install 或 sudo apt-get）（⌃⇧` (Windows, Linux Ctrl+Shift+`)）。

  3. 最后，按 F5 或使用 运行和调试 视图在 Codespace 中启动扩展。

    注意：您将无法在出现的窗口中打开扩展源代码文件夹，但您可以在 Codespace 中打开子文件夹或其他位置。

出现的扩展开发主机窗口将包含在 Codespace 中运行的扩展，调试器附加到它。

在自定义开发容器中调试

请按照以下步骤操作

  1. 要在本地使用开发容器，请 安装和配置 Dev Containers 扩展，并使用 文件 > 打开... / 打开文件夹... 在 VS Code 中本地打开您的源代码。要改为使用 Codespaces，请导航到 GitHub 上包含您扩展的存储库，并 在 Codespace 中打开它，以便在基于浏览器的编辑器中使用它。如果您愿意，也可以 在 VS Code 中打开 Codespace。

  2. 从命令面板中选择 Dev Containers: 添加开发容器配置文件... 或 Codespaces: 添加开发容器配置文件... (F1)，并选择 Node.js & TypeScript（如果您没有使用 TypeScript，则选择 Node.js），以添加必要的容器配置文件。

  3. 可选：在该命令运行后，您可以修改 .devcontainer 文件夹的内容，以包含其他构建或运行时要求。有关详细信息，请参阅深入的 创建开发容器 文档。

  4. 运行 Dev Containers: 在容器中重新打开 或 Codespaces: 添加开发容器配置文件...，片刻后，VS Code 将设置容器并连接。现在，您就可以在容器内部开发源代码，就像在本地情况下一样。

  5. 在新的 VS Code 终端窗口中运行 yarn install 或 npm install (⌃⇧` (Windows, Linux Ctrl+Shift+`))，以确保安装了 Linux 版本的 Node.js 本地依赖项。您也可以安装其他操作系统或运行时依赖项，但您可能希望将它们也添加到 .devcontainer/Dockerfile 中，以便在重新构建容器时可用。

  6. 最后，按 F5 或使用 运行和调试 视图在同一容器中启动扩展并附加调试器。

    注意： 您将无法在出现的窗口中打开扩展源代码文件夹，但可以在容器中的子文件夹或其他位置打开它。

出现的扩展开发主机窗口将包含您在步骤 2 中定义的容器中运行的扩展，并附加了调试器。

使用 SSH 调试

按照以下步骤操作

  1. 在 安装和配置远程 - SSH 扩展 后，从 VS Code 命令面板 (F1) 中选择远程 - SSH：连接到主机... 连接到主机。

  2. 连接后，可以使用文件 > 打开... / 打开文件夹... 选择包含您的扩展源代码的远程文件夹，或从命令面板 (F1) 中选择Git：克隆 将其克隆并在远程主机上打开它。

  3. 在新的 VS Code 终端窗口 (⌃⇧` (Windows、Linux Ctrl+Shift+`)) 中安装任何可能缺少的必需依赖项（例如，使用 yarn install 或 apt-get）。

  4. 最后，按 F5 或使用运行和调试视图在远程主机内部启动扩展并附加调试器。

    注意： 您将无法在出现的窗口中打开扩展源代码文件夹，但可以在 SSH 主机上的子文件夹或其他位置打开它。

出现的扩展开发主机窗口将包含在 SSH 主机上运行的扩展，并附加了调试器。

使用 WSL 调试

请按照以下步骤操作

  1. 在 安装和配置 WSL 扩展 后，从 VS Code 命令面板 (F1) 中选择WSL：新窗口。

  2. 在出现的窗口中，可以使用文件 > 打开... / 打开文件夹... 选择包含您的扩展源代码的远程文件夹，或从命令面板 (F1) 中选择Git：克隆 将其克隆并在 WSL 中打开它。

    提示： 您可以选择 /mnt/c 文件夹以访问 Windows 侧上的任何克隆源代码。

  3. 在新的 VS Code 终端窗口 (⌃⇧` (Windows、Linux Ctrl+Shift+`)) 中安装任何可能缺少的必需依赖项（例如，使用 apt-get）。您至少需要运行 yarn install 或 npm install 以确保本机 Node.js 依赖项的 Linux 版本可用。

  4. 最后，按 F5 或使用运行和调试视图启动扩展并附加调试器，就像您在本地执行一样。

    注意： 您将无法在出现的窗口中打开扩展源代码文件夹，但可以在 WSL 中的子文件夹或其他位置打开它。

出现的扩展开发主机窗口将包含在 WSL 中运行的扩展，并附加了调试器。

安装扩展的开发版本

无论何时 VS Code 在 SSH 主机、容器或 WSL 内部自动安装扩展，还是通过 GitHub Codespaces 自动安装扩展，都会使用 Marketplace 版本（而不是您本地机器上已安装的版本）。

虽然这在大多数情况下是合理的，但您可能希望在没有设置调试环境的情况下，使用（或共享）未发布的扩展版本进行测试。要安装未发布的扩展版本，您可以将扩展打包为 VSIX，并将其手动安装到已连接到运行中的远程环境的 VS Code 窗口中。

请按照以下步骤操作

  1. 如果这是一个已发布的扩展，您可能希望将 "extensions.autoUpdate": false 添加到 settings.json 中，以防止其自动更新到最新的 Marketplace 版本。
  2. 接下来，使用 vsce package 将扩展打包为 VSIX。
  3. 连接到 codespace、Dev Containers、SSH 主机 或 WSL 环境。
  4. 使用扩展视图更多操作 (...) 菜单中提供的从 VSIX 安装... 命令，在该特定窗口（而不是本地窗口）中安装扩展。
  5. 出现提示时重新加载。

提示： 安装完成后，您可以使用开发人员：显示运行中的扩展 命令查看 VS Code 是否在本地或远程运行扩展。

使用远程扩展处理依赖项

扩展可以依赖于其他扩展以获取 API。例如

  • 扩展可以从其 activate 函数导出 API。
  • 此 API 将对在同一扩展主机上运行的所有扩展可用。
  • 消费者扩展在其 package.json 中声明它们依赖于提供者扩展，使用 extensionDependencies 属性。

当所有扩展都在本地运行并共享相同的扩展主机时，扩展依赖项运行良好。

在处理远程场景时，远程运行的扩展可能依赖于本地运行的扩展。例如，本地扩展公开了对远程扩展运行至关重要的命令。在这种情况下，我们建议远程扩展将本地扩展声明为 extensionDependency，但问题是扩展在两个不同的扩展主机上运行，这意味着提供者的 API 对消费者不可用。因此，提供者扩展需要完全放弃通过使用其扩展的 package.json 中的 "api": "none" 来导出任何 API 的能力。扩展仍然可以使用 VS Code 命令进行通信（它们是异步的）。

这似乎对提供者扩展来说是一个不必要的严格约束，但使用 "api": "none" 的扩展只放弃了从其 activate 方法返回 API 的能力。在其他扩展主机上执行的消费者扩展仍然可以依赖它们，并且将被激活。

常见问题

VS Code 的 API 旨在自动在正确的位置运行，无论您的扩展恰好在哪里。考虑到这一点，有一些 API 可以帮助您避免意外行为。

不正确的执行位置

如果您的扩展没有按预期工作，它可能在错误的位置运行。最常见的是，这表现为扩展在您期望它只在本地运行时远程运行。您可以从命令面板 (F1) 中使用开发人员：显示运行中的扩展 命令查看扩展在哪里运行。

如果开发人员：显示运行中的扩展 命令显示 UI 扩展被错误地视为工作区扩展或反之亦然，请尝试在您的扩展的 package.json 中设置 extensionKind 属性，如 扩展种类部分 所述。

您可以使用 remote.extensionKind 设置 快速测试更改扩展种类的效果。此设置是扩展 ID 到扩展种类的映射。例如，如果您想强制 Azure 数据库 扩展成为 UI 扩展（而不是其工作区默认值），以及 远程 - SSH：编辑配置文件 扩展成为工作区扩展（而不是其 UI 默认值），您将设置

{
  "remote.extensionKind": {
    "ms-azuretools.vscode-cosmosdb": ["ui"],
    "ms-vscode-remote.remote-ssh-edit": ["workspace"]
  }
}

使用 remote.extensionKind 允许您快速测试已发布的扩展版本，而无需修改其 package.json 并重新构建它们。

持久化扩展数据或状态

在某些情况下，您的扩展可能需要持久化不属于 settings.json 或单独的工作区配置文件（例如 .eslintrc）中的状态信息。为了解决这个问题，VS Code 在激活期间传递给您扩展的 vscode.ExtensionContext 对象上提供了一组有用的存储属性。如果您的扩展已经利用了这些属性，它应该继续工作，无论它在哪里运行。

但是，如果您的扩展依赖于当前的 VS Code 路径约定（例如 ~/.vscode）或某些 OS 文件夹（例如 Linux 上的 ~/.config/Code）的存在来持久化数据，您可能会遇到问题。幸运的是，更新您的扩展并避免这些挑战应该很简单。

如果您正在持久化简单的键值对，可以使用 vscode.ExtensionContext.workspaceState 或 vscode.ExtensionContext.globalState 分别存储特定于工作区或全局的状态信息。如果您的数据比键值对更复杂，globalStorageUri 和 storageUri 属性提供了“安全”的 URI，您可以使用它们在文件中读取/写入全局特定于工作区的信息。

要使用 API

import * as vscode from 'vscode';

export function activate(context: vscode.ExtensionContext) {
    context.subscriptions.push(
        vscode.commands.registerCommand('myAmazingExtension.persistWorkspaceData', async () => {
            if (!context.storageUri) {
                return;
            }

            // Create the extension's workspace storage folder if it doesn't already exist
            try {
                // When folder doesn't exist, and error gets thrown
                await vscode.workspace.fs.stat(context.storageUri);
            } catch {
                // Create the extension's workspace storage folder
                await vscode.workspace.fs.createDirectory(context.storageUri)
            }

            const workspaceData = vscode.Uri.joinPath(context.storageUri, 'workspace-data.json');
            const writeData = new TextEncoder().encode(JSON.stringify({ now: Date.now() }));
            vscode.workspace.fs.writeFile(workspaceData, writeData);
        }
    ));

    context.subscriptions.push(
        vscode.commands.registerCommand('myAmazingExtension.persistGlobalData', async () => {

        if (!context.globalStorageUri) {
            return;
        }

        // Create the extension's global (cross-workspace) folder if it doesn't already exist
        try {
            // When folder doesn't exist, and error gets thrown
            await vscode.workspace.fs.stat(context.globalStorageUri);
        } catch {
            await vscode.workspace.fs.createDirectory(context.globalStorageUri)
        }

        const workspaceData = vscode.Uri.joinPath(context.globalStorageUri, 'global-data.json');
        const writeData = new TextEncoder().encode(JSON.stringify({ now: Date.now() }));
        vscode.workspace.fs.writeFile(workspaceData, writeData);
    ));
}

在机器之间同步用户全局状态

如果您的扩展需要在不同的机器上保留一些用户状态，则使用 vscode.ExtensionContext.globalState.setKeysForSync 将状态提供给 设置同步。这有助于防止在多台机器上向用户显示相同的欢迎或更新页面。

在 扩展功能 主题中有一个使用 setKeysforSync 的示例。

持久化秘密

如果您的扩展需要持久化密码或其他秘密，您可能希望使用 Visual Studio Code 的 SecretStorage API，它提供了一种通过加密安全地将文本存储在文件系统上的方法。例如，在桌面端，我们使用 Electron 的 safeStorage API 在将秘密存储到文件系统之前对其进行加密。该 API 始终将秘密存储在客户端，但无论您的扩展在哪里运行，您都可以使用此 API 并检索相同的秘密值。

注意：此 API 是保存密码和密钥的推荐方法。您 **不应** 使用 `vscode.ExtensionContext.workspaceState` 或 `vscode.ExtensionContext.globalState` 来存储您的密钥，因为这些 API 会以明文形式存储数据。

以下是一个示例

import * as vscode from 'vscode';

export function activate(context: vscode.ExtensionContext) {
  // ...
  const myApiKey = context.secrets.get('apiKey');
  // ...
  context.secrets.delete('apiKey');
  // ...
  context.secrets.store('apiKey', myApiKey);
}

使用剪贴板

从历史上看，扩展作者使用过 `clipboardy` 等 Node.js 模块与剪贴板交互。不幸的是，如果您在工作区扩展中使用这些模块，它们将使用远程剪贴板而不是用户的本地剪贴板。VS Code 剪贴板 API 解决了这个问题。它始终在本地运行，无论调用它的扩展类型如何。

要在扩展中使用 VS Code 剪贴板 API

import * as vscode from 'vscode';

export function activate(context: vscode.ExtensionContext) {
  context.subscriptions.push(
    vscode.commands.registerCommand('myAmazingExtension.clipboardIt', async () => {
      // Read from clipboard
      const text = await vscode.env.clipboard.readText();

      // Write to clipboard
      await vscode.env.clipboard.writeText(
        `It looks like you're copying "${text}". Would you like help?`
      );
    })
  );
}

在本地浏览器或应用程序中打开内容

生成进程或使用类似 `opn` 的模块来启动浏览器或其他应用程序以处理特定 URI 对本地场景很有用，但工作区扩展在远程运行，这会导致应用程序在错误的一侧启动。VS Code 远程开发 **部分** 模拟了 `opn` 节点模块，以允许现有扩展正常运行。您可以使用 URI 调用该模块，VS Code 将使 URI 的默认应用程序出现在客户端。但是，这不是一个完整的实现，因为不支持选项，也不会返回 `child_process` 对象。

我们建议扩展不要依赖于第三方节点模块，而是利用 `vscode.env.openExternal` 方法在您的本地操作系统上为给定的 URI 启动默认注册的应用程序。更重要的是，`vscode.env.openExternal` **会自动执行 localhost 端口转发！** 您可以使用它指向远程机器或 codespace 上的本地 Web 服务器，并提供内容，即使该端口在外部被阻止也是如此。

注意：目前，Codespaces 基于浏览器的编辑器中的转发机制仅支持 **http 和 https 请求**。但是，当您从 VS Code 连接到 codespace 时，您可以与任何 TCP 连接进行交互。

要使用 `vscode.env.openExternal` API

import * as vscode from 'vscode';

export async function activate(context: vscode.ExtensionContext) {
  context.subscriptions.push(
    vscode.commands.registerCommand('myAmazingExtension.openExternal', () => {
      // Example 1 - Open the VS Code homepage in the default browser.
      vscode.env.openExternal(vscode.Uri.parse('https://vscode.js.cn'));

      // Example 2 - Open an auto-forwarded localhost HTTP server.
      vscode.env.openExternal(vscode.Uri.parse('https://127.0.0.1:3000'));

      // Example 3 - Open the default email application.
      vscode.env.openExternal(vscode.Uri.parse('mailto:<fill in your email here>'));
    })
  );
}

转发 localhost

虽然 `vscode.env.openExternal` 中的 localhost 转发机制很有用，但您可能还会遇到需要转发内容而不实际启动新浏览器窗口或应用程序的情况。这就是 `vscode.env.asExternalUri` API 派上用场的地方。

注意：目前，Codespaces 基于浏览器的编辑器中的转发机制仅支持 **http 和 https 请求**。但是，当您从 VS Code 连接到 codespace 时，您可以与任何 TCP 连接进行交互。

要使用 `vscode.env.asExternalUri` API

import * as vscode from 'vscode';
import { getExpressServerPort } from './server';

export async function activate(context: vscode.ExtensionContext) {

    const dynamicServerPort = await getWebServerPort();

    context.subscriptions.push(vscode.commands.registerCommand('myAmazingExtension.forwardLocalhost', async () =>

        // Make the port available locally and get the full URI
        const fullUri = await vscode.env.asExternalUri(
            vscode.Uri.parse(`https://127.0.0.1:${dynamicServerPort}`));

        // ... do something with the fullUri ...

    }));
}

需要注意的是，API 返回的 URI **可能根本不引用 localhost**，因此您应该完整地使用它。这对 Codespaces 基于浏览器的编辑器尤其重要，在该编辑器中无法使用 localhost。

回调和 URI 处理程序

vscode.window.registerUriHandler API 允许您的扩展注册一个自定义 URI，如果在浏览器中打开该 URI，将在您的扩展中触发一个回调函数。注册 URI 处理程序的一个常见用例是在使用 OAuth 2.0 身份验证提供程序（例如，Azure AD）实现服务登录时。但是，它可以用于任何您希望外部应用程序或浏览器将信息发送到您的扩展的场景。

VS Code 中的远程开发和 Codespaces 扩展将透明地处理将 URI 传递到您的扩展，无论它实际运行在哪里（本地或远程）。但是，`vscode://` URI 无法与 Codespaces 基于浏览器的编辑器配合使用，因为在类似浏览器中打开这些 URI 会尝试将它们传递到本地 VS Code 客户端而不是基于浏览器的编辑器。幸运的是，可以使用 `vscode.env.asExternalUri` API 轻松解决此问题。

让我们结合使用 `vscode.window.registerUriHandler` 和 `vscode.env.asExternalUri` 来连接一个 OAuth 身份验证回调示例

import * as vscode from 'vscode';

// This is ${publisher}.${name} from package.json
const extensionId = 'my.amazing-extension';

export async function activate(context: vscode.ExtensionContext) {
  // Register a URI handler for the authentication callback
  vscode.window.registerUriHandler({
    handleUri(uri: vscode.Uri): vscode.ProviderResult<void> {
      // Add your code for what to do when the authentication completes here.
      if (uri.path === '/auth-complete') {
        vscode.window.showInformationMessage('Sign in successful!');
      }
    }
  });

  // Register a sign in command
  context.subscriptions.push(
    vscode.commands.registerCommand(`${extensionId}.signin`, async () => {
      // Get an externally addressable callback URI for the handler that the authentication provider can use
      const callbackUri = await vscode.env.asExternalUri(
        vscode.Uri.parse(`${vscode.env.uriScheme}://${extensionId}/auth-complete`)
      );

      // Add your code to integrate with an authentication provider here - we'll fake it.
      vscode.env.clipboard.writeText(callbackUri.toString());
      await vscode.window.showInformationMessage(
        'Open the URI copied to the clipboard in a browser window to authorize.'
      );
    })
  );
}

在 VS Code 中运行此示例时，它会连接一个 `vscode://` 或 `vscode-insiders://` URI，该 URI 可以用作身份验证提供程序的回调。在 Codespaces 基于浏览器的编辑器中运行时，它会连接一个 `https://*.github.dev` URI，无需任何代码更改或特殊条件。

虽然 OAuth 超出了本文档的范围，但请注意，如果将此示例改编为真实的身份验证提供程序，您可能需要在提供程序前面构建一个代理服务。这是因为并非所有提供程序都允许 `vscode://` 回调 URI，而其他提供程序不允许 HTTPS 上的回调使用通配符主机名。我们还建议尽可能使用 带有 PKCE 的 OAuth 2.0 授权代码流（例如，Azure AD 支持 PKCE）来提高回调的安全性。

远程运行或在 Codespaces 基于浏览器的编辑器中运行时的不同行为

在某些情况下，您的工作区扩展可能需要在远程运行时改变行为。在其他情况下，您可能希望在 Codespaces 基于浏览器的编辑器中运行时改变其行为。VS Code 提供三个 API 来检测这些情况：`vscode.env.uiKind`、`extension.extensionKind` 和 `vscode.env.remoteName`。

接下来，您可以按如下方式使用这三个 API

import * as vscode from 'vscode';

export async function activate(context: vscode.ExtensionContext) {
  // extensionKind returns ExtensionKind.UI when running locally, so use this to detect remote
  const extension = vscode.extensions.getExtension('your.extensionId');
  if (extension.extensionKind === vscode.ExtensionKind.Workspace) {
    vscode.window.showInformationMessage('I am running remotely!');
  }

  // Codespaces browser-based editor will return UIKind.Web for uiKind
  if (vscode.env.uiKind === vscode.UIKind.Web) {
    vscode.window.showInformationMessage('I am running in the Codespaces browser editor!');
  }

  // VS Code will return undefined for remoteName if working with a local workspace
  if (typeof vscode.env.remoteName === 'undefined') {
    vscode.window.showInformationMessage('Not currently connected to a remote workspace.');
  }
}

使用命令在扩展之间进行通信

一些扩展作为其激活的一部分返回 API，这些 API 旨在供其他扩展使用（通过 `vscode.extension.getExtension(extensionName).exports`）。如果所有涉及的扩展都在同一侧（全部是 UI 扩展或全部是工作区扩展），则这些将起作用，但在 UI 扩展和工作区扩展之间不起作用。

幸运的是，VS Code 会自动将任何执行的命令路由到正确的扩展，无论其位置如何。您可以自由调用任何命令（包括其他扩展提供的命令），无需担心任何影响。

如果您有一组需要相互交互的扩展，则使用私有命令公开功能可以帮助您避免意外影响。但是，您作为参数传入的任何对象都将在传输之前被“字符串化”（`JSON.stringify`），因此该对象不能具有循环引用，并且最终将在另一端成为“普通 JavaScript 对象”。

例如

import * as vscode from 'vscode';

export async function activate(context: vscode.ExtensionContext) {
  // Register the private echo command
  const echoCommand = vscode.commands.registerCommand(
    '_private.command.called.echo',
    (value: string) => {
      return value;
    }
  );
  context.subscriptions.push(echoCommand);
}

有关使用命令的详细信息，请参见 命令 API 指南。

使用 Webview API

与剪贴板 API 一样，Webview API 始终在用户的本地机器或浏览器中运行，即使从工作区扩展中使用也是如此。这意味着许多基于 webview 的扩展应该可以正常工作，即使在远程工作区或 Codespaces 中使用也是如此。但是，有一些注意事项需要您注意，以便您的 webview 扩展在远程运行时正常工作。

始终使用 asWebviewUri

您应该使用 `asWebviewUri` API 来管理扩展资源。使用此 API 而不是硬编码 `vscode-resource://` URI 是必要的，以确保 Codespaces 基于浏览器的编辑器能够与您的扩展配合使用。有关详细信息，请参见 Webview API 指南，但这里有一个简单的示例。

您可以在您的内容中按如下方式使用该 API

// Create the webview
const panel = vscode.window.createWebviewPanel(
  'catWebview',
  'Cat Webview',
  vscode.ViewColumn.One
);

// Get the content Uri
const catGifUri = panel.webview.asWebviewUri(
  vscode.Uri.joinPath(context.extensionUri, 'media', 'cat.gif')
);

// Reference it in your content
panel.webview.html = `<!DOCTYPE html>
<html>
<body>
    <img src="${catGifUri}" width="300" />
</body>
</html>`;

使用消息传递 API 来创建动态 webview 内容

VS Code webview 包含一个 消息传递 API，允许您动态更新 webview 内容，无需使用本地 Web 服务器。即使您的扩展正在运行一些您希望与其交互以更新 webview 内容的本地 Web 服务，您也可以从扩展本身进行操作，而不是直接从您的 HTML 内容进行操作。

对于远程开发和 GitHub Codespaces 来说，这是一个重要的模式，以确保您的 webview 代码在 VS Code 和 Codespaces 基于浏览器的编辑器中都能正常工作。

为什么使用消息传递而不是本地主机 Web 服务器？

另一种模式是在 `iframe` 中提供 Web 内容，或让 webview 内容直接与本地主机服务器交互。不幸的是，默认情况下，webview 内部的 `localhost` 将解析到开发人员的本地机器。这意味着对于远程运行的工作区扩展，它创建的 webview 将无法访问扩展生成的本地服务器。即使您使用机器的 IP，您连接到的端口通常也会在云 VM 或容器中默认被阻止。即使这在 VS Code 中有效，它在 Codespaces 基于浏览器的编辑器中将无效。

以下是在使用 Remote - SSH 扩展时出现的问题的说明，但这个问题在 Dev Containers 和 GitHub Codespaces 中也存在

Webview problem

如果可能，**您应该避免这样做**，因为它会使您的扩展变得很复杂。消息传递 API 可以实现相同类型的用户体验，而不会出现这些麻烦。扩展本身将在远程的 VS Code Server 中运行，因此它可以透明地与您的扩展启动的任何 Web 服务器进行交互，这是由于 webview 传递给它的任何消息导致的。

从 webview 中使用 localhost 的解决方法

如果您由于某种原因无法使用 消息传递 API，则有两种方法可以与 VS Code 中的远程开发和 GitHub Codespaces 扩展配合使用。

每个选项都允许 webview 内容通过 VS Code 用于与 VS Code Server 通信的相同通道进行路由。例如，如果我们更新上一节中关于 Remote - SSH 的说明，您将拥有以下内容

Webview Solution

选项 1 - 使用 asExternalUri

VS Code 1.40 引入了 `vscode.env.asExternalUri` API，以允许扩展以编程方式远程转发本地 `http` 和 `https` 请求。当您的扩展在 VS Code 中运行时，您可以使用相同的 API 将请求转发到 webview 中的 `localhost` Web 服务器。

使用该 API 获取 iframe 的完整 URI，并将其添加到您的 HTML。您还需要在 webview 中启用脚本，并将 CSP 添加到您的 HTML 内容中。

// Use asExternalUri to get the URI for the web server
const dynamicWebServerPort = await getWebServerPort();
const fullWebServerUri = await vscode.env.asExternalUri(
  vscode.Uri.parse(`https://127.0.0.1:${dynamicWebServerPort}`)
);

// Create the webview
const panel = vscode.window.createWebviewPanel(
  'asExternalUriWebview',
  'asExternalUri Example',
  vscode.ViewColumn.One,
  {
    enableScripts: true
  }
);

const cspSource = panel.webview.cspSource;
panel.webview.html = `<!DOCTYPE html>
        <head>
            <meta
                http-equiv="Content-Security-Policy"
                content="default-src 'none'; frame-src ${fullWebServerUri} ${cspSource} https:; img-src ${cspSource} https:; script-src ${cspSource}; style-src ${cspSource};"
            />
        </head>
        <body>
        <!-- All content from the web server must be in an iframe -->
        <iframe src="${fullWebServerUri}">
    </body>
    </html>`;

请注意，在上述示例中，iframe 中提供的任何 HTML 内容都需要使用相对路径，而不是硬编码 localhost。

选项 2 - 使用端口映射

如果您**不打算支持 Codespaces 浏览器编辑器**，可以使用 webview API 中提供的 portMapping 选项。（此方法也适用于来自 VS Code 客户端的 Codespaces，但不适用于浏览器）。

要使用端口映射，请在创建 webview 时传入一个 portMapping 对象

const LOCAL_STATIC_PORT = 3000;
const dynamicServerPort = await getWebServerPort();

// Create webview and pass portMapping in
const panel = vscode.window.createWebviewPanel(
  'remoteMappingExample',
  'Remote Mapping Example',
  vscode.ViewColumn.One,
  {
    portMapping: [
      // This maps localhost:3000 in the webview to the web server port on the remote host.
      { webviewPort: LOCAL_STATIC_PORT, extensionHostPort: dynamicServerPort }
    ]
  }
);

// Reference the port in any full URIs you reference in your HTML.
panel.webview.html = `<!DOCTYPE html>
    <body>
        <!-- This will resolve to the dynamic server port on the remote machine -->
        <img src="https://127.0.0.1:${LOCAL_STATIC_PORT}/canvas.png">
    </body>
    </html>`;

在此示例中，无论是在远程还是本地情况下，对 https://127.0.0.1:3000 的任何请求都将自动映射到 Express.js web 服务器运行的动态端口。

使用原生 Node.js 模块

与 VS Code 扩展捆绑在一起（或动态获取）的原生模块必须使用 Electron 的 electron-rebuild 重新编译。但是，VS Code Server 运行标准（非 Electron）版本的 Node.js，这会导致二进制文件在远程使用时失败。

要解决此问题

  1. 为 VS Code 附带的 Node.js 的“modules”版本包含（或动态获取）两套二进制文件（Electron 和标准 Node.js）。
  2. 检查 vscode.extensions.getExtension('your.extensionId').extensionKind === vscode.ExtensionKind.Workspace 以根据扩展程序是在远程还是本地运行来设置正确的二进制文件。
  3. 您可能还希望通过 遵循类似的逻辑 同时添加对非 x86_64 目标和 Alpine Linux 的支持。

您可以通过转到 **帮助 > 开发者工具** 并在控制台中键入 process.versions.modules 来找到 VS Code 使用的“modules”版本。但是，为了确保原生模块在不同的 Node.js 环境中无缝工作，您可能需要针对所有可能的 Node.js“modules”版本和平台（Electron Node.js、官方 Node.js Windows/Darwin/Linux、所有版本）编译原生模块。node-tree-sitter 模块是很好地做到这一点的模块示例。

支持非 x86_64 主机或 Alpine Linux 容器

如果您的扩展纯粹是用 JavaScript/TypeScript 编写的，您可能不需要做任何事情来添加对其他处理器架构或基于 musl 的 Alpine Linux 的支持。

但是，如果您的扩展在 Debian 9+、Ubuntu 16.04+ 或 RHEL/CentOS 7+ 远程 SSH 主机、容器或 WSL 上运行，但在受支持的非 x86_64 主机（例如 ARMv7l）或 Alpine Linux 容器上失败，则扩展程序可能包含特定于 x86_64 glibc 的原生代码或运行时，这些代码或运行时将在这些架构/操作系统上失败。

例如，您的扩展程序可能只包含 x86_64 编译版本的原生模块或运行时。对于 Alpine Linux，包含的原生代码或运行时可能无法工作，因为 Alpine Linux（musl）和其它发行版（glibc）中 libc 的实现方式存在 根本差异。

要解决此问题

  1. 如果您正在动态获取编译后的代码，您可以通过使用 process.arch 检测非 x86_64 目标并下载针对正确架构编译的版本来添加支持。如果您在扩展程序中包含了所有受支持架构的二进制文件，则可以使用此逻辑来使用正确的二进制文件。

  2. 对于 Alpine Linux，您可以使用 await fs.exists('/etc/alpine-release') 检测操作系统，然后再次下载或使用针对基于 musl 的操作系统的正确二进制文件。

  3. 如果您不想支持这些平台，可以使用相同的逻辑来提供一个好的错误消息。

重要的是要注意，一些第三方 npm 模块包含可能会导致此问题的原生代码。因此，在某些情况下，您可能需要与 npm 模块作者合作以添加额外的编译目标。

避免使用 Electron 模块

虽然依赖扩展 API 未公开的内置 Electron 或 VS Code 模块很方便，但重要的是要注意，VS Code Server 运行标准（非 Electron）版本的 Node.js。这些模块在远程运行时将丢失。有一些例外情况，其中有一些特定的代码来使其工作。

使用您的扩展 VSIX 中的 Node.js 基础模块或模块来避免这些问题。如果您绝对必须使用 Electron 模块，请确保在模块丢失时有备用方案。

以下示例将使用 Electron original-fs 节点模块（如果找到），如果没有则回退到 Node.js 基础 fs 模块。

function requireWithFallback(electronModule: string, nodeModule: string) {
  try {
    return require(electronModule);
  } catch (err) {}
  return require(nodeModule);
}

const fs = requireWithFallback('original-fs', 'fs');

尽可能避免这些情况。

已知问题

有一些扩展问题可以通过为工作区扩展添加一些额外的功能来解决。下表是正在考虑的一些已知问题列表

问题 描述
无法从工作区扩展访问已连接的设备 访问本地连接设备的扩展程序在远程运行时将无法连接到它们。克服此问题的一种方法是创建一个伴侣 UI 扩展程序，其作用是访问已连接的设备并提供远程扩展程序也可以调用的命令。
另一种方法是反向隧道，该方法正在 VS Code 存储库问题 中跟踪。

问题和反馈

10/29/2024