创建开发容器

Name: Visual Studio Code
Author: Microsoft

Visual Studio Code 开发容器扩展允许您使用 Docker 容器作为功能齐全的开发环境。它允许您在容器内打开任何文件夹或存储库，并利用 Visual Studio Code 的全部功能。项目中的 devcontainer.json 文件会告诉 VS Code 如何访问（或创建）具有明确定义的工具和运行时堆栈的开发容器。此容器可用于运行应用程序或提供使用代码库所需的单独工具、库或运行时。

创建开发容器的路径

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

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

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

注意：开发容器扩展有一个开发容器：添加开发容器配置文件...命令，可让您从列表中选择预定义的容器配置。如果您希望立即拥有一个完整的开发容器，而不是逐步构建 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，您的开发容器就可以正常工作，您可以连接到它并开始在其中进行开发。使用开发容器：在容器中重新打开命令试用一下

Quick pick with list of Dev Containers commands

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

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" 属性从预定义的功能集，甚至是您自己的功能安装工具和语言。

例如，您可以使用以下命令安装最新版本的 Azure CLI

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

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

重建

编辑 .devcontainer 文件夹的内容时，您需要重建以使更改生效。使用开发容器：重建容器命令来更新您的容器。

然而，如果**重建**容器，您将不得不**重新安装**您手动安装的任何东西。为了避免这个问题，您可以使用 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"

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

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

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

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

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

Dockerfile

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

{
  "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，让我们看看编辑容器配置文件的通用过程。

完整的配置编辑循环

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

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

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 的起点

现有 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 文件。

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

# 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: 重建容器 命令，才能使对 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 repo”以找到该设置

Repository container folders setting

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

📁 github.com
    📁 devcontainers
        📁 templates
           📁 .devcontainer

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

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

后续步骤

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

12/11/2024