在 VS Code 中试用

创建开发容器

Visual Studio Code 开发容器扩展允许你将Docker 容器用作功能齐全的开发环境。它允许你在容器中打开任何文件夹或存储库,并充分利用 Visual Studio Code 的所有功能。项目中的 devcontainer.json 文件会告诉 VS Code 如何访问(或创建)一个具有明确定义的工具和运行时堆栈的开发容器。此容器可用于运行应用程序或提供处理代码库所需的独立工具、库或运行时。

创建开发容器的路径

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

  1. 创建一个 devcontainer.json 文件,它描述了 VS Code 应该如何启动容器以及连接后应该做什么。
  2. 通过使用 Dockerfile,对开发容器进行更改并使其持久化,例如安装新软件。
  3. 通过 Docker Compose 配置多个容器。
  4. 进行更改时,构建你的开发容器以确保更改生效。

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

注意:开发容器扩展有一个 开发容器:添加开发容器配置文件... 命令,可让你从列表中选择预定义的容器配置。如果你更喜欢立即拥有一个完整的开发容器,而不是逐步构建 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"
}

你可以修改配置以执行以下操作:

对于此示例,如果你想在容器中安装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 重启时,你现在已处于一个 Node.js 和 TypeScript 开发容器中,其中端口 3000 已转发,并安装了 ESLint 扩展。连接后,请注意状态栏左侧的绿色远程指示器,它显示你已连接到开发容器

VS Code instance connected to dev container

其他开发容器场景

通过 devcontainer.json 文件,你可以:

如果 devcontainer.json 支持的工作流不满足你的需求,你也可以改为连接到已在运行的容器

提示:想使用远程 Docker 主机吗?请参阅在远程 Docker 主机上开发文章以了解设置详情。

安装附加软件

你可能希望在开发容器中安装附加软件。一旦 VS Code 连接到容器,你就可以打开一个 VS Code 终端并在容器内的操作系统上执行任何命令。这允许你在 Linux 容器内部安装新的命令行实用程序,并启动数据库或应用程序服务。

大多数容器镜像都基于 Debian 或 Ubuntu,其中使用 aptapt-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"

NVM 等工具在不使用 -i 将 shell 置于交互模式的情况下将无法工作

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

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

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

与直接在 devcontainer.json 中引用镜像或通过 postCreateCommandpostStartCommand 安装软件相比,更有效的方法是使用 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)中选择 开发容器:添加开发容器配置文件... 命令会将所需的文件添加到你的项目作为起点,你可以根据需要进一步自定义。

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

Add a dev container config

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

在 使用 开发容器:添加开发容器配置文件... 命令的最后,你将看到可用特性列表,它们是可以轻松添加到你的开发容器中的工具和语言。开发容器:配置容器特性 允许你更新现有配置。

Dev container features in Command Palette

你也可以重用现有的 Dockerfile

Select Dockerfile

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

完整配置编辑循环

编辑容器配置很容易。由于重建容器会将其“重置”为其初始内容(本地源代码除外),因此如果你编辑容器配置文件(devcontainer.jsonDockerfiledocker-compose.yml),VS Code 不会自动重建。相反,有几个命令可以用来使你的配置编辑更容易。

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

Container edit loop illustration

  1. 从命令面板(F1)开始使用 开发容器:添加开发容器配置文件...
  2. 根据需要编辑 .devcontainer 文件夹的内容。
  3. 尝试使用 开发容器:在容器中重新打开
  4. 如果看到错误,请在出现的对话框中选择 本地打开文件夹
  5. 窗口重新加载后,控制台中将出现一份构建日志副本,以便你调查问题。根据需要编辑 .devcontainer 文件夹的内容。(如果关闭日志,你也可以使用 开发容器:显示容器日志 命令再次查看日志。)
  6. 运行 开发容器:重建并在容器中重新打开,如果需要则跳转到步骤 4。

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

使用 开发容器:在容器卷中克隆存储库 命令时,你也可以迭代你的容器。

  1. 从命令面板(F1)开始使用 开发容器:在容器卷中克隆存储库。如果你输入的存储库中没有 devcontainer.json,系统会要求你选择一个起点。
  2. 根据需要编辑 .devcontainer 文件夹的内容。
  3. 尝试使用 开发容器:重建容器
  4. 如果看到错误,请在出现的对话框中选择 在恢复容器中打开
  5. 在此“恢复容器”中,根据需要编辑 .devcontainer 文件夹的内容。
  6. 使用 开发容器:在容器中重新打开,如果仍然遇到问题,请跳转到步骤 4。

使用 Docker Compose

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

你可以:

  1. 使用现有、未修改的 docker-compose.yml 中定义的服务。
  2. 创建一个新的 docker-compose.yml(或复制现有的),用于开发服务。
  3. 扩展你现有的 Docker Compose 配置以开发服务。
  4. 使用独立的 VS Code 窗口同时处理多个 Docker Compose 定义的服务

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

VS Code 可以配置为自动启动 Docker Compose 文件中特定服务所需的任何容器。如果你已使用命令行启动了已配置的容器,VS Code 将改为连接到你指定正在运行的服务。这使得你的多容器工作流具有与上述 Docker 镜像和 Dockerfile 工作流相同的快速设置优势,同时如果你愿意,仍然允许你使用命令行。

要快速入门,请在 VS Code 中打开你想要工作的文件夹,然后从命令面板(F1)中运行 开发容器:添加开发容器配置文件... 命令。

系统将提示你从我们的第一方和社区索引中选择一个预定义的容器配置,该列表可筛选并根据你的文件夹内容排序。在 VS Code UI 中,你可以选择以下模板之一作为 Docker Compose 的起点:

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

做出选择后,VS Code 会将相应的 .devcontainer/devcontainer.json(或 .devcontainer.json)文件添加到文件夹中。

你也可以手动创建配置。要重用未修改的 Docker Compose 文件,你可以在 .devcontainer/devcontainer.json 中使用 dockerComposeFileservice 属性。

例如:

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

有关 workspaceFoldershutdownAction 等其他可用属性的信息,请参阅devcontainer.json 参考

.devcontainer/devcontainer.json 文件添加到文件夹后,从命令面板(F1)运行 开发容器:在容器中重新打开 命令(如果你尚未在容器中,则运行 开发容器:在容器中打开文件夹...)。

如果容器尚未运行,VS Code 将在此示例中调用 docker-compose -f ../docker-compose.yml upservice 属性指示 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

首次创建容器后,你需要运行 开发容器:重建容器 命令,以使 devcontainer.json、你的 Docker Compose 文件或相关 Dockerfile 的更新生效。

在 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

你可以在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 container configuration file reopen notification

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

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

你还可以在存储库中添加徽章或链接,以便用户可以轻松地在开发容器中打开你的项目。它将在必要时安装开发容器扩展,将存储库克隆到容器中,并启动开发容器。

例如,一个打开 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.

备选方案:存储库配置文件目录

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

首先,使用你希望用于存储存储库容器配置文件的本地文件夹更新 开发 > 容器:存储库配置路径 用户设置

在“设置”编辑器中,你可以搜索“开发容器存储库”以找到该设置

Repository container folders setting

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

📁 github.com
    📁 devcontainers
        📁 templates
           📁 .devcontainer

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

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

后续步骤