在容器内开发

Visual Studio Code Dev Containers 扩展允许你将容器用作功能齐全的开发环境。它允许你在容器内（或挂载到容器内）打开任何文件夹，并充分利用 Visual Studio Code 的全部功能。项目中的 devcontainer.json 文件 告诉 VS Code 如何访问（或创建）一个具有明确定义工具和运行时堆栈的 开发容器。该容器可用于运行应用程序或隔离处理代码库所需的工具、库或运行时。

工作区文件从本地文件系统挂载，或复制或克隆到容器中。扩展在容器内安装和运行，在那里它们可以完全访问工具、平台和文件系统。这意味着你可以通过连接到不同的容器来无缝切换整个开发环境。

这使得 VS Code 能够提供本地质量的开发体验，包括完整的 IntelliSense（补全）、代码导航和调试，无论你的工具（或代码）位于何处。

Dev Containers 扩展支持两种主要的运行模式

• 你可以将容器用作你的全职开发环境
• 你可以 附加到正在运行的容器 以检查它。

注意：Dev Containers 扩展支持开放的 Dev Containers 规范，该规范使任何人都可以使用任何工具来配置一致的开发环境。你可以在我们的 开发容器常见问题解答 和规范网站 containers.dev 上了解更多信息。

入门

注意：你可以在介绍性的 Dev Containers 教程 中了解如何快速启动并运行开发容器。

系统要求

本地 / 远程主机

你可以通过以下几种方式使用 Docker 与 Dev Containers 扩展配合使用，包括

• 本地安装 Docker。
• 安装在远程环境上的 Docker。
• 安装在本地或远程的其他 Docker 兼容 CLI。
  • 虽然其他 CLI 也可以工作，但它们不受官方支持。请注意，附加到 Kubernetes 集群 只需要正确配置的 kubectl CLI。

你可以在 替代 Docker 选项文档 中了解更多信息。

以下是一些你可以在本地或远程主机上配置 Docker 的具体方法

• Windows: Windows 10 Pro/Enterprise 上的 Docker Desktop 2.0+。Windows 10 Home (2004+) 需要 Docker Desktop 2.3+ 和 WSL 2 后端。（Docker Toolbox 不受支持。Windows 容器镜像不受支持。）
• macOS: Docker Desktop 2.0+。
• Linux: Docker CE/EE 18.06+ 和 Docker Compose 1.21+。（Ubuntu snap 包不受支持。）
• 远程主机： 需要 1 GB 内存，但建议至少 2 GB 内存和 2 核 CPU。

容器:

• x86_64 / ARMv7l (AArch32) / ARMv8l (AArch64) Debian 9+, Ubuntu 16.04+, CentOS / RHEL 7+
• x86_64 Alpine Linux 3.9+

其他基于 glibc 的 Linux 容器如果具有 所需的 Linux 先决条件，也可能有效。

安装

要开始，请按照以下步骤操作

1. 使用以下方法之一或 替代 Docker 选项（例如远程主机上的 Docker 或 Docker 兼容 CLI）为你的操作系统安装和配置 Docker。

   Windows / macOS:

   1. 安装 Docker Desktop for Windows/Mac。

   2. 如果你正在使用 Windows 上的 WSL 2，要确保启用了 WSL 2 后端：右键单击 Docker 任务栏项目并选择 Settings。选中 Use the WSL 2 based engine，并在 Resources > WSL Integration 下验证你的发行版是否已启用。

   3. 如果未使用 WSL 2 后端，右键单击 Docker 任务栏项目，选择 Settings，并使用你的源代码存储位置更新 Resources > File Sharing。有关故障排除，请参阅 技巧和窍门。

   Linux:

   1. 按照 官方 Docker CE/EE 安装说明 为你的发行版安装。如果你正在使用 Docker Compose，请按照 Docker Compose 说明 进行操作。

   2. 使用终端将你的用户添加到 docker 组：sudo usermod -aG docker $USER

   3. 注销并重新登录以使更改生效。

2. 安装 Visual Studio Code 或 Visual Studio Code Insiders。

3. 安装 Dev Containers 扩展。如果你计划在 VS Code 中使用其他远程扩展，你也可以选择安装 Remote Development 扩展包。

使用 Git 吗？

以下是两个需要考虑的技巧

• 如果你在 Windows 本地和容器内使用相同的仓库，请确保设置一致的行尾。有关详细信息，请参阅 技巧和窍门。
• 如果你使用 Git 凭据管理器进行克隆，你的容器应该已经可以访问你的凭据！如果你使用 SSH 密钥，你也可以选择共享它们。有关详细信息，请参阅 与容器共享 Git 凭据。

选择你的快速入门

本文档包含 3 个快速入门 - 我们建议从最适合你的工作流程和兴趣的快速入门开始

1. 想在快速示例仓库中试用开发容器吗？请查看 快速入门 1：试用开发容器。
2. 想将开发容器添加到你现有的本地克隆项目中吗？请查看 快速入门 2：在容器中打开现有文件夹。
3. 想使用仓库的隔离副本，例如审查 PR 或调查分支而不影响你的本地工作吗？请查看 快速入门 3：在隔离的容器卷中打开 git 仓库或 PR。

快速入门：试用开发容器

最简单的入门方法是尝试其中一个示例开发容器。 Containers 教程 将引导你设置 Docker 和 Dev Containers 扩展，并让你选择一个示例

注意：如果你已经安装了 VS Code 和 Docker，那么你可以使用 在 dev 容器中打开。你可以在 创建 dev 容器指南 中了解更多信息。

快速入门：在容器中打开现有文件夹

此快速入门介绍如何为现有项目设置开发容器，以使用文件系统上的现有源代码作为你的全职开发环境。请按照以下步骤操作

1. 启动 VS Code，从命令面板 (F1) 或状态栏快速操作项运行 Dev Containers: Open Folder in Container... 命令，然后选择你想要设置容器的项目文件夹。

   提示： 如果你想在打开文件夹之前编辑容器的内容或设置，你可以运行 Dev Containers: Add Dev Container Configuration Files...。

   

2. 现在选择开发容器的起点。你可以从可筛选列表中选择一个基本 Dev Container Template，或者如果所选文件夹中存在一个现有的 Dockerfile 或 Docker Compose 文件，则可以使用它。

   注意： 当使用 Alpine Linux 容器时，某些扩展可能无法工作，因为扩展内部的本地代码存在 glibc 依赖项。

   

   列表将根据你打开的文件夹的内容自动排序。

   你可能可以使用额外的 Features 自定义你的开发容器，你可以在下面了解更多信息。

   显示的 dev container Templates 来自我们的 第一方和社区索引，它是 Dev Container Specification 的一部分。我们作为规范的一部分托管一组 Templates 在 devcontainers/templates 仓库 中。你可以浏览该仓库的 src 文件夹以查看每个 Template 的内容。

   你还可以选择使用 dev container CLI 发布和分发你自己的 dev container Templates。

3. 选择容器的起点后，VS Code 会将 dev 容器配置文件添加到你的项目 (.devcontainer/devcontainer.json)。

4. VS Code 窗口将重新加载并开始构建 dev 容器。进度通知提供状态更新。你只需要在第一次打开容器时构建它；之后再次打开文件夹会更快。

   

5. 构建完成后，VS Code 将自动连接到容器。

现在你可以像在本地打开项目一样在 VS Code 中与你的项目交互。从现在开始，当你打开项目文件夹时，VS Code 会自动获取并重用你的 dev 容器配置。

提示： 想使用远程 Docker 主机吗？请参阅有关 在容器中打开远程 SSH 主机上的文件夹 的部分，了解更多信息。

虽然使用这种方法将 绑定挂载 本地文件系统到容器中很方便，但它在 Windows 和 macOS 上有一些性能开销。你可以应用 一些技术 来提高磁盘性能，或者你可以 在隔离的容器卷中使用容器打开仓库。

在 Windows 上在容器中打开 WSL 2 文件夹

如果你正在使用 Windows Subsystem for Linux v2 (WSL 2) 并已启用 Docker Desktop 的 WSL 2 后端，你可以使用存储在 WSL 中的源代码！

启用 WSL 2 引擎后，你可以

• 使用 Dev Containers: Reopen in Container 命令从已经使用 WSL 扩展打开的文件夹中重新打开。
• 从命令面板 (F1) 选择 Dev Containers: Open Folder in Container...，并使用本地 \\wsl$ 共享选择一个 WSL 文件夹（从 Windows 侧）。

其余的快速入门步骤保持不变！您可以在此处查阅 WSL 扩展的文档了解更多信息。

在容器中打开远程 SSH 主机上的文件夹

如果您使用的是 Linux 或 macOS SSH 主机，您可以将 远程 - SSH 和 Dev Containers 扩展程序一起使用。您甚至不需要在本地安装 Docker 客户端。

操作步骤如下：

1. 按照 安装 和 SSH 主机设置 步骤操作，以配置远程 - SSH 扩展程序。
2. 可选： 设置 SSH 基于密钥的身份验证到服务器，这样你就不需要多次输入密码。
3. 在您的 SSH 主机上安装 Docker。您不需要在本地安装 Docker。
4. 按照 快速入门 步骤操作，以配置远程 - SSH 扩展程序，连接到主机并在那里打开一个文件夹。
5. 从命令面板（F1，⇧⌘P (Windows, Linux Ctrl+Shift+P)）使用 开发容器：在容器中重新打开 命令。

其余的 Dev Containers 快速入门步骤保持不变。您可以在此处查阅远程 - SSH 扩展的文档了解更多信息。如果您觉得此模型不符合您的需求，还可以参阅 在远程 Docker 主机上开发 文章，了解其他选项。

在容器中打开远程 Tunnel 主机上的文件夹

您可以将 远程 - Tunnel 和 Dev Containers 扩展程序一起使用，在容器内打开远程主机上的文件夹。您甚至不需要在本地安装 Docker 客户端。这与上面的 SSH 主机方案类似，但使用远程 - Tunnel 代替。

操作步骤如下：

1. 按照 入门 说明操作，以配置远程 - Tunnel 扩展程序。
2. 在您的 Tunnel 主机上安装 Docker。您不需要在本地安装 Docker。
3. 按照 步骤 操作，以配置远程 - Tunnel 扩展程序，连接到 Tunnel 主机并在那里打开一个文件夹。
4. 从命令面板（F1，⇧⌘P (Windows, Linux Ctrl+Shift+P)）使用 开发容器：在容器中重新打开 命令。

其余的 Dev Containers 快速入门步骤保持不变。您可以在此处查阅远程 - Tunnel 扩展的文档了解更多信息。如果您觉得此模型不符合您的需求，还可以参阅 在远程 Docker 主机上开发 文章，了解其他选项。

在容器中打开现有的工作区

您也可以遵循类似的过程，在单个容器中打开一个 VS Code 多根工作区，前提是工作区仅引用 .code-workspace 文件所在文件夹的子文件夹的相对路径（或文件夹本身）。

您可以选择

• 使用 Dev Containers: 在容器中打开工作区... 命令。
• 在您打开包含 .code-workspace 文件的文件夹后，使用 文件 > 打开工作区...。

连接后，您可能需要将 .devcontainer 文件夹添加到工作区，以便在它尚未可见时轻松编辑其内容。

另外请注意，虽然您不能在同一个 VS Code 窗口中使用多个容器来处理同一个工作区，但您可以从单独的窗口使用 多个 Docker Compose 管理的容器。

快速入门：在隔离的容器卷中打开 Git 仓库或 GitHub PR

虽然您可以 在容器中打开本地克隆的仓库，但您可能希望使用仓库的隔离副本进行 PR 审查或调查另一个分支，而不会影响您的工作。

仓库容器使用隔离的本地 Docker 卷，而不是绑定到本地文件系统。除了不污染您的文件树之外，本地卷还具有在 Windows 和 macOS 上提高性能的额外好处。（有关如何在其他场景中使用这些类型的卷的信息，请参阅高级配置 提高磁盘性能 文章。）

例如，请按照以下步骤在仓库容器中打开其中一个“试用”仓库

1. 启动 VS Code，然后从命令面板 (F1) 运行 Dev Containers: 在容器卷中克隆仓库...。

2. 在出现的输入框中输入 microsoft/vscode-remote-try-node（或另一个“试用”仓库）、Git URI、GitHub 分支 URL 或 GitHub PR URL，然后按 Enter。

   

   提示： 如果您选择私有仓库，您可能需要设置凭据管理器或将 SSH 密钥添加到 SSH 代理。请参阅 与容器共享 Git 凭据。

3. 如果您的仓库中没有 .devcontainer/devcontainer.json 文件，系统会要求您从可筛选的列表中或现有的 Dockerfile 或 Docker Compose 文件（如果存在）中选择一个起始点。

   注意： 当使用 Alpine Linux 容器时，某些扩展可能无法工作，因为扩展内部的本地代码存在 glibc 依赖项。

   

   列表将根据您打开的文件夹的内容自动排序。显示的开发容器模板来自我们的 第一方和社区索引，它是 Dev Container 规范 的一部分。我们在 devcontainers/templates 仓库 中托管一组模板作为规范的一部分。您可以浏览该仓库的 src 文件夹，以查看每个模板的内容。

4. VS Code 窗口（实例）将重新加载，克隆源代码并开始构建开发容器。进度通知会提供状态更新。

   

   如果您在步骤 2 中粘贴了 GitHub 拉取请求 URL，则会自动签出 PR，并且 GitHub 拉取请求 扩展程序将安装在容器中。该扩展程序提供额外的 PR 相关功能，例如 PR 资源管理器、内联交互式 PR 注释以及状态栏可见性。

   

5. 构建完成后，VS Code 将自动连接到容器。现在，您可以像在本地克隆代码一样，在此独立环境中处理仓库源代码。

请注意，如果由于 Docker 构建错误等原因导致容器无法启动，您可以选择在出现的对话框中选择 以恢复容器重新打开，以进入一个“恢复容器”，该容器允许您编辑 Dockerfile 或其他内容。这将以最小容器打开 docker 卷，其中包含克隆的仓库，并向您显示创建日志。完成修复后，使用 以容器重新打开 重新尝试。

提示： 想使用远程 Docker 主机吗？请参阅有关 在容器中打开远程 SSH 主机上的文件夹 的部分，了解更多信息。

信任你的工作区

Visual Studio Code 非常重视安全性，并希望帮助您安全地浏览和编辑代码，无论其来源或原始作者如何。工作区信任功能 允许您决定您的项目文件夹是否应该允许或限制自动代码执行。

Dev Containers 扩展程序已采用工作区信任。根据您打开和交互源代码的方式，您将在不同的时间点被提示决定是否信任您正在编辑或执行的代码。

在容器中重新打开文件夹

为现有项目设置开发容器 需要信任本地（或 WSL）文件夹。窗口重新加载前，系统会要求您信任本地（或 WSL）文件夹。

此流程有几个例外

1. 单击最近条目时。
2. 使用 在容器中打开文件夹 命令将在窗口重新加载后要求信任（如果尚未授予信任）。

附加到现有容器

当 附加到现有容器 时，系统会要求您确认附加意味着您信任该容器。这仅确认一次。

在卷中克隆仓库

当 在容器卷中克隆仓库 时，系统会要求您确认克隆仓库意味着您信任该仓库。这仅确认一次。

检查卷

检查卷 从 受限模式 开始，您可以信任容器内的文件夹。

Docker 守护程序在远程运行

这意味着信任 运行 Docker 守护程序的主机。没有其他提示需要确认（仅上述本地/WSL 情况）。

创建 devcontainer.json 文件

VS Code 的容器配置存储在 devcontainer.json 文件中。此文件类似于调试配置的 launch.json 文件，但用于启动（或附加到）您的开发容器。您还可以指定在容器运行时要安装的任何扩展程序或准备环境的创建后命令。dev 容器配置位于 .devcontainer/devcontainer.json 下，或者存储为项目根目录中的 .devcontainer.json 文件（请注意点前缀）。

从命令面板 (F1) 选择 Dev Containers: 添加开发容器配置文件... 命令将在您的项目中添加所需的文件作为起点，您可以进一步自定义这些文件以满足您的需求。该命令允许您根据文件夹的内容从列表中选择预定义的容器配置，重用现有的 Dockerfile，或重用现有的 Docker Compose 文件。

您还可以手动创建 devcontainer.json 文件，并使用任何镜像、Dockerfile 或一组 Docker Compose 文件作为起点。这是一个简单的示例，它使用其中一个预构建的 开发容器镜像

{
  "image": "mcr.microsoft.com/devcontainers/typescript-node",
  "forwardPorts": [3000],
  "customizations": {
    // Configure properties specific to VS Code.
    "vscode": {
      // Add the IDs of extensions you want installed when the container is created.
      "extensions": ["streetsidesoftware.code-spell-checker"]
    }
  }
}

注意： 基于基本镜像的内容，容器中已经会添加额外的配置。例如，我们上面添加了 streetsidesoftware.code-spell-checker 扩展程序，并且容器还将包含 "dbaeumer.vscode-eslint" 作为 mcr.microsoft.com/devcontainers/typescript-node 的一部分。当使用 devcontainer.json 进行预构建时，这会自动发生，您可以在 预构建部分 中了解更多信息。

要了解有关创建 devcontainer.json 文件的更多信息，请参阅 创建开发容器。

开发容器特性

开发容器“功能”是自包含的、可共享的安装代码和开发容器配置单元。之所以命名为“功能”，是因为引用其中一个功能可以快速轻松地将更多工具、运行时或库“功能”添加到您的开发容器中，供您或您的协作者使用。

当您使用 Dev Containers: 添加开发容器配置文件 时，系统会向您呈现一个脚本列表，用于自定义现有的开发容器配置，例如安装 Git 或 Azure CLI

在重新构建并在容器中重新打开时，您选择的功能将在您的 devcontainer.json 中可用

"features": {
    "ghcr.io/devcontainers/features/github-cli:1": {
        "version": "latest"
    }
}

在直接编辑 "features" 属性时，您将获得 IntelliSense

Dev Containers: 配置容器功能 命令允许您更新现有的配置。

VS Code UI 中的功能现在来自中心索引，您也可以为此做出贡献。请参阅 Dev Containers 规范网站 以获取当前列表，以及 了解如何发布和分发功能。

"始终安装"的功能

就像你可以 设置扩展始终安装 在你的开发容器中一样，你可以使用

"dev.containers.defaultFeatures": {
    "ghcr.io/devcontainers/features/github-cli:1": {}
},

创建你自己的功能

创建和发布你自己的 Dev Container 功能也很容易。已发布的功能可以存储和共享为 OCI Artifacts，来自任何支持的公共或私有容器注册表。你可以在 containers.dev 上查看当前已发布功能的列表。

一个功能是一个自包含的实体，位于一个文件夹中，至少包含一个 devcontainer-feature.json 和 install.sh 入口点脚本

+-- feature
|    +-- devcontainer-feature.json
|    +-- install.sh
|    +-- (other files)

查看 feature/starter 仓库，了解有关使用 dev container CLI 发布你自己的公共或私有功能的说明。

功能规范和分发

功能是开源 Development Containers Specification 的关键部分。你可以查看 有关功能工作原理的更多信息 及其 分发。

预构建开发容器镜像

我们建议使用预构建的镜像来包含你需要的工具，而不是每次在开发容器中打开项目时创建和构建容器镜像。使用预构建的镜像将导致更快的容器启动、更简单的配置，并允许你固定到特定版本的工具，以提高供应链安全性并避免潜在的中断。你可以通过使用 DevOps 或持续集成 (CI) 服务（如 GitHub Actions）来安排构建，从而自动预构建你的镜像。

更好的是 - 预构建的镜像可以包含 Dev Container 元数据，因此当你引用一个镜像时，设置将自动提取。

我们建议使用 Dev Container CLI（或其他 规范 支持的实用程序，如 GitHub Action）来预构建你的镜像，因为它与 Dev Containers 扩展的最新功能保持同步 - 包括 dev container 功能。构建完镜像后，你可以将其推送到容器注册表（如 Azure Container Registry、GitHub Container Registry 或 Docker Hub）并直接引用它。

你可以使用 devcontainers/ci 仓库中的 GitHub Action 来帮助你在工作流程中重用 dev 容器。

转到 dev container CLI 文章关于预构建镜像 以获取更多信息。

继承元数据

你可以通过 镜像标签 在预构建的镜像中包含 Dev Container 配置和功能元数据。这使得镜像自包含，因为这些设置在引用镜像时会自动提取 - 无论是直接引用、在引用的 Dockerfile 中的 FROM 中，还是在 Docker Compose 文件中。这有助于防止你的 Dev Container 配置和镜像内容不同步，并允许你通过简单的镜像引用将同一配置的更新推送到多个仓库。

当你使用 Dev Container CLI（或其他 规范 支持的实用程序，如 GitHub Action 或 Azure DevOps 任务）预构建时，此元数据标签会 自动添加，并包含 devcontainer.json 和任何引用的 Dev Container 功能中的设置。

这允许你拥有一个单独的 更复杂 devcontainer.json 用于预构建你的镜像，然后是多个仓库中的一个 简化版。镜像的内容将在你创建容器时与此简化的 devcontainer.json 内容合并（有关合并逻辑，请转到 规范）。但最简单地说，你可以直接在 devcontainer.json 中引用镜像以使设置生效

{
  "image": "mcr.microsoft.com/devcontainers/go:1"
}

请注意，你也可以选择手动将元数据添加到镜像标签。即使你没有使用 Dev Container CLI 进行构建（并且 CLI 即使在使用时也可以更新），这些属性也会被提取。

LABEL devcontainer.metadata='[{ \
  "capAdd": [ "SYS_PTRACE" ], \
  "remoteUser": "devcontainer", \
  "postCreateCommand": "yarn install" \
}]'

检查卷

有时你可能会遇到使用你想要检查或修改的 Docker 命名卷的情况。你可以使用 VS Code 在不创建或修改 devcontainer.json 文件的情况下使用这些内容，方法是从命令面板 (F1) 中选择 Dev Containers: 在 Dev Container 中探索一个卷...。

你还可以使用 Remote Explorer 检查你的卷。确保你在下拉列表中选择了 Containers，然后你将看到一个 Dev Volumes 部分。你可以右键单击一个卷来检查其创建信息，例如卷的创建时间、克隆到其中的仓库以及挂载点。你也可以在开发容器中探索它。

如果你安装了 Container Tools 扩展，你可以右键单击 Container Explorer 的 Volumes 部分中的一个卷，然后选择 在开发容器中探索。

管理扩展

VS Code 在两个地方运行扩展：UI / 客户端侧本地，或在容器中。虽然影响 VS Code UI（如主题和代码片段）的扩展程序安装在本地，但大多数扩展程序将驻留在特定的容器中。这允许你仅为给定任务在容器中安装你需要的扩展程序，并通过仅连接到新的容器来无缝切换整个工具链。

如果你从扩展视图安装一个扩展程序，它将自动安装在正确的位置。你可以根据类别分组来判断扩展程序安装在哪里。将有一个 Local - Installed 类别，以及一个用于你的容器的类别。

注意： 如果你是扩展程序作者，并且你的扩展程序无法正常工作或安装在错误的位置，请参阅 Supporting Remote Development 以获取详细信息。

实际上需要远程运行的本地扩展程序在 Local - Installed 类别中将显示为 Disabled。选择 Install 以在你的远程主机上安装扩展程序。

你可以通过转到扩展视图并选择 Install Local Extensions in Dev Container: {Name} 使用云按钮在 Local - Installed 标题栏的右侧，将所有本地安装的扩展程序安装到 Dev Container 中。这将显示一个下拉菜单，你可以在其中选择要安装在容器中的本地安装的扩展程序。

但是，某些扩展程序可能需要你 在容器中安装其他软件。如果遇到问题，请参阅扩展程序文档以获取详细信息。

将扩展程序添加到 devcontainer.json

虽然你可以手动编辑你的 devcontainer.json 文件以添加扩展程序 ID 列表，但你也可以右键单击扩展视图中的任何扩展程序，然后选择 Add to devcontainer.json。

退出扩展程序

如果基本镜像或功能配置了一个你不希望安装在你的开发容器中的扩展程序，你可以通过使用减号列出该扩展程序来退出。例如

{
  "image": "mcr.microsoft.com/devcontainers/typescript-node:1-20-bookworm",
  "customizations": {
    "vscode": {
      "extensions": ["-dbaeumer.vscode-eslint"]
    }
  }
}

"始终安装"的扩展程序

如果有你希望始终安装在任何容器中的扩展程序，你可以更新

"dev.containers.defaultExtensions": [
    "eamodio.gitlens",
    "mutantdino.resourcemonitor"
]

高级：强制扩展程序在本地或远程运行

扩展通常设计和测试为仅在本地或远程运行，而不是两者都运行。但是，如果扩展支持，你可以在 settings.json 文件中强制它在特定位置运行。

例如，以下设置将强制 Container Tools 扩展在本地运行，以及 Remote - SSH: Editing Configuration Files 扩展在远程运行，而不是使用它们的默认设置：

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

与 "workspace" 相比，"ui" 值将强制扩展程序在本地 UI / 客户端侧运行。通常，除非扩展程序的文档另有说明，否则仅应将其用于测试，因为它 可能会破坏扩展程序。有关详细信息，请参阅 首选扩展程序位置。

转发或发布端口

容器是单独的环境，因此如果你想访问容器内的服务器、服务或其他资源，你需要通过“转发”或“发布”端口到你的主机。你可以配置你的容器始终公开这些端口，或者仅临时转发它们。

始终转发端口

你可以通过在 devcontainer.json 中使用 forwardPorts 属性来指定你 始终 希望在附加或打开容器中的文件夹时转发的端口列表。

"forwardPorts": [3000, 3001]

只需重新加载/重新打开窗口，设置将在 VS Code 连接到容器时应用。

临时转发端口

如果你需要访问你未添加到 devcontainer.json 或在你的 Docker Compose 文件中发布的端口，你可以通过从命令面板 (F1) 运行 Forward a Port 命令来 临时转发 一个新端口，以用于会话期间。

选择端口后，通知将告诉你你应该使用的 localhost 端口来访问容器中的端口。例如，如果你转发了一个侦听端口 3000 的 HTTP 服务器，通知可能会告诉你它映射到 localhost 上的端口 4123。然后你可以使用 https://:4123 连接到此远程 HTTP 服务器。

这些信息也可用在 Remote Explorer 的 Forwarded Ports 部分，如果你以后需要访问它。

如果您希望 VS Code 记住您转发的任何端口，请在设置编辑器中选中“Remote: Restore Forwarded Ports”（⌘, (Windows, Linux Ctrl+,)）或在 settings.json 中设置 "remote.restoreForwardedPorts": true。

发布端口

Docker 在创建容器时具有“发布”端口的概念。发布的端口的行为非常类似于您提供给本地网络使用的端口。如果您的应用程序仅接受来自 localhost 的调用，它将拒绝来自已发布端口的连接，就像您的本地机器拒绝网络调用的方式一样。另一方面，转发的端口实际上看起来像 localhost 对应用程序而言。两者在不同的情况下都可能有用。

要发布端口，您可以

1. 使用 appPort 属性： 如果您在 devcontainer.json 中引用了镜像或 Dockerfile，则可以使用 appPort 属性将端口发布到主机。

   "appPort": [ 3000, "8921:5000" ]
   

2. 使用 Docker Compose 端口映射： 端口映射可以轻松地添加到您的 docker-compose.yml 文件中以发布其他端口。

   ports:
   - "3000"
   - "8921:5000"
   

在每种情况下，您都需要重建容器才能使设置生效。您可以在连接到容器时，在命令面板（F1）中运行 Dev Containers: Rebuild Container 命令来执行此操作。

打开终端

从 VS Code 在容器中打开终端很简单。一旦您在容器中打开了一个文件夹，您在 VS Code 中打开的任何终端窗口（Terminal > New Terminal）都将自动在容器中而不是本地运行。

您还可以从同一个终端窗口使用 code 命令行执行许多操作，例如在容器中打开新文件或文件夹。键入 code --help 以了解命令行中可用的选项。

在容器中调试

一旦您在容器中打开了一个文件夹，您就可以像在本地运行应用程序时一样使用 VS Code 的调试器。例如，如果您在 launch.json 中选择一个启动配置并开始调试（F5），应用程序将启动在远程主机上并将其附加到调试器。

有关在 .vscode/launch.json 中配置 VS Code 调试功能的详细信息，请参阅调试文档。

容器特定设置

当您连接到开发容器时，VS Code 的本地用户设置也会被重用。虽然这保持了您一致的用户体验，但您可能希望在本地机器和每个容器之间更改其中一些设置。幸运的是，一旦您连接到容器，您还可以通过从命令面板（F1）运行 Preferences: Open Remote Settings 命令或选择设置编辑器中的 Remote 选项卡来设置容器特定的设置。这些设置将在您连接到容器时覆盖您拥有的任何本地设置。

默认容器特定设置

您可以使用 settings 属性在 devcontainer.json 中包含容器特定设置的默认值。这些值将在创建容器后自动放置在容器特定的设置文件中。

例如，将以下内容添加到 .devcontainer/devcontainer.json 将设置 Java 主路径

// Configure tool-specific properties.
"customizations": {
    // Configure properties specific to VS Code.
    "vscode": {
        "settings": {
            "java.home": "/docker-java-home"
        }
    }
}

由于这只是建立默认值，因此您仍然可以在创建容器后根据需要更改设置。

管理容器

默认情况下，Dev Containers 扩展会在您打开文件夹时自动启动 devcontainer.json 中提到的容器。当您关闭 VS Code 时，该扩展会自动关闭您已连接的容器。您可以通过将 "shutdownAction": "none" 添加到 devcontainer.json 来更改此行为。

虽然您可以使用命令行来管理容器，但您也可以使用 Remote Explorer。要停止容器，请从下拉菜单中选择 Containers（如果存在），右键单击正在运行的容器，然后选择 Stop Container。您还可以启动已退出的容器、删除容器和删除最近的文件夹。从“详细信息”视图中，您可以转发端口并在浏览器中打开已转发的端口。

如果您想清理镜像或批量删除容器，请参阅 清理未使用的容器和镜像，了解不同的选项。

使用 dotfile 仓库个性化

点文件是文件名以点（.）开头的文件，通常包含各种应用程序的配置信息。由于开发容器可以涵盖广泛的应用程序类型，因此将这些文件存储在某个位置以便在容器启动并运行后轻松复制到容器中可能很有用。

一种常见的方法是将这些点文件存储在 GitHub 存储库中，然后使用实用程序来克隆和应用它们。Dev Containers 扩展内置支持与您自己的容器一起使用这些文件。如果您对这个想法还不熟悉，请查看现有的不同 点文件引导存储库。

要使用它，请将您的点文件 GitHub 存储库添加到 VS Code 的用户设置（⌘, (Windows, Linux Ctrl+,)）如下所示

或者在 settings.json 中

{
  "dotfiles.repository": "your-github-id/your-dotfiles-repo",
  "dotfiles.targetPath": "~/dotfiles",
  "dotfiles.installCommand": "install.sh"
}

从现在开始，每次创建容器时都会使用点文件存储库。

已知限制

Dev Containers 限制

• 不支持 Windows 容器镜像。
• 多根工作区中的所有根/文件夹都将在同一个容器中打开，无论较低级别是否存在配置文件。
• Linux 的非官方 Ubuntu Docker snap 包不受支持。请遵循 适用于您的发行版的官方 Docker 安装说明。
• Windows 上的 Docker Toolbox 不受支持。
• 如果你使用 SSH 克隆 Git 仓库，并且你的 SSH 密钥有密码短语，VS Code 的拉取和同步功能在远程运行时可能会挂起。请使用不带密码短语的 SSH 密钥，使用 HTTPS 克隆，或者从命令行运行 git push 来解决此问题。
• 本地代理设置不会在容器内部重用，这可能会阻止扩展工作，除非配置了适当的代理信息（例如，具有适当代理信息的全局 HTTP_PROXY 或 HTTPS_PROXY 环境变量）。
• 当 ssh-agent 运行版本 <= 8.8 并且 SSH 客户端（在任何平台上）运行版本 >= 8.9 时，Windows 上的 OpenSSH 版本之间存在不兼容性。解决方法是在 Windows 上将 OpenSSH 升级到 8.9 或更高版本，可以使用 winget 或来自 Win32-OpenSSH/releases 的安装程序。 （请注意，ssh-add -l 将正常工作，但 ssh <ssh-server> 将因 <ssh-server>: Permission denied (publickey) 而失败。这也会在使用 SSH 连接到存储库时影响 Git。）

有关与容器相关的活动问题列表，请参阅 此处。

Docker 限制

有关更多信息，请参阅 Docker 故障排除指南，了解 Windows 或 Mac。

容器工具扩展限制

如果您正在从 WSL、Remote - Tunnels 或 Remote - SSH 窗口使用 Container Tools 或 Kubernetes 扩展，则使用 Container Explorer 或 Kubernetes 视图中的“Attach Visual Studio Code”上下文菜单操作将要求您再次从可用容器中选择。

扩展限制

此时，大多数扩展程序都将在 Dev Containers 内部工作，无需修改。但是，在某些情况下，某些功能可能需要更改。如果您遇到扩展问题，请参阅 此处，了解常见问题和解决方案的摘要，您可以在报告问题时向扩展作者提及。

此外，虽然提供 Alpine 支持，但由于扩展程序内部的本机代码中存在 glibc 依赖项，某些安装在容器中的扩展程序可能无法工作。有关详细信息，请参阅 使用 Linux 进行远程开发 文章。

高级容器配置

有关以下主题的高级容器配置文章，请参阅 高级容器配置

• 添加环境变量
• 添加另一个本地文件挂载
• 更改或删除默认源代码挂载
• 提高容器磁盘性能
• 将非 root 用户添加到您的开发容器
• 为 Docker Compose 设置项目名称
• 从容器内部使用 Docker 或 Kubernetes
• 同时连接到多个容器
• 在远程 Docker Machine 或 SSH 主机上的容器内开发
• 减少 Dockerfile 构建警告
• 与容器共享 git 凭据

devcontainer.json 参考

有一个完整的 devcontainer.json 参考，您可以在其中查看文件模式，以帮助您自定义开发容器并控制如何连接到正在运行的容器。

问题或反馈

• 请参阅 技巧和窍门 或 常见问题。
• 在 Stack Overflow 上搜索。
• 添加功能请求或报告问题。
• 创建开发容器模板或特性供他人使用。
• 查看并提供有关 开发容器规范 的反馈。
• 为我们的文档或VS Code 本身做出贡献。
• 请参阅我们的贡献指南了解详细信息。

故障排除

无法写入文件 (NoPermissions (FileSystemError))

您可能会在以下配置中运行开发容器时遇到此问题

• Docker Desktop 运行 Windows Subsystem for Linux (WSL) 后端
• 增强的容器隔离 (ECI) 已启用

请查看 问题 #8278，了解可能的解决方法。

后续步骤

• 附加到正在运行的容器 - 附加到已经运行的 Docker 容器。
• 创建开发容器 - 为您的工作环境创建一个自定义容器。
• 高级容器 - 查找高级容器场景的解决方案。
• devcontainer.json 参考 - 查看 devcontainer.json 模式。