在容器内进行开发

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

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

Container Architecture

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

开发容器扩展支持两种主要的操作模式：

你可以将容器用作你的全时开发环境
你可以连接到正在运行的容器来检查它。

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

入门

注意：你可以在入门开发容器教程中快速学习如何开始使用开发容器。

系统要求

本地/远程主机

你可以通过以下几种方式将 Docker 与开发容器扩展结合使用，包括：

本地安装的 Docker。
在远程环境上安装的 Docker。
其他符合 Docker 标准的 CLI，无论安装在本地还是远程。
- 虽然其他 CLI 可能可用，但它们并未得到官方支持。请注意，连接到 Kubernetes 集群仅需要一个配置正确的kubectl CLI。

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

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

Windows: Docker Desktop 2.0+，适用于 Windows 10 Pro/Enterprise。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 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 任务栏图标，选择设置。勾选使用基于 WSL 2 的引擎，并在资源 > WSL 集成下验证你的发行版已启用。
3. 未在使用 WSL 2 后端时，右键单击 Docker 任务栏图标，选择设置，并在资源 > 文件共享中更新存放源代码的任何位置。请参阅技巧和窍门进行故障排除。
Linux:
1. 按照你发行版的Docker CE/EE 官方安装说明进行操作。如果你使用 Docker Compose，也请按照Docker Compose 的说明进行操作。
2. 使用终端运行：sudo usermod -aG docker $USER 将你的用户添加到 docker 组。
3. 退出并重新登录，以便更改生效。
安装Visual Studio Code或Visual Studio Code Insiders。
安装开发容器扩展。如果你打算在 VS Code 中使用其他远程扩展，可以选择安装Remote Development 扩展包。

使用 Git？

这里有两个技巧供你参考：

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

选择你的快速入门

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

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

快速入门：尝试开发容器

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

Select a sample from the list

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

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

本快速入门涵盖了如何为现有项目设置开发容器，以便使用文件系统上的现有源代码作为你的全时开发环境。请按照以下步骤操作：

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

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

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

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

你可以使用附加的特性自定义你的开发容器，你可以在下面阅读更多相关信息。

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

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

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

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

虽然使用这种方式将本地文件系统bind mount到容器中很方便，但在 Windows 和 macOS 上会产生一定的性能开销。你可以应用一些技术来提高磁盘性能，或者改为在容器中使用独立的容器卷打开仓库。

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

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

启用 WSL 2 引擎后，你可以选择以下任一方式：

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

快速入门的其余部分照常适用！你可以在WSL 扩展的文档中了解更多信息。

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

如果你使用 Linux 或 macOS SSH 主机，可以同时使用Remote - SSH和开发容器扩展。你甚至不需要在本地安装 Docker 客户端。

为此：

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

开发容器快速入门的其余部分照常适用。你可以在Remote - SSH 扩展的文档中了解更多信息。如果此模式不满足你的需求，你还可以参阅在远程 Docker 主机上进行开发文章以获取其他选项。

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

你可以同时使用Remote - Tunnels和开发容器扩展，以便在远程主机上的容器内部打开一个文件夹。你甚至不需要在本地安装 Docker 客户端。这类似于上面的 SSH 主机场景，但使用的是 Remote - Tunnels。

为此：

按照 Remote - Tunnels 扩展的入门说明进行操作。
在你的隧道主机上安装 Docker。你无需在本地安装 Docker。
按照 Remote - Tunnels 扩展的步骤连接到隧道主机并在那里打开一个文件夹。
从命令面板 (F1, ⇧⌘P (Windows, Linux Ctrl+Shift+P)) 运行 Dev Containers: Reopen in Container（开发容器：在容器中重新打开）命令。

开发容器快速入门的其余部分照常适用。你可以在Remote - Tunnels 扩展的文档中了解更多信息。如果此模式不满足你的需求，你还可以参阅在远程 Docker 主机上进行开发文章以获取其他选项。

在容器中打开现有工作区

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

你可以选择以下任一方式：

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

连接后，如果 .devcontainer 文件夹尚未显示，你可能希望将其添加到工作区中，以便轻松编辑其内容。

另请注意，虽然你无法在同一个 VS Code 窗口中为同一个工作区使用多个容器，但你可以在不同的窗口中同时使用多个 Docker Compose 管理的容器。

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

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

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

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

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

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

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

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

如果你在步骤 2 中粘贴了 GitHub pull request 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 非常重视安全性，并希望帮助你安全地浏览和编辑代码，无论其来源或原始作者是谁。“工作区信任”功能允许你决定你的项目文件夹是应允许还是限制自动代码执行。

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

在容器中重新打开文件夹

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

此流程有几个例外情况：

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

连接到现有容器

连接到现有容器时，系统会要求你确认连接意味着你信任该容器。这只需确认一次。

Workspace trust prompt when attaching to container

在卷中克隆仓库

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

Workspace trust prompt when cloning in container volume

检查卷

检查卷时以受限模式启动，你可以在容器内部信任该文件夹。

远程运行的 Docker 守护进程

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

创建 devcontainer.json 文件

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

从命令面板 (F1) 选择 Dev Containers: Add Dev Container Configuration Files...（开发容器：添加开发容器配置文件...）命令会将所需文件添加到你的项目中作为起点，你可以根据需要进一步自定义。该命令允许你根据文件夹内容从列表中选择预定义的容器配置，重用现有的 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 文件的信息，请参阅创建开发容器。

开发容器特性

开发容器“特性”是独立、可共享的安装代码和开发容器配置单元。这个名称源于这样一个想法：引用其中一个特性可以让你快速轻松地向开发容器添加更多工具、运行时或库“特性”，供你或你的协作者使用。

使用 Dev Containers: Add Dev Container Configuration Files（开发容器：添加开发容器配置文件）时，会显示一个脚本列表，用于自定义现有的开发容器配置，例如安装 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 when modifying terraform Feature

Dev Containers: Configure Container Features（开发容器：配置容器特性）命令允许你更新现有配置。

VS Code UI 中显示的特性现在来自一个中心索引，你也可以为其贡献。请参阅开发容器规范网站查看当前列表，并了解如何发布和分发特性。

“始终安装”的特性

类似于你如何设置扩展始终安装在你的开发容器中，你可以使用 dev.containers.defaultFeatures 用户设置来设置你始终希望安装的特性：

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

创建自己的特性

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

一个特性是一个独立的实体，位于一个文件夹中，至少包含 devcontainer-feature.json 和 install.sh 入口点脚本：

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

查看feature/starter仓库，获取使用 dev container CLI 发布你自己的公共或私有特性的说明。

特性规范和分发

特性是开源开发容器规范的关键组成部分。你可以查阅更多关于特性如何工作及其分发的信息。

预构建开发容器镜像

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

更好的是，预构建的镜像可以包含开发容器元数据，因此当你引用一个镜像时，设置将自动引入。

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

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

有关预构建镜像的更多信息，请参阅dev container CLI 文章中的预构建部分。

继承元数据

你可以通过镜像标签将开发容器配置和特性元数据包含在预构建的镜像中。这使得镜像具有自包含性，因为当引用镜像时，这些设置会自动被识别，无论是在引用的 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，这些属性也可以由 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...（开发容器：在开发容器中探索卷...）命令。

你还可以在远程资源管理器中检查你的卷。确保在下拉列表中选择了“容器”，然后你会看到一个“开发卷”部分。你可以右键单击一个卷来检查其创建信息，例如卷何时创建、克隆了哪个仓库以及挂载点。你也可以在开发容器中探索它。

Right-click dev volumes in Remote Explorer

如果你安装了容器工具扩展，你可以在容器资源管理器的“卷”部分右键单击一个卷，并选择 Explore in a Development Container（在开发容器中探索）。

Explore in dev container in Container Tools context menu

管理扩展

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

如果你从“扩展”视图安装扩展，它将自动安装在正确的位置。你可以根据类别分组判断扩展安装在哪里。会有一个“本地 - 已安装”类别，以及一个针对你的容器的类别。

Workspace Extension Category

Local Extension Category

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

实际上需要在远程运行的本地扩展在“本地 - 已安装”类别中将显示为禁用。选择安装以在你的远程主机上安装扩展。

Disabled Extensions w/Install Button

你还可以通过转到“扩展”视图，并在“本地 - 已安装”标题栏右侧使用云按钮选择 Install Local Extensions in Dev Container: {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 用户设置。例如，如果你想安装GitLens和Resource Monitor扩展，你可以按如下方式指定它们的扩展 ID：

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

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

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

例如，以下设置将强制容器工具扩展在本地运行，而Remote - SSH: Editing Configuration Files（远程 - SSH：编辑配置文件）扩展在远程运行，而不是使用它们的默认设置：

"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

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

如果你以后需要访问这些信息，可以在远程资源管理器的已转发端口部分找到。

如果你希望 VS Code 记住你转发过的任何端口，请在设置编辑器 (⌘, (Windows, Linux Ctrl+,)) 中勾选 Remote: Restore Forwarded Ports（远程：恢复转发端口），或在 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（开发容器：重建容器）命令来完成此操作。

打开终端

从 VS Code 打开容器中的终端很简单。在容器中打开文件夹后，你在 VS Code 中打开的任何终端窗口（终端 > 新建终端）都将自动在容器中运行，而不是在本地运行。

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

Using the code CLI

在容器中调试

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

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

容器特定的设置

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

Container specific settings tab

默认容器特定的设置

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

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

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

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

管理容器

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

虽然你可以使用命令行管理容器，但你也可以使用远程资源管理器。要停止容器，从下拉列表（如果存在）中选择“容器”，右键单击正在运行的容器，然后选择 Stop Container（停止容器）。你也可以启动已退出的容器、移除容器和移除最近文件夹。从详情视图中，你可以转发端口并在浏览器中打开已转发的端口。

Containers Explorer screenshot

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

使用 dotfile 仓库进行个性化设置

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

一种常见的方法是将这些 dotfiles 存储在 GitHub 仓库中，然后使用一个工具克隆并应用它们。开发容器扩展内置支持在你的容器中使用这些 dotfiles。如果你对这个概念不熟悉，可以查看现有的各种dotfiles bootstrap 仓库。

要使用它，请将你的 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 仓库。

已知限制

开发容器限制

不支持 Windows 容器镜像。
多根工作区中的所有根/文件夹将在同一个容器中打开，无论较低级别是否存在配置文件。
不支持非官方的 Ubuntu Docker snap Linux 包。请按照你发行版的Docker 官方安装说明进行操作。
不支持 Windows 上的 Docker Toolbox。
如果你使用 SSH 克隆 Git 仓库，并且你的 SSH 密钥有密码，在远程运行时 VS Code 的拉取和同步功能可能会卡住。请使用没有密码的 SSH 密钥，或使用 HTTPS 克隆，或从命令行运行 git push 来解决此问题。
容器内不会重用本地代理设置，这可能会导致扩展无法工作，除非配置了相应的代理信息（例如，设置带有相应代理信息的全局 HTTP_PROXY 或 HTTPS_PROXY 环境变量）。
当 ssh-agent 在 Windows 上运行时版本 <= 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 限制

请参阅 Windows 或 Mac 的 Docker 疑难解答指南，或查阅Docker 支持资源获取更多信息。

容器工具扩展限制

如果你在 WSL、Remote - Tunnels 或 Remote - SSH 窗口中使用容器工具或 Kubernetes 扩展，在容器资源管理器或 Kubernetes 视图中使用 Attach Visual Studio Code（连接 Visual Studio Code）上下文菜单操作时，会再次要求你从可用容器中进行选择。

扩展限制

目前，大多数扩展在开发容器内无需修改即可工作。但是，在某些情况下，某些功能可能需要更改。如果你遇到扩展问题，请参阅此处获取常见问题和解决方案的摘要，你可以在报告问题时向扩展作者提及。

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

高级容器配置

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

devcontainer.json 参考

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

问题或反馈

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

故障排除

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

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

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

查看issue #8278 以获取可能的解决方法。

下一步

连接到正在运行的容器 - 连接到已在运行的 Docker 容器。
创建开发容器 - 为你的工作环境创建一个自定义容器。
高级容器 - 查找高级容器场景的解决方案。
devcontainer.json 参考 - 查看 devcontainer.json schema。

06/12/2025