创建开发容器

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: 添加 Dev Container 配置文件...命令，允许您从列表中选择一个预定义的容器配置。如果您更喜欢立即拥有一个完整的开发容器，而不是逐步构建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 开发容器镜像:

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

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

在容器中安装额外的工具，如Git。
自动安装扩展。
发布或出版更多端口。
设置运行时参数。
重用或扩展您现有的Docker Compose设置.
添加更多高级容器配置.

在这个例子中，如果你希望将Code Spell Checker扩展安装到你的容器中并自动转发3000端口，你的devcontainer.json将会看起来像：

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

  "定制": {
    "vscode": {
      "扩展": ["streetsidesoftware.code-spell-checker"]
    }
  },
  "转发端口": [3000]
}

注意： 额外的配置将根据基础镜像中的内容添加到容器中。例如，我们添加了街道边软件.代码拼写检查器扩展部分上，并且容器也将包括"dbaeumer.vscode-eslint" 作为那是 mcr.microsoft.com/devcontainers/typescript-node当使用devcontainer.json进行预构建时，这会自动发生，您可以在预构建部分了解更多。

以上devcontainer.json，你的开发容器已经可以使用，你可以连接并开始在其中进行开发。尝试使用开发容器：在容器中重新打开命令：

快速选择与开发容器命令列表

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

VS Code 实例连接到开发容器

附加的开发容器场景

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

启动一个独立的容器来隔离你的工具链或加快设置。
与由图像定义的容器部署的应用程序Dockerfile或Docker Compose一起工作。
使用Docker或Kubernetes 从开发容器内部构建和部署您的应用程序。

如果devcontainer.json支持的工作流程不符合您的需求，您也可以附加到已运行的容器上。

提示： 想要使用远程Docker主机吗？请参阅在远程Docker主机上开发文章了解详细设置。

安装额外的软件

您可能希望在开发容器中安装额外的软件。一旦 VS Code 连接到容器，您可以在 VS Code 终端中执行任何针对容器内操作系统命令。这使您能够在 Linux 容器内安装新的命令行工具并启动数据库或应用服务。

大多数容器镜像基于Debian或Ubuntu，其中的公寓或apt-get command 用于安装新包。您可以在 Ubuntu 的文档中了解更多关于该命令的信息。 Alpine 镜像包含一个类似的安卓应用安装包 命令在 CentOS / RHEL / Oracle SE / Fedora 镜像中使用 yum 或最近 地下城与勇士输入：.

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

例如：

# 如果以 root 用户运行
apt-get 更新
apt-get 安装 <包>

如果你以 root 用户身份运行，只要...你就可以安装软件。超级用户权限在您的容器中进行了配置。所有预定义的容器都有超级用户权限 设置，但将非根用户添加到容器中文章可以帮助您为自己的容器设置。不管怎样，如果您安装和配置 超级用户权限这样你就可以在任何用户下运行，包括 root。

# 如果安装并配置了sudo
sudo apt-get update
sudo apt-get install <包

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

# 如果已安装和配置好sudo
sudo apt-get update
# 安装Git
sudo apt-get install git

您还可以使用"功能"物业在devcontainer.json 安装预定义的功能或者你自己选择的工具和语言。

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

"特性": {
    "ghcr.io/devcontainers/特性/azure-cli:1": {
        "版本": "最新"
    }
  }

参见Dev Container Features规范以获取更多详细信息。

重建

在编辑内容时.devcontainer 文件夹，您需要重建以使更改生效。使用 Dev Containers: 重建容器 命令更新您的容器。

然而，如果你重建容器，你将不得不重新安装任何你手动安装的东西。为了避免这个问题，你可以使用创建命令后物业在devcontainer.json或自定义Dockerfile输入：.

自定义Dockerfile将受益于Docker的构建缓存，并比创建命令后然而，Dockerfile在开发容器创建和挂载工作区文件夹之前运行，因此无法访问工作区文件夹中的文件。Dockerfile最适合于在不依赖于您的工作区文件的情况下安装软件包和工具。

该创建命令后在容器创建后运行操作，因此您也可以使用该属性来运行诸如等命令npm 安装或者在源代码树中执行一个 shell 脚本（如果你已经挂载它）。

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

您还可以使用交互式bash shell，以便您的.bashrc被拾取后，会自动为您的环境定制您的外壳：

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

像NVM这样的工具在不使用的情况下无法工作-我将 shell 设置为交互模式：

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

命令需要退出，否则容器无法启动。例如，如果你在添加应用程序启动到创建命令后, 命令不会退出。

还有开始后命令在容器每次启动时执行。参数的行为完全像创建命令后，但命令在启动时执行而不是创建。

而不是直接在devcontainer.json或通过安装软件创建命令后或开始后命令，一种更高效的实践方法是使用Dockerfile。

Dockerfile

Dockerfile 也将存储在.devcontainer文件夹。您可以替换图像物业在devcontainer.json与Dockerfile输入：

{
  "构建": { "Dockerfile": "Dockerfile" },

  "定制": {
    "vscode": {
      "扩展": ["dbaeumer.vscode-eslint"]
    }
  },

  "forwardPorts": [3000]
}

当你进行如安装新软件等更改时，即使在重新构建开发容器后，Dockerfile 中所做的更改也将保持持久。

在你的Dockerfile中，使用从指定图像，并且执行安装任何软件的说明。您可以使用&&将多个命令连接在一起。

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

注意：TheDEBIAN_FRONTEND导出可以避免在你继续处理容器时出现警告。

自动化开发容器创建

与其创造一个.devcontainer 手动，选择 Dev Containers: 添加 Dev Container 配置文件... 命令从命令面板 (F1) 将在你的项目中添加所需的文件作为起点，你可以根据需要进一步自定义。

该命令允许您从基于文件夹内容的列表中选择一个预定义的容器配置：

添加开发容器配置

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

在使用Dev Containers: 添加 Dev Container 配置文件...后，您将看到可用功能的列表，这些是您可以轻松放入开发容器中的工具和语言。Dev Containers: 配置容器功能允许您更新现有配置。

命令面板中的开发容器功能

您还可以重用现有的Dockerfile：

选择Dockerfile

既然你已经有一个devcontainer.json和Dockerfile，让我们看看编辑容器配置文件的一般过程。

完整配置编辑循环

编辑容器配置很容易。由于重建容器会将容器“重置”到其初始内容（本地源代码除外），如果你编辑容器配置文件，VS Code 不会自动重建。devcontainer.json，Dockerfile，和docker-compose.yml). 相反，有一些命令可以让你更容易地编辑配置。

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

容器编辑循环示意图

开始使用 开发容器: 在命令面板中添加开发容器配置文件... (F1).
编辑内容.devcontainer文件夹如需。
试试看 开发容器：在容器中重新打开.
如果看到错误，请选择在本地打开文件夹在出现的对话框中。
Windows重新加载后，构建日志的副本将出现在控制台上，以便您可以调查问题。编辑.devcontainer 文件夹如需。Dev Containers: Show Container Log 命令，如果你关闭了它，你也可以再次查看日志。
运行 开发容器：重建并在容器中重新打开，如有需要，跳至第4步。

如果你已经有一个成功的构建，你仍然可以编辑该内容.devcontainer 根据需要连接到容器并创建文件夹，然后在命令面板 (F1) 中选择 Dev Containers: 重新构建容器 使更改生效。

当使用 开发容器时，您还可以在容器中克隆仓库以进行迭代。

开始使用 开发容器：在容器卷中克隆仓库 在命令面板中（F1）。如果您输入的仓库没有 devcontainer.json在其中，您将被要求选择一个起点。
编辑内容.devcontainer文件夹如需。
尝试一下 开发容器：重建容器.
如果看到错误，请选择在恢复容器中打开在出现的对话框中。
编辑内容.devcontainer文件夹，如本“恢复容器”中所述。
使用开发容器：重新在容器中打开，如果仍然遇到问题，请跳至第4步。

使用Docker Compose

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

您可以：

与现有且未修改的服务定义一起工作docker-compose.yml输入：.
创建一个新的docker-compose.yml（或制作一个现有的副本）作为开发服务的依据。
扩展您现有的Docker Compose配置以开发该服务。
使用单独的 VS Code Windows来同时处理多个由Docker Compose定义的服务。

注意： 当使用 Alpine Linux 容器时，由于 glibc扩展中原代码的依赖项。

VS Code 可以配置为自动启动一个特定服务在Docker Compose文件中所需的容器。如果你已经使用命令行启动了配置的容器，VS Code 将会连接到你指定的运行服务。这为多容器工作流程提供了与上述Docker镜像和Dockerfile工作流程相同的快速设置优势，同时仍然允许你使用命令行（如果你更喜欢的话）。

要快速开始，打开你想要在 VS Code 中使用的文件夹，然后在命令面板中运行Dev Containers: 添加 Dev Container 配置文件...命令 (F1)。

您将被提示从我们的第一方和社区索引中选择一个预定义的容器配置，该配置是基于您的文件夹内容过滤和排序的。通过 VS Code 用户界面，您可以选择以下模板之一作为 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文件，您可以使用Docker 组合文件和服务属性在.devcontainer/devcontainer.json输入：.

例如：

{
  "name": "[可选] 您的项目名称",
  "dockerComposeFile": "../docker-compose.yml",
  "service": "您在VSCode中要使用的服务名称",
  "workspaceFolder": "/默认/工作区/在容器中打开的路径",
  "shutdownAction": "stopCompose"
}

参见devcontainer.json 参考了解其他可用属性的信息，例如工作区文件夹和关闭操作输入：.

一旦你添加了一个.devcontainer/devcontainer.json 将文件移动到你的文件夹，运行 Dev Containers: Reopen in Container 命令（或 Dev Containers: Open Folder in Container... 如果你还没有在容器中）从命令面板（F1）中执行。

如果容器尚未运行，VS Code 将调用docker-compose -f ../docker-compose.yml up在这个例子中。服务属性指示 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如下所示：

# 覆盖默认命令，以便在进程结束后不会关闭。
命令：/bin/sh -c "while sleep 1000; do :; done"

如果你还没有这样做，你可以“绑定”挂载你的本地源代码到容器中，使用Docker Compose文件中的volumes列表。

例如：

卷:
  # 将项目文件夹挂载到' /workspace '。容器内的目标路径
  # 应符合您的应用程序期望的路径。在这种情况下，编排文件位于子文件夹中，因此您将挂载' .. '。
  # 您会在此路径下引用' .devcontainer/devcontainer.json '中的' workspaceFolder '，以便 VS Code 从这里开始。
  - 
  ..:/workspace:cached

然而，在 Linux 上，您可能需要设置并 指定一个非 root 用户 当使用绑定挂载时，或者您创建的任何文件将是 root。请参阅将非 root 用户添加到您的开发容器了解详细信息。要让 VS Code 以不同的用户运行，请将此添加到 devcontainer.json输入：

"远程用户"："你的用户名"

如果你想让所有进程以不同的用户运行，请在你的Docker Compose文件中相应的服务中添加此内容：

用户：你的用户名

如果你没有为开发创建自定义的Dockerfile，你可能需要安装额外的开发工具，例如curl在服务的容器内。虽然将这些工具添加到容器镜像中更高效，但您也可以使用创建命令后为此目的的财产。

参见安装附加软件了解有关软件安装的更多信息devcontainer.json 参考了解有关创建命令后财产。

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

# 对于基于ptrace的调试器（如C++、Go和Rust）是必需的
cap_add:
- SYS_PTRACE
security_opt:
- seccomp:unconfined

第一次创建容器后，您需要运行Dev Containers: 重新构建容器命令以进行更新devcontainer.json, 您的Docker Compose文件，或相关的Docker文件以生效。

在Docker Compose中使用localhost

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

# 在与数据库容器相同的网络上运行服务，允许在devcontainer.json中使用"forwardPorts"。
network_mode：服务:db

你可以看到一个例子网络模式: 服务:db 在 Node.js 和 MongoDB 示例开发容器中。

扩展你的Docker Compose文件用于开发

参考现有的部署 / 非开发导向docker-compose.yml有一些潜在的缺点。

例如：

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

通过扩展整个Docker Compose配置，您可以解决这些问题和其他类似问题多个docker-compose.yml 文件用于覆盖或补充主文件。

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

版本：'3'
服务：
  your-service-name-here：
    卷：
      # 将项目文件夹挂载到 '/workspace'。当此文件在 .devcontainer 中时，
      # 挂载是相对于列表中的第一个文件，这里是向上一级。
      - .:/workspace:cached

    # [可选] 对于像 C++、Go 和 Rust 这样的 ptrace 基调试器是必需的
    cap_add:
      - SYS_PTRACE
    security_opt:
      - seccomp:unconfined

    # 覆盖默认命令，以便进程结束后不会关闭。
    命令: /bin/sh -c "while sleep 1000; do :; done"

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

{
  "名称": "[可选] 您的项目名称",

  // 文件的顺序很重要，因为后来的文件会覆盖前面的文件
  "dockerComposeFile": ["../docker-compose.yml", "docker-compose.extend.yml"],

  "service": "你的服务名称",
  "workspaceFolder": /workspace,
  "shutdownAction": "stopCompose"
}

VS Code 将会自动使用这两个文件来启动任何容器。你也可以在命令行中手动启动它们，如下所示：

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

虽然创建命令后属性允许你在容器内安装额外的工具。在某些情况下，你可能希望为开发使用特定的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中配置了一个开发容器。继续阅读以了解如何在队友和各种项目之间共享容器配置。

将配置文件添加到代码库

您可以轻松地通过添加来共享项目定制的Dev Container模板devcontainer.json将这些文件添加到源代码控制中。通过将这些文件包含在你的仓库中，任何人在 VS Code 中打开你仓库的本地副本时，如果他们已经安装了 Dev Containers 扩展，将会自动提示在容器中重新打开该文件夹。

开发容器配置文件重新打开通知

除了使用一致的环境和工具链所带来的优势之外，这还使得新贡献者或团队成员能够更快地开始工作。首次贡献者需要的指导更少，并且遇到与环境设置相关的错误更少。

添加在开发容器中打开的徽章

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

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

[![在开发容器中打开](https://img.shields.io/static/v1?label=开发容器&message=打开&color=blue)](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/microsoft/vscode-remote-try-java)

您还可以包括一个在开发容器中打开直接链接：

如果你已经安装了 VS Code 和 Docker，你可以点击上面的徽章或 [这里](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/microsoft/vscode-remote-try-java) 来开始。点击这些链接将导致 VS Code 自动安装所需的扩展，将源代码克隆到容器卷中，并启动一个开发容器供使用。

备用：存储库配置文件夹

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

首先，更新开发 > 容器：仓库配置路径 用户设置为本地文件夹，该文件夹将用于存储您的仓库容器配置文件。

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

仓库容器文件夹设置

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

📁 github.com
📁 devcontainers
📁 templates
📁 .devcontainer

一旦设置好，使用任何Dev Containers命令时都会自动读取配置。进入容器后，您还可以从命令面板（F1）选择Dev Containers: 打开容器配置文件来打开相关的devcontainer.json保存并进行进一步编辑。

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

下一步

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