Dev Container CLI

本主题介绍开发容器命令行界面 (dev container CLI)，该界面允许您构建和管理开发容器，并且是 Development Containers Specification 的配套工具。

开发容器

一致且可预测的环境是实现高效且愉悦的软件开发体验的关键。

容器（例如 Docker 容器）历来用于在部署应用程序时对其进行标准化，但现在有很好的机会来支持其他场景，包括持续集成 (CI)、测试自动化和功能齐全的编码环境。 开发容器 提供此工作环境，并确保您的项目拥有所需的工具和软件，无论项目是复杂且分布式的，还是仅具有少量要求。

Diagram comparing dev versus production containers

Visual Studio Code 通过 Dev Containers 扩展和 GitHub Codespaces 支持开发容器。此支持由 devcontainer.json 提供支持，devcontainer.json 是一种结构化的 JSON with Comments (jsonc) 元数据格式，用于配置容器化环境。

随着容器化生产工作负载变得司空见惯，开发容器已在 VS Code 之外的场景中得到广泛应用。为了在任何环境中推广开发容器，已开始制定 Development Containers Specification，该规范使任何工具中的任何人都可以配置一致的开发环境。开源 dev container CLI 充当该规范的参考实现。

dev container CLI

当 VS Code 和 Codespaces 等工具在用户的项目中检测到 devcontainer.json 文件时，它们会使用 CLI 来配置开发容器。 dev container CLI 是参考实现，以便个人用户和其他工具可以读取 devcontainer.json 元数据并从中创建开发容器。

此 CLI 既可以直接使用，也可以集成到产品体验中，类似于今天它与 Dev Containers 和 Codespaces 集成的方式。它目前既支持简单的单容器选项，也与 Docker Compose 集成以用于多容器场景。

CLI 在 devcontainers/cli 存储库中提供。

安装

您可以通过 Dev Containers 扩展快速试用 CLI。从命令面板 (F1) 中选择 Dev Containers: Install devcontainer CLI 命令。

备用安装

还有其他选项可在其他位置使用 CLI

安装其 npm 包
使用 GitHub Action 或 Azure DevOps Task
- 您可以在 devcontainers/ci 中找到这些
从源代码构建 CLI 存储库
- 您可以在 CLI 存储库的 README 中了解有关从源代码构建的更多信息

在本页中，我们将重点介绍如何使用 npm 包。

npm install

要安装 npm 包，您需要安装 Python、Node.js（版本 14 或更高版本）和 C/C++ 以构建其中一个依赖项。 VS Code How to Contribute wiki 提供了有关推荐工具集的详细信息。

npm install -g @devcontainers/cli

验证您可以运行 CLI 并查看其帮助文本

devcontainer <command>

Commands:
  devcontainer up                   Create and run dev container
  devcontainer build [path]         Build a dev container image
  devcontainer run-user-commands    Run user commands
  devcontainer read-configuration   Read configuration
  devcontainer features             Features commands
  devcontainer templates            Templates commands
  devcontainer exec <cmd> [args..]  Execute a command on a running dev container

Options:
  --help     Show help                                                 [boolean]
  --version  Show version number                                       [boolean]

注意： 如果您通过 VS Code 安装了 CLI，则会列出用于打开开发容器的 open 命令。

运行 CLI

获得 CLI 后，您可以尝试使用示例项目，例如此 Rust 示例。

将 Rust 示例克隆到您的计算机，并使用 CLI 的 up 命令启动开发容器

git clone https://github.com/microsoft/vscode-remote-try-rust
devcontainer up --workspace-folder <path-to-vscode-remote-try-rust>

这将从容器注册表下载容器镜像并启动容器。您的 Rust 容器现在应该正在运行

[88 ms] dev-containers-cli 0.1.0.
[165 ms] Start: Run: docker build -f /home/node/vscode-remote-try-rust/.devcontainer/Dockerfile -t vsc-vscode-remote-try-rust-89420ad7399ba74f55921e49cc3ecfd2 --build-arg VARIANT=bullseye /home/node/vscode-remote-try-rust/.devcontainer
[+] Building 0.5s (5/5) FINISHED
 => [internal] load build definition from Dockerfile                       0.0s
 => => transferring dockerfile: 38B                                        0.0s
 => [internal] load .dockerignore                                          0.0s
 => => transferring context: 2B                                            0.0s
 => [internal] load metadata for mcr.microsoft.com/vscode/devcontainers/r  0.4s
 => CACHED [1/1] FROM mcr.microsoft.com/vscode/devcontainers/rust:1-bulls  0.0s
 => exporting to image                                                     0.0s
 => => exporting layers                                                    0.0s
 => => writing image sha256:39873ccb81e6fb613975e11e37438eee1d49c963a436d  0.0s
 => => naming to docker.io/library/vsc-vscode-remote-try-rust-89420ad7399  0.0s
[1640 ms] Start: Run: docker run --sig-proxy=false -a STDOUT -a STDERR --mount type=bind,source=/home/node/vscode-remote-try-rust,target=/workspaces/vscode-remote-try-rust -l devcontainer.local_folder=/home/node/vscode-remote-try-rust --cap-add=SYS_PTRACE --security-opt seccomp=unconfined --entrypoint /bin/sh vsc-vscode-remote-try-rust-89420ad7399ba74f55921e49cc3ecfd2-uid -c echo Container started
Container started
{"outcome":"success","containerId":"f0a055ff056c1c1bb99cc09930efbf3a0437c54d9b4644695aa23c1d57b4bd11","remoteUser":"vscode","remoteWorkspaceFolder":"/workspaces/vscode-remote-try-rust"}

然后，您可以在此开发容器中运行命令

devcontainer exec --workspace-folder <path-to-vscode-remote-try-rust> cargo run

这将编译并运行 Rust 示例，输出

[33 ms] dev-containers-cli 0.1.0.
   Compiling hello_remote_world v0.1.0 (/workspaces/vscode-remote-try-rust)
    Finished dev [unoptimized + debuginfo] target(s) in 1.06s
     Running `target/debug/hello_remote_world`
Hello, VS Code Dev Containers!
{"outcome":"success"}

CLI 存储库的 README 中也提供了上述步骤。

自动化

如果您想在 CI/CD 构建或测试自动化中使用 dev container CLI，您可以在 devcontainers/ci 存储库中找到 GitHub Actions 和 Azure DevOps Tasks 的示例。

预构建

devcontainer build 命令允许您按照 Dev Containers 扩展或 GitHub Codespaces 使用的相同步骤快速构建开发容器镜像。当您想要使用 CI 或 DevOps 产品（如 GitHub Actions）预构建开发容器镜像时，此功能特别有用。

build 接受包含 .devcontainer 文件夹或 .devcontainer.json 文件的文件夹的路径。例如，devcontainer build --workspace-folder <my_repo> 将为 my_repo 构建容器镜像。

构建和发布镜像的示例

例如，您可能想要预构建多个镜像，然后在多个项目或存储库中重复使用这些镜像。为此，请按照以下步骤操作

创建源代码存储库。

为您要预构建的每个镜像创建开发容器配置，并根据需要进行自定义（包括 dev container Features）。例如，考虑以下 devcontainer.json 文件

{
  "build": {
    "dockerfile": "Dockerfile"
  },
  "features": {
    "ghcr.io/devcontainers/features/docker-in-docker:1": {
      "version": "latest"
    }
  }
}

使用 devcontainer build 命令构建镜像，并将镜像推送到您的镜像注册表。有关镜像命名和附加步骤（如身份验证）的信息，请参阅您的镜像注册表的文档（例如 Azure Container Registry、GitHub Container Registry 或 Docker Hub）。
```
devcontainer build --workspace-folder <my_repo> --push true --image-name <my_image_name>:<optional_image_version>
```

避免使用 Docker 构建的镜像出现问题

鉴于 Dockerfile 和 Docker Compose 文件可以在没有 VS Code 或 devcontainer CLI 的情况下使用，您可能需要告知用户他们不应尝试直接构建镜像。您可以在高级开发容器文档中了解更多信息。

模板和功能

您可以使用 dev container CLI 处理开发容器模板和功能。当您创建和使用模板时，您可能想要为其他人发布它们，您可以在 dev container 规范中了解更多相关信息。

反馈

dev container CLI 和规范正在积极开发中，我们欢迎您的反馈，您可以在此问题中提供反馈，或通过 devcontainers/cli 存储库中的新问题和拉取请求提供反馈。

后续步骤

Dev container specification repository - 阅读并为开放规范做出贡献。
devcontainer.json reference - 查看 devcontainer.json 架构。
创建开发容器 - 为您的工作环境创建自定义容器。
高级容器 - 查找高级容器场景的解决方案。

03/05/2025