Dev Container CLI 保姆级部署教程：把开发环境装进容器的官方工具完整搭建

Dev Container CLI 是微软开源的「开发容器」官方命令行工具，属于 Development Containers 开放规范。截至本文写作时在 GitHub 上收获约 3 千 Star，main 分支几乎每天都有提交。它能读取一个 devcontainer.json 文件，在 Docker 里为你构建并配置一个完整的开发环境容器。

为什么需要它？团队里每个人的电脑环境都不一样——你装了 Node 20，我装了 Node 18，他用 Windows 他用 Mac，跑同一份代码经常报「在我机器上是好的」。Dev Container 的思路是：把整个开发环境（编译器、语言运行时、工具链、甚至 VS Code 插件）写成一个 devcontainer.json，提交进 Git，任何人 clone 下来一条命令就能起一个一模一样的容器。本文从零开始，把 CLI 装好、跑通第一个 Rust 示例、讲清楚怎么为自己的项目写 devcontainer.json。

一、项目介绍与适用场景

Dev Container CLI 是 Development Containers 规范的官方参考实现。它的输入是一个 devcontainer.json，输出是一个跑起来的容器。适合：

• 团队统一环境：新同学入职不用装一堆依赖，clone 仓库、跑 devcontainer up 就能开发。
• CI/CD：用 dev container 当 CI 构建环境，本地和 CI 完全一致。
• 多语言项目：一个仓库里有 Python + Go + Rust，用 dev container 一次性配齐。
• 隔离开发：不想在宿主机装一堆语言工具链，全在容器里玩。

二、核心功能逐条拆解

1. devcontainer up：读 devcontainer.json，构建并启动容器（官方已实现）。
2. devcontainer build：只构建镜像，可预构建加速后续启动。
3. devcontainer exec：在运行中的容器里执行命令，自动套用 remoteUser、remoteEnv 等配置。
4. devcontainer run-user-commands：跑 postCreateCommand 等生命周期脚本。
5. devcontainer read-configuration：输出当前生效的配置，方便调试。
6. devcontainer outdated / upgrade：检查 / 升级 lockfile 里的 feature 版本。
7. devcontainer features / templates：作者工具，帮你写和测试 Dev Container Features / Templates。
8. Lockfile 可复现：build / up 默认生成 .devcontainer-lock.json 钉死 feature 版本，--frozen-lockfile 强制用 lockfile。
9. 尚未实现：官方 README 明确 devcontainer stop 和 devcontainer down 还没做（用 Docker 原生命令替代）。

三、全套官方链接

四、硬件与环境前置要求

• Docker：必须装 Docker（或 Docker Desktop）。CLI 本身只是个控制器，真正干活的是 Docker。
• 操作系统：Linux / macOS；Windows 走 WSL2。
• Node.js（仅 npm 安装方式）：Node 18+，且需要 Python 和 C/C++ 编译工具来建一个依赖。
• 磁盘：每个 dev container 镜像几百 MB 到几 GB，留足空间。

五、多平台安装步骤

5.1 一行脚本安装（推荐，无需 Node）

官方 README 原文：

curl -fsSL https://raw.githubusercontent.com/devcontainers/cli/main/scripts/install.sh | sh

这个脚本会下载一个自带 Node 运行时的打包版 CLI，不需要你本机装 Node。支持 Linux 和 macOS（x64 和 arm64）。

装完后把 PATH 加上：

export PATH="$HOME/.devcontainers/bin:$PATH"

把这行写进 ~/.bashrc 永久生效。

进阶用法（官方 README 原文）：

# 装指定版本
sh install.sh --version 0.82.0

# 装到自定义目录
sh install.sh --prefix ~/.local/devcontainers

# 更新到最新
sh install.sh --update

# 卸载
sh install.sh --uninstall

5.2 npm 安装（已有 Node 的环境）

官方 README 原文：

npm install -g @devcontainers/cli

官方提醒：npm 版需要 Python 和 C/C++ 编译工具来建一个依赖。

验证：

devcontainer --help

会打印所有子命令（up / build / run-user-commands / read-configuration / features / templates / exec）。

5.3 从源码编译

官方 README 原文：

yarn
yarn compile

验证：

node devcontainer.js --help

六、配置文件全部参数解释

Dev Container 的核心配置是项目根目录 .devcontainer/devcontainer.json。下面是官方示例（以 Rust 项目为例，来自 README 的 example）：

{
  "name": "Rust Demo",
  "build": {
    "dockerfile": "Dockerfile"
  },
  "customizations": {
    "vscode": {
      "extensions": ["rust-lang.rust-analyzer"]
    }
  }
}

常见字段：

Lockfile：.devcontainer-lock.json 由 build / up 自动生成，钉死 feature 版本；用 --no-lockfile 关闭，--frozen-lockfile 强制用现有 lockfile。

七、启动、后台常驻与开机自启

7.1 启动一个示例容器

官方 README 给的完整示例：

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

预期输出（官方 README 原文）：

[88 ms] dev-containers-cli 0.1.0.
[165 ms] Start: Run: docker build -f ...
[+] Building 0.5s (5/5) FINISHED
...
Container started
{"outcome":"success","containerId":"f0a055ff...","remoteUser":"vscode","remoteWorkspaceFolder":"/workspaces/vscode-remote-try-rust"}

7.2 在容器里跑命令

官方 README 原文：

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

预期输出：

   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 Remote - Containers!

7.3 停止 / 删除容器

官方 README 明确 devcontainer stop 和 devcontainer down 还没实现。手动用 Docker：

docker ps                 # 找到容器名
docker stop <容器名>
docker rm <容器名>

7.4 后台常驻

dev container 本身就是 Docker 容器，由 Docker 管理生命周期；不需要额外 systemd。

八、功能实操教程

第 1 步：用 5.1 的脚本装好 CLI，export PATH=... 后 devcontainer --help 验证。

第 2 步：git clone https://github.com/microsoft/vscode-remote-try-rust。

第 3 步：devcontainer up --workspace-folder ./vscode-remote-try-rust。第一次会拉 Rust 镜像、构建，耐心等。

第 4 步：看到 {"outcome":"success",...} 后，跑 devcontainer exec --workspace-folder ./vscode-remote-try-rust cargo run，看到「Hello, VS Code Remote - Containers!」就成了。

第 5 步：在自己项目里建 .devcontainer/devcontainer.json，写一个最小配置：

{
  "image": "mcr.microsoft.com/devcontainers/javascript-node:20",
  "postCreateCommand": "npm install"
}

第 6 步：在自己项目里跑 devcontainer up --workspace-folder .，CLI 会拉 Node 20 镜像、启动容器、自动 npm install。

第 7 步：试 lockfile——再次 devcontainer up，看目录下多了 .devcontainer-lock.json。

九、全套报错故障排查

报错 1： devcontainer: command not found 原因分析：~/.devcontainers/bin 不在 PATH。 解决方案：echo 'export PATH="$HOME/.devcontainers/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc。

报错 2： Cannot connect to the Docker daemon 原因分析：Docker 没起。 解决方案：sudo systemctl start docker（Linux）或启动 Docker Desktop（macOS）。

报错 3： npm 安装时报 node-gyp 编译失败。 原因分析：缺 Python 或 C/C++ 编译工具。 解决方案：用 5.1 的脚本安装（自带 Node 运行时，避开这个问题）；或 apt install python3 build-essential 后重试。

报错 4： devcontainer up 卡在拉镜像。 原因分析：网络拉 mcr.microsoft.com 慢。 解决方案：配 Docker 镜像加速器；或换国内镜像源。

报错 5： lockfile 和 devcontainer.json 不一致。 原因分析：改了 feature 版本但没重新生成 lockfile。 解决方案：删掉 .devcontainer-lock.json 后重跑 devcontainer up；CI 里用 --frozen-lockfile 强制用现有 lockfile 跑。

十、升级、回滚与卸载

升级：脚本版 sh install.sh --update；npm 版 npm update -g @devcontainers/cli。

备份建议：配置就是项目里的 .devcontainer/ 目录，跟 Git 走，不需要单独备份。

回滚：脚本版 sh install.sh --version 0.82.0；npm 版 npm install -g @devcontainers/cli@具体旧版本。

卸载：脚本版 sh install.sh --uninstall；npm 版 npm uninstall -g @devcontainers/cli。

十一、商用许可与合规风险提示

Dev Container CLI 采用 MIT（README 原文：This project is under an MIT license），可自由商用、二次开发、嵌入 CI。注意：

• 它本身只是个控制器，真正跑的是 Docker 镜像——你在 devcontainer.json 里选的基础镜像（如 mcr.microsoft.com/vscode/devcontainers/rust）各有自己的 license，商用前看对应镜像条款。
• 官方 README 明确 stop / down 子命令尚未实现，生产脚本里别假设它们存在。
• 团队推广时，建议把 .devcontainer/ 提交进 Git，让所有人用同一份配置；lockfile 也提交，保证可复现。

参考链接

• GitHub 仓库：https://github.com/devcontainers/cli
• 规范官网：https://devcontainers.github.io/
• npm 包：https://www.npmjs.com/package/@devcontainers/cli
• Features 文档：https://containers.dev/implementors/features/