在容器中开发

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

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

Container Architecture

这使得 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 专业版/企业版上的 Docker Desktop 2.0+。Windows 10 家庭版 (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 RAM，但建议至少 2 GB RAM 和 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 先决条件，它们也可能正常工作。

安装

要开始使用，请遵循以下步骤：

针对您的操作系统安装和配置 Docker，使用以下路径之一或替代 Docker 选项（如远程主机上的 Docker 或兼容 Docker 的 CLI）。

Windows / macOS:
1. 安装 Docker Desktop for Windows/Mac。
2. 如果您在 Windows 上使用 WSL 2，请确保启用了 WSL 2 后端：右键单击任务栏上的 Docker 图标并选择设置 (Settings)。勾选使用基于 WSL 2 的引擎 (Use the WSL 2 based engine)，并在资源 (Resources) > WSL 集成 (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. 登出并重新登录以使更改生效。
安装 Visual Studio Code 或 Visual Studio Code Insiders。
安装 Dev Containers 扩展。如果您计划在 VS Code 中使用其他远程扩展，您可以选择安装 Remote Development 扩展包。

正在使用 Git？

以下是两条建议参考：

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

选择您的快速入门

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

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

快速入门：尝试开发容器

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

Select a sample from the list

注意：如果您已经安装了 VS Code 和 Docker，则可以使用在开发容器中打开。您可以在创建开发容器指南中了解有关此内容以及如何将其添加到您的仓库的更多信息。

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

本快速入门介绍了如何使用文件系统上的现有源代码为现有项目设置开发容器，以将其用作全职开发环境。请遵循以下步骤

启动 VS Code，从命令面板（F1）或快速操作状态栏项运行 Dev Containers: Open Folder in Container...（Dev Containers: 在容器中打开文件夹...） 命令，然后选择要为其设置容器的项目文件夹。

提示：如果您想在打开文件夹之前编辑容器的内容或设置，可以改为运行 Dev Containers: Add Dev Container Configuration Files...（Dev Containers: 添加开发容器配置文件...）。
现在为您的开发容器选择一个起点。您可以从可筛选的列表中选择基础开发容器模板 (Dev Container Template)，或者如果所选文件夹中存在现有的 Dockerfile 或 Docker Compose 文件，则使用它们。

注意：当使用 Alpine Linux 容器时，由于扩展内原生代码中的 glibc 依赖项，某些扩展可能无法正常工作。

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

您可以使用其他功能 (Features) 来定制您的开发容器，您可以在下方了解更多信息。

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

您还可以选择使用开发容器 CLI 发布和分发您自己的开发容器模板。
为容器选择起点后，VS Code 会将开发容器配置文件添加到您的项目中（.devcontainer/devcontainer.json）。
VS Code 窗口将重新加载并开始构建开发容器。进度通知会提供状态更新。您只需在第一次打开开发容器时对其进行构建；在首次成功构建后打开文件夹将会快得多。
构建完成后，VS Code 将自动连接到容器。

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

提示：想要使用远程 Docker 主机？有关信息，请参阅在容器中打开远程 SSH 主机上的文件夹一节。

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

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

如果您正在使用适用于 Linux 的 Windows 子系统 v2 (WSL 2) 并且已启用 Docker Desktop 的 WSL 2 后端，您就可以处理存储在 WSL 内部的源代码！

启用 WSL 2 引擎后，您可以：

从已使用 WSL 扩展打开的文件夹中运行 Dev Containers: Reopen in Container（Dev Containers: 在容器中重新打开） 命令。
从命令面板（F1）中选择 Dev Containers: Open Folder in Container...（Dev Containers: 在容器中打开文件夹...） 并使用本地 \\wsl$ 共享（从 Windows 端）选择一个 WSL 文件夹。

快速入门的其余部分原样适用！您可以在其文档中了解有关 WSL 扩展的更多信息。

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

如果您使用的是 Linux 或 macOS SSH 主机，则可以同时使用 Remote - SSH 和 Dev Containers 扩展。您甚至不需要在本地安装 Docker 客户端。

要做到这一点

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

Dev Containers 快速入门的其余部分原样适用。您可以在其文档中了解有关 Remote - SSH 扩展的更多信息。如果此模型不满足您的需求，您还可以参阅在远程 Docker 主机上开发一文以了解其他选项。

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

您可以结合使用 Remote - Tunnels 和 Dev Containers 扩展，在容器内部打开远程主机上的文件夹。您甚至无需在本地安装 Docker 客户端。这类似于上面的 SSH 主机场景，但改用了 Remote - Tunnels。

要做到这一点

按照 Remote - Tunnels 扩展的入门说明进行操作。
在您的 tunnel 主机上安装 Docker。您无需在本地安装 Docker。
按照 Remote - Tunnels 扩展的步骤连接到 tunnel 主机并在那里打开文件夹。
从命令面板（F1，⇧⌘P (Windows, Linux Ctrl+Shift+P)）使用 开发容器：在容器中重新打开 命令。

Dev Containers 快速入门的其余部分原样适用。您可以在其文档中了解有关 Remote - Tunnels 扩展的更多信息。如果此模型不满足您的需求，您还可以参阅在远程 Docker 主机上开发一文以了解其他选项。

在容器中打开现有工作区

如果工作区仅引用了 .code-workspace 文件所在的文件夹的子文件夹的相对路径（或文件夹本身），您还可以按照类似的过程在单个容器中打开 VS Code 多根工作区。

您可以：

使用 Dev Containers: Open Workspace in Container...（Dev Containers: 在容器中打开工作区...） 命令。
在容器中打开包含 .code-workspace 文件的文件夹后，使用文件 (File) > 打开工作区... (Open Workspace...)。

连接后，如果您希望方便地编辑其内容（如果它当前不可见），您可能想要将 .devcontainer 文件夹添加到工作区。

还要注意，虽然您不能在同一个 VS Code 窗口中为同一个工作区使用多个容器，但您可以从不同的窗口同时使用多个由 Docker Compose 管理的容器。

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

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

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

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

启动 VS Code 并从命令面板（F1）运行 Dev Containers: Clone Repository in Container Volume...（Dev Containers: 在容器卷中克隆仓库...）。
在出现的输入框中输入 microsoft/vscode-remote-try-node（或其他“try”仓库之一）、Git URI、GitHub 分支 URL 或 GitHub PR URL，然后按 Enter。

提示：如果您选择私有仓库，您可能需要设置凭据管理器或将您的 SSH 密钥添加到您的 SSH 代理。请参阅与容器共享 Git 凭据。
如果您的仓库根目录中没有 .devcontainer/devcontainer.json 文件，系统会要求您从可筛选的列表中或从现有的 Dockerfile 或 Docker Compose 文件（如果存在）中选择一个起点。

注意：当使用 Alpine Linux 容器时，由于扩展内原生代码中的 glibc 依赖项，某些扩展可能无法正常工作。

该列表将根据您打开的文件夹的内容自动排序。显示的开发容器模板来自我们的官方及社区索引，它是 Dev Container 规范的一部分。我们在 devcontainers/templates 仓库中托管了一组作为规范一部分的模板。您可以浏览该仓库的 src 文件夹以查看每个模板的内容。
VS Code 窗口（实例）将重新加载、克隆源代码并开始构建开发容器。进度通知会提供状态更新。

如果您在第 2 步中粘贴了 GitHub 拉取请求 URL，该 PR 将自动检出，并且 GitHub Pull Requests 扩展将被安装在容器中。该扩展提供了其他与 PR 相关的功能，例如 PR 资源管理器、内联与 PR 评论交互以及状态栏可见性。
构建完成后，VS Code 将自动连接到容器。现在，您可以在此独立环境中操作仓库源代码，就像在本地克隆代码一样。

请注意，如果容器由于 Docker 构建错误之类的问题而无法启动，您可以在弹出的对话框中选择 Reopen in Recovery Container（在恢复容器中重新打开） 进入“恢复容器”，这允许您编辑 Dockerfile 或其他内容。这会在最简容器中打开包含已克隆仓库的 docker 卷并向您显示创建日志。修复完成后，使用 Reopen in Container（在容器中重新打开） 重试。

提示：想要使用远程 Docker 主机？有关信息，请参阅在容器中打开远程 SSH 主机上的文件夹一节。

信任您的工作区

Visual Studio Code 非常重视安全性，并希望无论代码来源或原始作者是谁，都能帮助您安全地浏览和编辑代码。工作区信任 (Workspace Trust) 功能可让您决定项目文件夹是应允许还是限制自动代码执行。

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

在容器中重新打开文件夹

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

此流程有几个例外情况：

点击最近的项目条目时。
如果尚未给予信任，使用 Open Folder in Container（在容器中打开文件夹） 命令将在窗口重新加载后询问信任。

附加到现有容器

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

Workspace trust prompt when attaching to container

在卷中克隆仓库

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

Workspace trust prompt when cloning in container volume

检查卷

检查卷将以受限模式 (Restricted Mode) 启动，您可以选择信任容器内的文件夹。

Docker 守护进程在远程运行

这意味着信任运行 Docker 守护进程的机器。没有额外的确认提示（仅包含上述本地/WSL 情况中列出的提示）。

创建 devcontainer.json 文件

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

从命令面板（F1）中选择 Dev Containers: Add Dev Container Configuration Files...（Dev Containers: 添加开发容器配置文件...） 命令将把所需文件添加为项目的起点，您可以根据需要进一步自定义这些文件。通过该命令，您可以根据文件夹内容从列表中选择预定义的容器配置、复用现有的 Dockerfile 或复用现有的 Docker Compose 文件。

Select a node Dev Container Template

您还可以手动创建 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 文件的更多信息，请参阅创建开发容器。

开发容器功能

开发容器“功能 (Features)”是自包含的、可共享的安装代码和开发容器配置单元。这个名称源于这样一种理念：引用其中一个功能，可以让您快速轻松地将更多工具、运行时或库“功能”添加到开发容器中，供您或您的协作者使用。

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

Dev container Features list drop down

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

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

直接在 devcontainer.json 中编辑 "features" 属性时，您将获得 IntelliSense 支持

Intellisense when modifying terraform Feature

Dev Containers: Configure Container Features（Dev Containers: 配置容器功能） 命令允许您更新现有配置。

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

“始终安装”的功能

类似于您可以在开发容器中将扩展设置为始终安装的方式，您可以使用 dev.containers.defaultFeatures 在 VS Code 中打开在 VS Code Insiders 中打开用户设置来设置您希望始终安装的功能

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

创建您自己的功能

创建和发布您自己的开发容器功能也很容易。发布的功能可以作为 OCI 制品 (OCI Artifacts) 存储和共享于任何支持的公共或私有容器注册表中。您可以在 containers.dev 上查看当前发布的功能列表。

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

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

请查看 feature/starter 仓库，了解如何使用开发容器 CLI 发布您自己的公共或私有功能的说明。

功能规范与分发

功能是开源 Development Containers Specification（开发容器规范）的关键部分。您可以查看有关功能工作原理的更多信息及其分发方式。

预构建开发容器镜像

我们建议使用所需的工具预构建镜像，而不是每次在开发容器中打开项目时都创建和构建容器镜像。使用预构建的镜像可以实现更快的容器启动、更简单的配置，并允许您锁定特定版本的工具以提高供应链安全性并避免潜在的中断。您可以使用诸如 GitHub Actions 之类的 DevOps 或持续集成 (CI) 服务安排构建，从而自动预构建镜像。

更好的是，预构建的镜像可以包含开发容器元数据，因此当您引用镜像时，设置将自动拉取过来。

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

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

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

继承元数据

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

当您使用 Dev Container CLI（或支持规范的其他实用工具，例如 GitHub Action 或 Azure DevOps 任务）进行预构建时，此元数据标签会自动添加，并且包含来自 devcontainer.json 以及任何引用的开发容器功能的设置。

这使您可以拥有一个用于预构建镜像的单独的、更复杂的 devcontainer.json，然后在的一个或多个仓库中使用一个极度简化版的 devcontainer.json。在创建容器时，镜像的内容将与这个简化的 devcontainer.json 内容合并（有关合并逻辑的信息，请参阅规范）。但最简单的是，您只需在 devcontainer.json 中直接引用镜像即可使设置生效

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

请注意，您也可以选择手动将元数据添加到镜像标签中。即使您没有使用 Dev Container CLI 进行构建，这些属性也会被获取（如果您使用了，也可以由 CLI 进行更新）。例如，考虑以下 Dockerfile 代码片段

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

检查卷

有时您可能会遇到这样一种情况：您正在使用一个命名的 Docker 卷，需要对其进行检查或进行更改。您可以使用 VS Code 操作这些内容，而无需创建或修改 devcontainer.json 文件——只需从命令面板（F1）中选择 Dev Containers: Explore a Volume in a Dev Container...（Dev Containers: 在开发容器中探索卷...）。

您还可以在远程资源管理器 (Remote Explorer) 中检查您的卷。确保在下拉菜单中选中了 Containers，然后您会看到一个 Dev Volumes（开发卷） 部分。您可以右键单击卷以检查其创建信息，例如卷是在何时创建的、克隆了什么仓库以及挂载点。您还可以在开发容器中对其进行探索。

Right-click dev volumes in Remote Explorer

如果您安装了 Container Tools 扩展，您可以右键单击容器资源管理器 (Container Explorer) 的 Volumes（卷） 部分中的卷，然后选择 Explore in a Development Container（在开发容器中探索）。

Explore in dev container in Container Tools context menu

管理扩展

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

如果您从扩展视图中安装扩展，它将自动安装在正确的位置。您可以根据类别分组判断扩展的安装位置。将有一个 Local - Installed（本地 - 已安装） 类别，还有一个针对您的容器的类别。

Workspace Extension Category

Local Extension Category

注意：如果您是扩展开发者，并且您的扩展无法正常工作或安装在错误的位置，请参阅支持远程开发了解详情。

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

Disabled Extensions w/Install Button

您还可以转到扩展视图，并使用 Local - Installed（本地 - 已安装） 标题栏右侧的云图标按钮选择 Install Local Extensions in Dev Container: {Name}（在开发容器中安装本地扩展: {Name}），从而将所有本地安装的扩展安装到开发容器中。这将显示一个下拉菜单，您可以在其中选择要在容器中安装哪些本地安装的扩展。

Install all extensions

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

将扩展添加到 devcontainer.json

虽然您可以手动编辑 devcontainer.json 文件以添加扩展 ID 列表，但您也可以在扩展视图中右键单击任何扩展并选择 Add to devcontainer.json（添加到 devcontainer.json）。

Add to devcontainer.json menu

排除扩展

如果基础镜像或功能配置了您不希望安装在开发容器中的扩展，您可以通过在扩展名前加上减号将其排除。例如

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

“始终安装”的扩展

如果有些扩展您希望在任何容器中都始终安装，您可以更新 dev.containers.defaultExtensions 在 VS Code 中打开在 VS Code Insiders 中打开用户设置。例如，如果您想安装 GitLens 和 Resource Monitor 扩展，您可以按如下方式指定它们的扩展 ID

"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" ]
}

将 "ui" 代替 "workspace" 会强制扩展在本地 UI/客户端侧运行。通常，这仅应用于测试，除非扩展文档中另有说明，因为它可能会破坏扩展。有关详细信息，请参阅关于首选扩展位置一节。

转发或发布端口

容器是隔离的环境，因此如果您想访问容器内部的服务器、服务或其他资源，您需要将端口“转发”或“发布”到您的主机。您可以将容器配置为始终公开这些端口，或者只是临时转发它们。

始终转发端口

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

"forwardPorts": [3000, 3001]

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

临时转发端口

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

Forward port input

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

如果您以后需要访问此信息，可以在远程资源管理器的 Forwarded Ports（已转发端口） 部分中找到它。

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

Restore forwarded ports setting

发布端口

Docker 具有在创建容器时“发布”端口的概念。发布的端口表现得非常像您向本地网络开放的端口。如果您的应用程序只接受来自 localhost 的调用，它将拒绝来自发布端口的连接，就像您的本地机器对网络调用所做的那样。另一方面，转发的端口对应用程序来说实际上看起来像 localhost。两者在不同的情况下都非常有用。

要发布端口，您可以

使用 appPort 属性：如果您在 devcontainer.json 中引用了镜像或 Dockerfile，则可以使用 appPort 属性将端口发布到主机。
```
"appPort": [ 3000, "8921:5000" ]
```
使用 Docker Compose 端口映射：可以轻松地将 ports 映射添加到您的 docker-compose.yml 文件中以发布其他端口。
```
ports:
- "3000"
- "8921:5000"
```

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

打开终端

从 VS Code 在容器中打开终端非常简单。在容器中打开文件夹后，您在 VS Code 中打开的任何终端窗口（终端 (Terminal) > 新建终端 (New Terminal)）都会自动在容器中运行，而不是在本地运行。

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

Using the code CLI

在容器中调试

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

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

容器特定设置

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

Container specific settings tab

默认的容器特定设置

您可以使用 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 时，该扩展会自动关闭您已连接的容器。您可以通过在 devcontainer.json 中添加 "shutdownAction": "none" 来更改此行为。

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

Containers Explorer screenshot

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

使用 dotfiles 仓库进行个性化配置

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

这样做的常见方法是将这些 dotfiles 存储在 GitHub 仓库中，然后使用实用工具来克隆和应用它们。Dev Containers 扩展内置了对在您自己的容器中使用这些文件的支持。如果您对这个概念感到陌生，可以查看现有的各种 dotfiles 引导仓库。

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

Settings for dotfiles

或者在 settings.json 中

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

从此以后，每当创建容器时，都将使用该 dotfiles 仓库。

已知限制

Dev Containers 限制

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

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

Docker 限制

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

容器工具扩展限制

如果您从 WSL、Remote - Tunnels 或 Remote - SSH 窗口使用 Container Tools 或 Kubernetes 扩展，则使用容器资源管理器或 Kubernetes 视图中的 Attach Visual Studio Code（附加 Visual Studio Code）上下文菜单操作将要求第二次从可用容器中进行选择。

扩展限制

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

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

高级容器配置

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

devcontainer.json 参考

这里有完整的 devcontainer.json 参考，您可以在其中查看文件架构，以帮助自定义开发容器并控制如何附加到正在运行的容器。

问题或反馈

请参阅提示和技巧或常见问题解答。
在 Stack Overflow 上搜索。
添加功能请求或报告问题。
创建 Dev Container 模板或功能 (Feature) 供他人使用。
审阅并提供关于 Development Containers Specification（开发容器规范）的反馈。
为我们的文档或 VS Code 本身做出贡献。
有关详细信息，请参阅我们的 CONTRIBUTING 指南。

疑难解答

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

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

Docker Desktop 运行在适用于 Linux 的 Windows 子系统 (WSL) 后端上
已启用增强型容器隔离 (ECI)

请查阅 issue #8278 了解潜在的变通解决方法。

下一步计划

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

7/29/2026