VS Code Dev Containers 复用 Features 的开发环境配置

要在多个项目或团队成员之间复用 VS Code Dev Containers 的工具链，最简做法是把工具声明放进项目的 .devcontainer/devcontainer.json，通过 features 对象引用可复用的 Dev Container Features。仓库成员执行重开或重建容器后，就会按同一份配置安装 Node.js、GitHub CLI 等工具，不必在每台开发机里重复手工安装。

本文完成后的可见结果是：项目包含可提交版本库的容器配置，VS Code 左下角显示已连接开发容器，重建后声明的工具可以正常查询版本。

VS Code 官方文档：https://code.visualstudio.com/docs/devcontainers/containers

Features 官方索引：https://containers.dev/features

开始前先确认最终状态

Dev Container Feature 是一组可共享的安装脚本与开发容器元数据。它通过 OCI Artifact 形式分发，在 devcontainer.json 中用 Feature ID 引用。这里选择官方维护的三个能力：

• common-utils:2：常用命令行工具与基础配置。
• node:2：Node.js 运行时，并通过选项指定工具版本。
• github-cli:1：GitHub CLI。

冒号后的数字是 Feature 引用的主版本，不等同于工具自身版本；例如 Node.js 的版本放在该 Feature 的 version 选项中。团队要复用配置，应把 .devcontainer 目录与业务代码一起提交，而不是依赖某位成员的全局设置。

第1步：创建项目级容器配置

在项目文件夹已打开的前提下，按 F1 打开命令面板，执行 Dev Containers: Add Dev Container Configuration Files...。随后选择 Add configuration to workspace，再选择一个与项目兼容的基础镜像配置。

如果项目已经存在 .devcontainer/devcontainer.json，不要重新生成；直接执行 Dev Containers: Open Container Configuration File 打开现有文件即可。

成功状态：资源管理器中出现 .devcontainer 文件夹，里面包含 devcontainer.json。此时先不要急着重建，继续补齐 Features。

第2步：把可复用工具写进 Features

可以按 F1 执行 Dev Containers: Configure Container Features，在列表中搜索并勾选需要的 Feature；也可以直接编辑配置。下面是一份紧凑的项目级写法：

{
  "name": "team-node-workspace",
  // 以稳定的开发容器基础镜像作为工具承载环境
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
  "features": {
    // 主版本写在 Feature ID 后，具体选项由该 Feature 定义
    "ghcr.io/devcontainers/features/common-utils:2": {},
    "ghcr.io/devcontainers/features/node:2": {
      // 团队统一使用 Node.js 22，避免成员环境漂移
      "version": "22"
    },
    "ghcr.io/devcontainers/features/github-cli:1": {}
  },
  "customizations": {
    "vscode": {
      // 该扩展会安装到容器侧的 VS Code 环境
      "extensions": ["dbaeumer.vscode-eslint"]
    }
  }
}

成功状态：features 节点能获得配置补全，三个 Feature ID 都位于同一个对象中。若通过界面选择，保存后同样会写回配置文件。

第3步：重建容器并等待重新连接

修改 .devcontainer 下的配置后，需要重建才会安装新增 Feature。按 F1，执行 Dev Containers: Rebuild Container。如果当前还没有进入容器，则先执行 Dev Containers: Reopen in Container；首次创建也会按配置构建环境。

重建期间不要再次触发相同命令。完成后，VS Code 会重新打开项目，左下角远程状态区显示开发容器名称，资源管理器仍指向原项目工作区。

成功状态：远程状态区显示已连接容器，命令面板可以打开当前容器配置，项目文件可正常编辑。

第4步：核对 Feature 是否真正可用

连接容器后，在 VS Code 集成终端中查询工具版本。下面的命令只是验收，不负责安装；安装来源仍然是 features 配置。

# 确认 Node.js 来自重建后的开发容器环境
node --version

# 确认 GitHub CLI 已由 Feature 安装
gh --version

# 确认常用基础工具可以调用
git --version

验收时不要只看构建结束提示。应同时确认三项：左下角确实处于容器连接状态；版本命令能返回结果；关闭并再次执行 Reopen in Container 后工具仍然存在。这样才能证明配置可复用，而不是某次手工安装残留。

异常时按这张表修正

排查入口统一放在命令面板：执行 Dev Containers: Show Container Log 查看构建与安装记录。不要把敏感令牌直接写进 devcontainer.json；需要认证时使用宿主机凭据转发、环境变量注入或团队既有的密钥管理方式。

把可复用配置归档到仓库

最终提交至少应包含 .devcontainer/devcontainer.json，以及配置引用的 Dockerfile 或 Compose 文件。提交说明中写清基础镜像、Feature ID、关键选项和验收命令。团队升级工具时，优先在分支中修改 Feature 主版本或工具版本选项，重建验收后再合并。

如果某个工具每个项目都需要，可以评估 VS Code 用户设置 dev.containers.defaultFeatures；但它属于个人设置，不能替代仓库内配置。需要团队一致的工具仍应写在项目 features 中。

常见问题

Features 和 Dockerfile 应该怎么选？

可复用的开发工具优先用 Feature；需要精确控制系统包、复制文件或执行复杂构建逻辑时使用 Dockerfile。两者可以同时存在。

能否在多个项目复制同一段 features？

可以。复制 Feature ID 与选项即可复用工具组合，但仍要检查每个项目的基础镜像、CPU 架构和权限条件。

为什么修改 devcontainer.json 后没有立即生效？

配置影响容器构建，需要执行 Rebuild Container。普通的窗口重新加载不会重新安装 Feature。

是否应该一直使用 latest？

团队环境更适合固定 Feature 主版本，并按需要固定工具版本选项。这样既能接受同一主版本内的维护更新，又能避免工具跨大版本变化导致不可预期差异。

用 Features 复用开发环境的核心不是“少写几行安装命令”，而是让工具声明进入版本库，并通过重建、连接状态和版本查询形成可重复的验收闭环。