支持远程开发和 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 或在适用于 Linux 的 Windows 子系统 (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 编辑器进行测试和故障排除。如果愿意，你也可以使用自定义开发容器。

请按照以下步骤操作

导航到 GitHub 上包含你的扩展的仓库，然后在 codespace 中打开它，以在基于浏览器的编辑器中进行操作。如果愿意，你也可以在 VS Code 中打开 codespace。
虽然 GitHub Codespaces 的默认镜像应包含大多数扩展所需的所有先决条件，但你可以在新的 VS Code 终端窗口（⌃⇧` (Windows, Linux Ctrl+Shift+`)）中安装任何其他必需的依赖项（例如，使用 yarn install 或 sudo apt-get）。
最后，按下 F5 或使用运行和调试视图在 codespace 中启动扩展。

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

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

在自定义开发容器中调试

请按照以下步骤操作

要在本地使用开发容器，安装并配置 Dev Containers 扩展，然后使用文件 > 打开... / 打开文件夹... 在 VS Code 中本地打开你的源代码。要改为使用 Codespaces，导航到 GitHub 上包含你的扩展的仓库，然后在 codespace 中打开它，以在基于浏览器的编辑器中进行操作。如果愿意，你也可以在 VS Code 中打开 codespace。
从命令面板（F1）中选择 Dev Containers: Add Dev Container Configuration Files... 或 Codespaces: Add Dev Container Configuration Files...，并选择 Node.js & TypeScript（如果你不使用 TypeScript 则选择 Node.js）以添加所需的容器配置文件。
可选：此命令运行后，你可以修改 .devcontainer 文件夹的内容以包含额外的构建或运行时要求。详情请参阅详细的创建开发容器文档。
运行 Dev Containers: Reopen in Container 或 Codespaces: Add Dev Container Configuration Files...，稍后，VS Code 将设置容器并连接。你现在可以从容器内部开发源代码，就像在本地开发一样。
在新的 VS Code 终端窗口（⌃⇧` (Windows, Linux Ctrl+Shift+`)）中运行 yarn install 或 npm install，以确保安装了 Linux 版本的 Node.js 原生依赖项。你还可以安装其他 OS 或运行时依赖项，但你可能希望将这些添加到 .devcontainer/Dockerfile 中，以便在重建容器时它们可用。
最后，按下 F5 或使用运行和调试视图在此同一容器中启动扩展并附加调试器。

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

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

使用 SSH 进行调试

按照以下步骤操作

在安装并配置 Remote - SSH 扩展后，从 VS Code 中的命令面板（F1）中选择 Remote-SSH: Connect to Host... 连接到主机。
连接后，使用文件 > 打开... / 打开文件夹... 选择包含你的扩展源代码的远程文件夹，或者从命令面板（F1）中选择 Git: Clone 将其克隆到远程主机并打开。
在新的 VS Code 终端窗口（⌃⇧` (Windows, Linux Ctrl+Shift+`)）中安装可能缺少的任何必需依赖项（例如，使用 yarn install 或 apt-get）。
最后，按下 F5 或使用运行和调试视图在远程主机上启动扩展并附加调试器。

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

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

使用 WSL 进行调试

请按照以下步骤操作

在安装并配置 WSL 扩展后，从 VS Code 中的命令面板（F1）中选择 WSL: New Window。
在出现的新窗口中，使用文件 > 打开... / 打开文件夹... 选择包含你的扩展源代码的远程文件夹，或者从命令面板（F1）中选择 Git: Clone 将其克隆到 WSL 并打开。

提示： 你可以选择 /mnt/c 文件夹访问你在 Windows 侧克隆的任何源代码。
在新的 VS Code 终端窗口（⌃⇧` (Windows, Linux Ctrl+Shift+`)）中安装可能缺少的任何必需依赖项（例如，使用 apt-get）。你至少需要运行 yarn install 或 npm install 以确保 Linux 版本的原生 Node.js 依赖项可用。
最后，按下 F5 或使用运行和调试视图启动扩展并附加调试器，就像在本地一样。

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

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

安装开发版扩展

每当 VS Code 在 SSH 主机、容器或 WSL 内，或通过 GitHub Codespaces 自动安装扩展时，使用的都是市场版本（而不是已安装在你本地机器上的版本）。

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

请按照以下步骤操作

如果这是一个已发布的扩展，你可能希望在 settings.json 中添加 "extensions.autoUpdate": false 以阻止其自动更新到最新的市场版本。
接下来，使用 vsce package 将你的扩展打包为 VSIX 文件。
连接到 codespace、开发容器、SSH 主机或 WSL 环境。
使用扩展视图更多操作（...）菜单中的从 VSIX 安装... 命令将扩展安装到这个特定窗口（而不是本地窗口）。
出现提示时重新加载。

提示：安装后，你可以使用开发者：显示正在运行的扩展命令查看 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 Databases扩展设置为 UI 扩展（而不是其工作区默认类型），并将Remote - SSH: Editing Configuration Files扩展设置为工作区扩展（而不是其 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);
}

使用剪贴板

过去，扩展作者使用 Node.js 模块（如 clipboardy）与剪贴板交互。不幸的是，如果你在工作区扩展中使用这些模块，它们将使用远程剪贴板而不是用户的本地剪贴板。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 Node 模块提供了 shim，以允许现有扩展正常运行。你可以使用 URI 调用该模块，VS Code 会在客户端显示该 URI 的默认应用程序。然而，这不是一个完整的实现，因为不支持选项，并且不返回 child_process 对象。

我们建议扩展利用 vscode.env.openExternal 方法启动你的本地操作系统上为给定 URI 注册的默认应用程序，而不是依赖第三方 Node 模块。更好的是，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('http://localhost: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(`http://localhost:${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，可用作身份验证提供者的回调。在基于浏览器的 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 扩展或都是工作区扩展），这些 API 将工作正常，但它们在 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 服务器。即使您的扩展程序正在运行一些本地 Web 服务，并且您想要与其交互以更新 webview 内容，您也可以从扩展程序本身执行此操作，而不是直接从您的 HTML 内容执行此操作。

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

为什么使用消息传递而不是 localhost Web 服务器？

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

下面是使用 Remote - SSH 扩展程序时出现此问题的示例，但在开发容器和 GitHub Codespaces 中也存在此问题

Webview problem

如果可能，您应该避免这样做，因为它会使您的扩展程序变得非常复杂。消息传递 API 可以实现相同类型的用户体验，而不会带来这些麻烦。扩展程序本身将在远程端的 VS Code Server 中运行，因此它可以透明地与您的扩展程序因收到来自 webview 的任何消息而启动的任何 Web 服务器交互。

从 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(`http://localhost:${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="http://localhost:${LOCAL_STATIC_PORT}/canvas.png">
    </body>
    </html>`;

在此示例中，在远程和本地情况下，对 http://localhost:3000 的任何请求都将自动映射到 Express.js Web 服务器正在运行的动态端口。

使用原生 Node.js 模块

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

为解决此问题

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

您可以通过转到帮助 > 开发人员工具并在控制台中键入 process.versions.modules 来查找 VS Code 使用的“模块”版本。但是，为确保原生模块在不同的 Node.js 环境中无缝工作，您可能需要针对您想要支持的所有可能的 Node.js“模块”版本和平台（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 实现方式的根本差异而无法工作。

为解决此问题

如果您正在动态获取编译代码，您可以通过使用 process.arch 检测非 x86_64 目标并下载为正确架构编译的版本来添加支持。如果您在扩展程序中包含所有受支持架构的二进制文件，则可以使用此逻辑来使用正确的二进制文件。
对于 Alpine Linux，您可以使用 await fs.exists('/etc/alpine-release') 检测操作系统，并再次下载或使用基于 musl 操作系统的正确二进制文件。
如果您不想支持这些平台，可以使用相同的逻辑来提供一条友好的错误消息。

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

避免使用 Electron 模块

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

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

下面的示例将使用 Electron original-fs node 模块（如果找到），如果未找到，则回退到基础 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 仓库问题中跟踪。

问题与反馈

请参阅提示与技巧或常见问题解答。
在Stack Overflow上搜索答案。
为现有功能点赞或请求新功能，搜索现有问题，或报告问题。
创建开发容器模板或特性供他人使用。
为我们的文档或VS Code贡献。
请参阅我们的贡献指南了解详情。

05/08/2025