创建开发容器

Name: Visual Studio Code
Author: Microsoft

Visual Studio Code Dev Containers（开发容器）扩展允许您使用 Docker 容器作为功能完备的开发环境。它让您可以在容器内打开任何文件夹或仓库，并充分利用 Visual Studio Code 的所有功能。项目中的 devcontainer.json 文件会告知 VS Code 如何访问（或创建）一个定义明确的工具和运行时栈的开发容器。该容器既可用于运行应用程序，也可用于提供处理代码库所需的独立工具、库或运行时。

创建开发容器的路径

在本文档中，我们将介绍在 VS Code 中创建开发（dev）容器的步骤

创建 devcontainer.json，它描述了 VS Code 应如何启动容器以及连接后应执行的操作。
通过使用 Dockerfile 对开发容器进行更改并持久化这些更改（例如安装新软件）。
通过 Docker Compose 配置多个容器。
在进行更改时，构建您的开发容器以确保更改生效。

完成上述任何步骤后，您将拥有一个功能齐全的开发容器，您可以继续本教程的下一步来添加更多功能，或者停止操作并开始在您当前的开发环境中工作。

注意：Dev Containers 扩展提供了一个 Dev Containers: Add Dev Container Configuration Files...（开发容器：添加开发容器配置文件...）命令，让您可以从列表中选择预定义的容器配置。如果您希望立即获得一个完整的开发容器，而不是逐步构建 devcontainer.json 和 Dockerfile，可以直接跳到自动化创建开发容器。

创建 devcontainer.json 文件

VS Code 的容器配置存储在 devcontainer.json 文件中。该文件类似于用于调试配置的 launch.json 文件，但它用于启动（或附加到）您的开发容器。开发容器配置要么位于 .devcontainer/devcontainer.json 中，要么作为项目根目录下的 .devcontainer.json 文件（注意点前缀）存储。

您可以将镜像用作 devcontainer.json 的起点。镜像就像一个预装了各种工具和操作系统的迷你硬盘驱动器。您可以从容器注册表（存储镜像的仓库集合）中拉取镜像。这是一个简单的 devcontainer.json 示例，它使用了预构建的 TypeScript 和 Node.js VS Code 开发容器镜像

{
  "image": "mcr.microsoft.com/devcontainers/typescript-node:0-18"
}

您可以修改配置以执行以下操作：

在容器中安装 Git 等其他工具。
自动安装扩展。
转发或发布其他端口。
设置运行时参数。
复用或扩展您现有的 Docker Compose 设置。
添加更多高级容器配置。

对于本示例，如果您想在容器中安装 Code Spell Checker 扩展并自动转发 3000 端口，您的 devcontainer.json 将如下所示：

{
  "image": "mcr.microsoft.com/devcontainers/typescript-node",

  "customizations": {
    "vscode": {
      "extensions": ["streetsidesoftware.code-spell-checker"]
    }
  },
  "forwardPorts": [3000]
}

注意：基于基础镜像的内容，额外的配置将自动添加到容器中。例如，我们在上面添加了 streetsidesoftware.code-spell-checker 扩展，容器也将包含 "dbaeumer.vscode-eslint"，因为它是 mcr.microsoft.com/devcontainers/typescript-node 的一部分。当使用 devcontainer.json 进行预构建时，这种情况会自动发生，您可以在预构建部分阅读更多相关信息。

使用上述 devcontainer.json，您的开发容器即可使用，您可以连接到它并开始开发。尝试使用 Dev Containers: Reopen in Container（开发容器：在容器中重新打开）命令进行测试。

Quick pick with list of Dev Containers commands

运行此命令后，当 VS Code 重启时，您现在处于一个 Node.js 和 TypeScript 开发容器中，3000 端口已转发，并且安装了 ESLint 扩展。连接后，注意状态栏左侧的绿色远程指示器，它显示您已连接到开发容器。

VS Code instance connected to dev container

其他开发容器场景

通过 devcontainer.json 文件，您可以：

启动一个独立容器，以隔离您的工具链或加快设置速度。
使用由镜像、Dockerfile 或 Docker Compose 定义的容器化应用程序进行工作。
在开发容器内使用 Docker 或 Kubernetes 来构建和部署您的应用。

如果 devcontainer.json 支持的工作流程不能满足您的需求，您也可以改为附加到已经运行的容器。

提示：想要使用远程 Docker 主机？请参阅在远程 Docker 主机上开发文章以获取有关设置的详细信息。

安装其他软件

您可能需要在开发容器中安装额外的软件。一旦 VS Code 连接到容器，您可以打开 VS Code 终端并针对容器内的操作系统执行任何命令。这允许您从 Linux 容器内部安装新的命令行实用程序并启动数据库或应用程序服务。

大多数容器镜像基于 Debian 或 Ubuntu，其中使用 apt 或 apt-get 命令安装新包。您可以在 Ubuntu 文档中了解更多关于该命令的信息。Alpine 镜像包含类似的 apk 命令，而 CentOS / RHEL / Oracle SE / Fedora 镜像使用 yum 或最近使用的 dnf。

您要安装的软件的文档通常会提供具体的说明，但如果您以 root 用户身份在容器中运行，则可能不需要在命令前加 sudo。

例如

# If running as root
apt-get update
apt-get install <package>

如果您以 root 用户身份运行，只要容器中配置了 sudo，就可以安装软件。所有预定义的容器都已设置好 sudo，但向容器添加非 root 用户文章可以帮助您为您自己的容器进行此设置。无论如何，如果您安装并配置了 sudo，您可以在以任何用户（包括 root）身份运行时使用它。

# If sudo is installed and configured
sudo apt-get update
sudo apt-get install <package>

假设您想安装 Git。您可以在 VS Code 的集成终端中运行以下命令：

# If sudo is installed and configured
sudo apt-get update
# Install Git
sudo apt-get install git

您也可以在 devcontainer.json 中使用 "features" 属性，从预定义的一组功能 (Features) 或您自己的集合中安装工具和语言。

例如，您可以通过以下方式安装最新版本的 Azure CLI：

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

有关详细信息，请参阅开发容器功能规范。

重建

编辑 .devcontainer 文件夹的内容时，需要进行重建以使更改生效。使用 Dev Containers: Rebuild Container（开发容器：重建容器）命令来更新您的容器。

但是，如果您重建容器，则必须重新安装您手动安装的任何内容。为避免此问题，您可以在 devcontainer.json 中使用 postCreateCommand 属性或自定义 Dockerfile。

自定义 Dockerfile 将受益于 Docker 的构建缓存，从而比 postCreateCommand 更快地重建。但是，Dockerfile 在开发容器创建和工作区文件夹挂载之前运行，因此无法访问工作区文件夹中的文件。Dockerfile 最适合安装独立于工作区文件的包和工具。

postCreateCommand 操作在容器创建后运行，因此您还可以使用此属性运行 npm install 等命令，或者在您的源代码树中执行 shell 脚本（如果您已挂载它）。

"postCreateCommand": "bash scripts/install-dependencies.sh"

您还可以使用交互式 bash shell，以便加载您的 .bashrc，从而自动为您环境定制 shell：

"postCreateCommand": "bash -i scripts/install-dependencies.sh"

像 NVM 这样的工具如果不使用 -i 将 shell 置于交互模式则无法工作。

"postCreateCommand": "bash -i -c 'nvm install --lts'"

命令需要退出，否则容器将无法启动。例如，如果您将应用程序启动添加到 postCreateCommand，则该命令不会退出。

还有一个 postStartCommand，它在容器每次启动时执行。参数的行为与 postCreateCommand 完全相同，但命令在启动时执行，而不是在创建时。

比起直接在 devcontainer.json 中引用镜像，或通过 postCreateCommand 或 postStartCommand 安装软件，更有效的方法是使用 Dockerfile。

Dockerfile

Dockerfile 也将位于 .devcontainer 文件夹中。您可以将 devcontainer.json 中的 image 属性替换为 dockerfile：

{
  "build": { "dockerfile": "Dockerfile" },

  "customizations": {
    "vscode": {
      "extensions": ["dbaeumer.vscode-eslint"]
    }
  },

  "forwardPorts": [3000]
}

当您进行更改（如安装新软件）时，Dockerfile 中所做的更改即使在重建开发容器后也会保持不变。

在 Dockerfile 中，使用 FROM 指定镜像，并使用 RUN 指令安装任何软件。您可以使用 && 将多个命令串联起来。

FROM mcr.microsoft.com/devcontainers/javascript-node:0-18
RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \
    && apt-get -y install git

注意：DEBIAN_FRONTEND 导出可避免您在继续使用容器时出现警告。

自动化创建开发容器

与其手动创建 .devcontainer，不如从命令面板 (F1) 中选择 Dev Containers: Add Dev Container Configuration Files... 命令，这将添加必要的文件到您的项目中作为起点，您可以根据需要进一步定制这些文件。

该命令允许您根据文件夹的内容从列表中选择预定义的容器配置。

Add a dev container config

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

使用 Dev Containers: Add Dev Container Configuration Files... 完成后，系统将显示可用功能的列表，这些功能是您可以轻松放入开发容器中的工具和语言。Dev Containers: Configure Container Features 允许您更新现有配置。

Dev container features in Command Palette

您也可以复用现有的 Dockerfile。

Select Dockerfile

现在您已经有了 devcontainer.json 和 Dockerfile，让我们看看编辑容器配置文件的通用流程。

完整配置编辑循环

编辑容器配置很容易。由于重建容器会将容器“重置”为其初始内容（本地源代码除外），VS Code 不会在您编辑容器配置文件（devcontainer.json、Dockerfile 和 docker-compose.yml）时自动重建。相反，有几个命令可以用来使编辑配置更容易。

以下是使用这些命令的典型编辑循环：

Container edit loop illustration

首先在命令面板 (F1) 中选择 Dev Containers: Add Dev Container Configuration Files...。
根据需要编辑 .devcontainer 文件夹的内容。
尝试使用 Dev Containers: Reopen in Container 进行测试。
如果看到错误，请在出现的对话框中选择 Open Folder Locally（本地打开文件夹）。
窗口重新加载后，构建日志的副本将出现在控制台中，以便您调查问题。根据需要编辑 .devcontainer 文件夹的内容。（如果关闭了日志，您也可以使用 Dev Containers: Show Container Log 命令再次查看它。）
运行 Dev Containers: Rebuild and Reopen in Container，如果需要，跳转到第 4 步。

如果您已经构建成功，仍然可以在连接到容器时根据需要编辑 .devcontainer 文件夹的内容，然后在命令面板 (F1) 中选择 Dev Containers: Rebuild Container，以便更改生效。

当使用 Dev Containers: Clone Repository in Container Volume 命令时，您也可以对容器进行迭代。

首先在命令面板 (F1) 中使用 Dev Containers: Clone Repository in Container Volume。如果您输入的仓库中没有 devcontainer.json，系统会要求您选择一个起点。
根据需要编辑 .devcontainer 文件夹的内容。
尝试使用 Dev Containers: Rebuild Container。
如果看到错误，请在出现的对话框中选择 Open in Recovery Container（在恢复容器中打开）。
在此“恢复容器”中根据需要编辑 .devcontainer 文件夹的内容。
使用 Dev Containers: Reopen in Container，如果仍然遇到问题，跳转到第 4 步。

使用 Docker Compose

在某些情况下，单容器环境是不够的。假设您想向配置中添加另一个复杂组件，例如数据库。您可以尝试直接将其添加到 Dockerfile，或者通过额外容器添加它。幸运的是，开发容器支持 Docker Compose 管理的多容器配置。

您可以选择：

使用现有的、未修改的 docker-compose.yml 中定义的服务。
创建一个新的 docker-compose.yml（或复制现有的）以开发服务。
扩展您现有的 Docker Compose 配置来开发服务。
使用多个 VS Code 窗口同时处理多个由 Docker Compose 定义的服务。

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

VS Code 可以配置为自动启动 Docker Compose 文件中特定服务所需的任何容器。如果您已经使用命令行启动了已配置的容器，VS Code 将附加到您指定的运行服务。这为您的多容器工作流程提供了与上述 Docker 镜像和 Dockerfile 工作流程相同的快速设置优势，同时如果您愿意，仍然允许您使用命令行。

要快速入门，请在 VS Code 中打开您要处理的文件夹，并在命令面板 (F1) 中运行 Dev Containers: Add Dev Container Configuration Files... 命令。

系统将提示您从我们的第一方和社区索引中选择一个预定义的容器配置，该列表是基于您的文件夹内容过滤和排序的。在 VS Code UI 中，您可以选择以下模板之一作为 Docker Compose 的起点：

Existing Docker Compose（现有 Docker Compose） - 包含一组文件，您可以将其放入现有项目中，这些文件将复用项目根目录中的 docker-compose.yml 文件。
Node.js & MongoDB - 一个连接到不同容器中 MongoDB 数据库的 Node.js 容器。
Python & PostgreSQL - 一个连接到不同容器中 PostgreSQL 的 Python 容器。
Docker-Outside-of-Docker Compose - 包含 Docker CLI，并演示了如何通过挂载 Docker Unix 套接字从开发容器内部访问本地 Docker 安装。

选择后，VS Code 会将适当的 .devcontainer/devcontainer.json（或 .devcontainer.json）文件添加到文件夹中。

您也可以手动创建配置。要复用未修改的 Docker Compose 文件，可以在 .devcontainer/devcontainer.json 中使用 dockerComposeFile 和 service 属性。

例如

{
  "name": "[Optional] Your project name here",
  "dockerComposeFile": "../docker-compose.yml",
  "service": "the-name-of-the-service-you-want-to-work-with-in-vscode",
  "workspaceFolder": "/default/workspace/path/in/container/to/open",
  "shutdownAction": "stopCompose"
}

有关 workspaceFolder 和 shutdownAction 等其他可用属性的信息，请参阅 devcontainer.json 参考。

将 .devcontainer/devcontainer.json 文件添加到文件夹后，从命令面板 (F1) 运行 Dev Containers: Reopen in Container（或者如果您尚未在容器中，则为 Dev Containers: Open Folder in Container...）。

如果容器尚未运行，在本示例中，VS Code 将调用 docker-compose -f ../docker-compose.yml up。service 属性表示 VS Code 应连接到 Docker Compose 文件中的哪个服务，而不是应该启动哪个服务。如果您手动启动了它们，VS Code 将附加到您指定的服务。

您也可以创建 Docker Compose 文件的开发副本。例如，如果您有 .devcontainer/docker-compose.devcontainer.yml，只需更改 devcontainer.json 中的以下行：

"dockerComposeFile": "docker-compose.devcontainer.yml"

然而，更好的方法通常是避免复制 Docker Compose 文件，而是通过另一个文件对其进行扩展。我们将在下一节中介绍扩展 Docker Compose 文件。

为了避免如果默认容器命令失败或退出时容器关闭，您可以按如下方式修改 Docker Compose 文件中 devcontainer.json 指定的服务：

# Overrides default command so things don't shut down after the process ends.
command: /bin/sh -c "while sleep 1000; do :; done"

如果尚未这样做，您可以使用 Docker Compose 文件中的卷列表将您的本地源代码“绑定挂载”到容器中。

例如

volumes:
  # Mounts the project folder to '/workspace'. The target path inside the container
  # should match what your application expects. In this case, the compose file is
  # in a sub-folder, so you will mount '..'. You would then reference this path as the
  # 'workspaceFolder' in '.devcontainer/devcontainer.json' so VS Code starts here.
  - ..:/workspace:cached

但是，在 Linux 上使用绑定挂载时，您可能需要设置并指定一个非 root 用户，否则您创建的任何文件都将归 root 所有。有关详细信息，请参阅向开发容器添加非 root 用户。要让 VS Code 以其他用户身份运行，请将此添加到 devcontainer.json：

"remoteUser": "your-user-name-here"

如果您希望所有进程都以其他用户身份运行，请将其添加到 Docker Compose 文件中的相应服务：

user: your-user-name-here

如果您没有为开发创建自定义 Dockerfile，则可能需要安装额外的开发工具（如 curl）到服务容器内。虽然这不如将这些工具添加到容器镜像中高效，但您也可以为此使用 postCreateCommand 属性。

有关安装软件的详细信息，请参阅安装其他软件，有关 postCreateCommand 属性的更多信息，请参阅 devcontainer.json 参考。

如果您的应用程序是使用 C++、Go、Rust 或其他使用基于 ptrace 的调试器的语言构建的，则还需要在 Docker Compose 文件中添加以下设置：

# Required for ptrace-based debuggers like C++, Go, and Rust
cap_add:
- SYS_PTRACE
security_opt:
- seccomp:unconfined

首次创建容器后，您需要运行 Dev Containers: Rebuild Container 命令，以使对 devcontainer.json、Docker Compose 文件或相关 Dockerfile 的更新生效。

在 Docker Compose 中使用 localhost

您可以按照 Docker 文档所述将其他服务添加到您的 docker-compose.yml 文件中。但是，如果您希望此服务中运行的任何内容在容器的 localhost 上可用，或者希望在本地转发该服务，请确保将此行添加到服务配置中：

# Runs the service on the same network as the database container, allows "forwardPorts" in devcontainer.json function.
network_mode: service:db

您可以在 Node.js 和 MongoDB 示例开发容器中看到 network_mode: service:db 的示例。

扩展 Docker Compose 文件以进行开发

引用现有的部署/非开发环境专用的 docker-compose.yml 有一些潜在的缺点。

例如

如果容器的入口点关闭，Docker Compose 将关闭该容器。这对于您正在进行调试并且需要反复重启应用程序的情况来说是有问题的。
您可能没有将本地文件系统映射到容器中，或者没有向其他资源（如数据库）开放端口以便访问。
您可能希望将本地 .ssh 文件夹的内容复制到容器中，或者设置上述使用 Docker Compose 中描述的 ptrace 选项。

您可以通过使用多个 docker-compose.yml 文件来覆盖或补充您的主文件，从而扩展整个 Docker Compose 配置，从而解决这些问题。

例如，考虑这个额外的 .devcontainer/docker-compose.extend.yml 文件：

version: '3'
services:
  your-service-name-here:
    volumes:
      # Mounts the project folder to '/workspace'. While this file is in .devcontainer,
      # mounts are relative to the first file in the list, which is a level up.
      - .:/workspace:cached

    # [Optional] Required for ptrace-based debuggers like C++, Go, and Rust
    cap_add:
      - SYS_PTRACE
    security_opt:
      - seccomp:unconfined

    # Overrides default command so things don't shut down after the process ends.
    command: /bin/sh -c "while sleep 1000; do :; done"

该文件可以根据需要提供其他设置，例如端口映射。要使用它，请按特定顺序引用您的原始 docker-compose.yml 文件以及 .devcontainer/docker-compose.extend.yml：

{
  "name": "[Optional] Your project name here",

  // The order of the files is important since later files override previous ones
  "dockerComposeFile": ["../docker-compose.yml", "docker-compose.extend.yml"],

  "service": "your-service-name-here",
  "workspaceFolder": "/workspace",
  "shutdownAction": "stopCompose"
}

这样，VS Code 在启动任何容器时将自动使用这两个文件。您也可以按照以下方式从命令行自行启动它们：

docker-compose -f docker-compose.yml -f .devcontainer/docker-compose.extend.yml up

虽然 postCreateCommand 属性允许您在容器内安装其他工具，但在某些情况下，您可能希望拥有一个特定的开发用 Dockerfile。您也可以使用相同的方法引用自定义的 Dockerfile，而无需修改现有的 Docker Compose 文件。例如，您可以按如下方式更新 .devcontainer/docker-compose.extend.yml：

version: '3'
services:
  your-service-name-here:
      # Note that the path of the Dockerfile and context is relative to the *primary*
      # docker-compose.yml file (the first in the devcontainer.json "dockerComposeFile"
      # array). The sample below assumes your primary file is in the root of your project.
      build:
        context: .
        dockerfile: .devcontainer/Dockerfile
      volumes:
        - .:/workspace:cached
      command: /bin/sh -c "while sleep 1000; do :; done"

恭喜！您现在已在 Visual Studio Code 中配置了开发容器。继续阅读以了解如何与团队成员和不同项目共享容器配置。

将配置文件添加到仓库中

通过将 devcontainer.json 文件添加到源代码管理中，您可以轻松共享为您项目定制的开发容器模板。通过在仓库中包含这些文件，任何在 VS Code 中打开您仓库本地副本的人，只要安装了 Dev Containers 扩展，都会自动收到提示，要求在容器中重新打开该文件夹。

Dev container configuration file reopen notification

除了让团队使用一致的环境和工具链带来的优势外，这还使新贡献者或团队成员能够更快地提高工作效率。首次贡献者将需要更少的指导，并且遇到与环境设置相关的问题更少。

添加“在开发容器中打开”徽章

您还可以在仓库中添加徽章或链接，以便用户可以轻松地在开发容器中打开您的项目。它会在必要时安装 Dev Containers 扩展，将仓库克隆到容器卷中，并启动开发容器。

例如，打开 https://github.com/microsoft/vscode-remote-try-java 的徽章看起来像这样：

[![Open in Dev Containers](https://img.shields.io/static/v1?label=Dev%20Containers&message=Open&color=blue)](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/microsoft/vscode-remote-try-java)

您也可以直接包含一个 open in dev container 链接：

If you already have VS Code and Docker installed, you can click the badge above or [here](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/microsoft/vscode-remote-try-java) to get started. Clicking these links will cause VS Code to automatically install the Dev Containers extension if needed, clone the source code into a container volume, and spin up a dev container for use.

替代方案：仓库配置文件夹

在某些情况下，您可能希望为不是您控制的仓库创建配置，或者您不希望配置包含在仓库本身中。要处理这种情况，您可以配置本地文件系统上的一个位置来存储配置，这些配置将根据仓库自动被识别。

首先，使用您想要用于存储仓库容器配置文件的本地文件夹更新 Dev > Containers: Repository Configuration Paths 用户设置。

在设置编辑器中，您可以搜索 'dev containers repo' 来找到该设置。

Repository container folders setting

接下来，将您的 .devcontainer/devcontainer.json（及相关文件）放在镜像远程仓库位置的子文件夹中。例如，如果您想为 github.com/devcontainers/templates 创建配置，您将创建以下文件夹结构：

📁 github.com
    📁 devcontainers
        📁 templates
           📁 .devcontainer

放置后，使用任何 Dev Containers 命令时都会自动拾取该配置。进入容器后，您还可以从命令面板 (F1) 中选择 Dev Containers: Open Container Configuration File 来打开相关的 devcontainer.json 文件并进行进一步编辑。

用于查找配置的路径派生自 git remote -v 的输出。如果您在尝试在容器中重新打开文件夹时未找到配置，请查看命令面板 (F1) 中的 Dev Containers: Show Container Log 日志，以获取已检查的路径列表。

后续步骤

附加到正在运行的容器 - 附加到已经运行的 Docker 容器。
高级容器 - 查找高级容器场景的解决方案。
devcontainer.json 参考 - 查看 devcontainer.json 模式。

4/8/2026