创建开发容器

Name: Visual Studio Code
Author: Microsoft

Visual Studio 的开发容器扩展允许你将 Docker 容器作为功能齐全的开发环境使用。它允许你在容器内打开任意文件夹或仓库，并充分利用 Visual Studio Code 的完整功能集。Adevcontainer.json项目中的文件告诉 VS Code 如何访问（或创建）一个带有明确工具和运行时栈的开发容器。该容器可用于运行应用程序，或提供用于代码库作所需的独立工具、库或运行时。

创建开发容器的路径

在本文档中，我们将讲解在VS Code中创建开发（开发）容器的步骤：

创建一个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 配置。
添加更多高级容器配置。

举个例子，如果你想在容器中安装代码拼写检查器扩展并自动转发端口3000，你的devcontainer.json看起来会是：

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

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

注：额外的配置会根据基础镜像中的内容添加到容器中。例如，我们添加streetsidesoftware.code-拼写检查器上方扩展，容器还将包括“dbaeumer.vscode-eslint”作为这是mcr.microsoft.com/devcontainers/typescript-node.在使用devcontainer.json预装时会自动完成，你可以在预装部分了解更多。

结合上述情况devcontainer.json你的开发容器已经功能正常，你可以连接并开始开发。试试用Dev Containers： Reopen in Container命令：

快速选择并附带开发容器命令列表

执行该命令后，当VS Code重启时，你就进入了一个Node.js和TypeScript开发容器，端口3000已转发，并安装了ESLint扩展。连接后，注意状态栏左侧的绿色远程指示器，显示你已连接到开发容器：

VS Code 实例连接到开发容器

其他开发容器场景

通过一个devcontainer.json你可以：

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

如果devcontainer.json支持的工作流程不满足你的需求，你也可以直接连接到已经运行的容器。

提示：想使用远程Docker主机？关于设置的详细信息，请参见“远程 Docker 主机开发”条目。

安装额外软件

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

大多数容器镜像基于 Debian 或 Ubuntu，其中公寓或APT-GETCommand 用于安装新包。你可以在 Ubuntu 的文档中了解更多关于该命令的信息。阿尔卑斯山的图像包括类似APK指挥而 CentOS / RHEL / Oracle SE / Fedora 镜像用途好吃或最近DNF.

你想安装的软件文档通常会提供具体说明，但你可能不需要在命令前加上须藤如果你在容器里以根权限运行，

例如：

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

如果你是root用户，只要安装软件，只要须藤在你的容器中配置。所有预定义容器都具有须藤设置，但“向容器添加非根用户”这篇文章可以帮助你为自己的容器设置。无论如何，如果你安装并配置好须藤你可以在任何用户（包括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安装预设功能组的工具和语言，甚至是你自己的。

例如，你可以安装最新版本的Azure CLI，并配合以下内容：

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

更多细节请参见开发容器功能规范。

重建

在编辑.devcontainer文件夹，你需要重建才能生效更改。使用开发容器：重建容器命令来更新你的容器。

不过，如果你重建容器，就必须重新安装你手动安装过的所有东西。为了避免这个问题，你可以使用postCreateCommand财产devcontainer.json或者是一种习俗Dockerfile.

一个习俗Dockerfile将受益于 Docker 的构建缓存，并使重建速度比 Docker 快postCreateCommand.然而，Dockerfile运行于开发容器创建之前，且 workspace 文件夹挂载，因此无法访问 workspace 文件夹中的文件。ADockerfile最适合安装独立于工作区文件的软件包和工具。

该postCreateCommand作在容器创建后才执行，所以你也可以用该属性执行以下命令NPM 安装或者在源树中执行 shell 脚本（如果你已经挂载了它）。

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

你也可以使用交互式 bash shell，这样你的.bashrc被拾取后，自动为你的外壳定制以适应你的环境：

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

像NVM这样的工具如果不使用是无法工作的-我将壳体置于交互模式：

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

命令必须退出，否则容器无法启动。例如，如果你添加一个应用程序，开始到postCreateCommand命令无法退出。

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

而不是直接引用图像devcontainer.json或者通过postCreateCommand或postStartCommand更高效的做法是使用 Dockerfile。

Dockerfile

Dockerfile 也会存在于.devcontainer文件夹。你可以替换图片财产devcontainer.json其中dockerfile:

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

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

  "forwardPorts": [3000]
}

当你做了安装新软件等更改时，Docker文件中的更改即使重建开发容器也会持续存在。

在你的 Dockerfile 里，用来自用来指定图像，以及快跑安装任何软件的说明。你可以用它串联多个命令。&&

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）将将所需文件添加到你的项目中，作为起点，你可以根据需要进一步定制。

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

添加开发容器配置

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

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

Command Palette 中的开发容器功能

你也可以复用现有的Docker文件：

选择 Dockerfile

现在你有了devcontainer.json以及 Dockerfile，让我们看看编辑容器配置文件的一般流程。

完整配置编辑循环

编辑你的容器配置很简单。由于重建容器会“重置”容器到起始内容（本地源代码除外），VS Code 不会在你编辑容器配置文件时自动重建（devcontainer.json,Dockerfile，和docker-compose.yml).相反，有几个命令可以让编辑配置变得更简单。

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

容器编辑循环示意图

从开发容器开始：在命令面板（F1）中添加开发容器配置文件。
编辑.devcontainer按需要使用文件夹。
试试用开发容器：在容器中重新打开。
如果看到错误，请在弹出的对话框中选择“本地打开文件夹”。
窗口重新加载后，构建日志会在控制台中显示，你可以调查问题。编辑.devcontainer按需要使用文件夹。（如果你关闭日志，也可以使用开发容器：显示容器日志命令重新查看日志。）
运行开发容器：在容器中重建并重新打开，必要时跳到第四步。

如果你已经有一个成功的构建，你仍然可以编辑.devcontainer连接到容器时按要求设置文件夹，然后在命令面板（F1）中选择开发容器：重建容器，这样更改就会生效。

你也可以在容器卷命令中使用开发容器：克隆仓库时对容器进行迭代。

从开发容器：命令面板（F1）中的容器卷中克隆仓库开始。如果你输入的仓库没有devcontainer.json在它中，你将被要求选择一个起点。
编辑.devcontainer按需要使用文件夹。
试试用开发容器：重建容器。
如果看到错误，请在弹出的对话框中选择“在恢复容器中打开”。
编辑.devcontainer文件夹按要求存放在这个“恢复容器”中。
使用开发容器：在容器中重新打开，如果仍然遇到问题，可以跳到第四步。

使用 Docker Compose

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

你可以选择：

使用已存在且未修改的服务定义docker-compose.yml.
创建一个新的docker-compose.yml（或者复制现有的），用来开发服务。
扩展你现有的 Docker Compose 配置来开发服务。
使用不同的 VS Code 窗口，同时处理多个 Docker Compose 定义的服务。

注：使用 Alpine Linux 容器时，某些扩展可能无法使用，原因包括格利比克扩展内部原生代码中的依赖关系。

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

要快速开始，请在VS Code中打开你想作的文件夹，在命令面板（F1）中执行开发容器：添加开发容器配置文件......命令。

系统会提示您从我们的第一方和社区索引中选择预定义的容器配置，列表可筛选，按文件夹内容排序。在 VS Code 界面中，您可以选择以下模板之一作为 Docker Compose 的起点：

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

在你做出选择后，VS Code会添加相应的.devcontainer/devcontainer.json（或.devcontainer.json）文件。

你也可以手动创建配置。要重用未修改的 Docker Compose 文件，可以使用dockerComposeFile以及服役经历在.devcontainer/devcontainer.json.

例如：

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

请参阅devcontainer.json参考文献，了解其他可用属性，如workspaceFolder以及关闭行动.

一旦你添加了.devcontainer/devcontainer.json文件到你的文件夹，从命令面板（F1）中执行“开发容器：在容器中重新打开”命令（或如果你还没进入容器，则“开发容器：在容器中打开文件夹”）。

如果容器还没有运行，VS Code 会调用docker-compose -f ../上docker-compose.yml在这个例子中。该服役经历property 表示 Docker Compose 文件中 VS Code 应该连接哪个服务，而不是应该启动哪个服务。如果你是手动启动的，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，可能需要安装额外的开发工具，比如卷曲在服务的集装箱内。虽然效率不如将这些工具添加到容器映像中，但你也可以使用postCreateCommand为此目的而设的财产。

有关安装软件的更多信息，请参见安装附加软件，devcontainer.json参考文献中获取更多相关信息postCreateCommand财产。

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

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

在你第一次创建容器后，你需要运行“开发容器：重建容器”命令以获取更新devcontainer.json，你的 Docker Compose 文件，或相关的 Docker 文件，才能生效。

在Docker Compose中使用localhost

你可以在你的账户中添加其他服务docker-compose.yml文件，如 Docker 文档中所述。然而，如果你希望该服务中运行的任何内容能在localhost的容器中可用，或者想本地转发服务，请务必在服务配置中添加以下行：

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

你可以看到一个例子network_mode：服务：db在Node.js和MongoDB示例开发容器中。

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

参考现有部署/非开发相关项目docker-compose.yml但也有一些潜在的缺点。

例如：

如果容器的入口关闭，Docker Compose 会关闭该容器。这在调试时需要反复重启应用时会有问题。
你也可能没有将本地文件系统映射到容器中，或者没有将端口暴露给你想访问的其他资源，比如数据库。
你可能想复制你所在地方的邮件内容.嘘或在容器中设置上述ptrace选项，使用Docker Compose。

你可以通过扩展整个 Docker Compose 配置来解决这些以及类似的问题多重docker-compose.yml文件它能覆盖或补充你的主计划。

例如，考虑以下.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

虽然postCreateCommandproperty 允许你在容器内安装更多工具，有时你可能需要专门的 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 扩展，将仓库克隆到容器卷中，然后启动开发容器。

举例来说，开门 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)

你也可以包含一个在开发容器中打开直接链接：

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 > 容器：仓库配置路径用户设置，加入你想用来存储仓库容器配置文件的本地文件夹。

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

仓库容器文件夹设置

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

📁 github.com
    📁 devcontainers
        📁 templates
           📁 .devcontainer

一旦配置到位，使用任何 Dev Containers 命令时，配置会自动被执行。进入容器后，你也可以从命令面板（F1）中选择开发容器：打开容器配置文件以打开相关文件devcontainer.json归档并进行进一步编辑。

查找配置的路径由的输出推导git remote -v.如果你尝试重新打开容器中的文件夹时找不到该配置，请在命令面板（F1）中查看日志“开发容器：显示容器日志”，查看已检查路径的列表。

下一步

附加到正在运行的容器——连接到已经运行的 Docker 容器。
高级容器——寻找针对高级容器场景的解决方案。
devcontainer.json参考文献 - 回顾devcontainer.jsonSchema。