开发容器

是什么，为什么存在

开发容器（Dev Container） 是用来开发应用的容器环境， 而不是应用最终部署时必须采用的打包格式。它在容器镜像或 Docker Compose 的基础上增加开发期元数据， 例如编辑器如何连接、工作区放在哪里、要转发哪些端口，以及创建后执行哪些命令。

它解决的是环境定义散落的问题。只有 README 时，安装步骤会随着操作系统、执行顺序和时间而分叉； 把环境定义提交到仓库后，工具可以从同一个声明创建本地环境、云端工作区或 CI 任务。 这会减少差异，但不会自动得到字节级相同的环境，因为镜像标签、Feature、软件源和宿主机仍可能变化。

当项目依赖特定运行时、系统包、数据库或编辑器扩展时，你会遇到开发容器。 只有一个成熟的版本管理器就能满足需求时，容器的构建、磁盘和权限成本可能不划算； 需要硬件设备、桌面应用或复杂企业网络时，也要先确认实现工具是否能传递这些宿主机能力。

工作原理

规范通常从仓库根目录下的 .devcontainer/devcontainer.json 读取配置，也支持根目录的 .devcontainer.json。配置选择一个基础：直接引用 image、用 build 指向 Dockerfile， 或用 dockerComposeFile 选择一组服务。三种形式都描述开发环境，只有 Compose 形式还要用 service 指定编辑器和生命周期命令连接的主服务。

创建工具会解析配置、替换 ${localEnv:...} 等变量，并把镜像元数据、 Dev Container Feature 提供的元数据与仓库配置合并。 Feature 是可复用的安装单元，通常包含 devcontainer-feature.json 和安装脚本。 它会在镜像构建阶段执行代码，因此引用 Feature 与引用构建依赖一样需要版本和来源审查。

环境首次创建后，容器内命令按 onCreateCommand、updateContentCommand、 postCreateCommand 的顺序运行。恢复已经存在的容器时会运行 postStartCommand； 工具每次成功连接后会运行 postAttachCommand。initializeCommand 不在容器中运行， 它在源码所在的宿主机上执行，而且一次会话中可能执行多次。

这些属性统称为 生命周期命令（lifecycle command） 。 字符串值通过 /bin/sh 运行，数组值直接执行程序，不经过 shell；对象中的多个命令并行运行， 且每个命令都必须成功。某一阶段失败后，后续生命周期阶段不会继续执行。

containerUser 决定容器中所有操作采用的用户； 远程用户（remote user） 由 remoteUser 指定， 用于生命周期脚本以及编辑器或工具启动的进程。没有设置 remoteUser 时，它默认跟随容器用户。 两者分开后，容器入口点可以使用一种身份，日常开发进程使用另一种身份。

containerEnv 在创建容器时写入环境，容器入口点也能看到；remoteEnv 由支持工具添加到远程进程， 可以在容器存活期间改变。workspaceMount 决定源码如何进入容器，workspaceFolder 决定远程进程的工作目录。 forwardPorts 请求支持工具把容器端口转发给使用者，但它不是 Docker 的端口发布规则。

开发容器保留 Docker 的边界。绑定挂载仍把宿主机路径暴露给容器，挂载 Docker 套接字通常等价于把宿主机 Docker 控制权交给容器，privileged 和额外 capability 会进一步扩大权限。 所以开发容器首先是环境管理机制，不能默认视为处理不可信代码的安全沙箱。

示例

从单镜像配置开始

下面的配置选择 Node 24 镜像，并让容器进程和远程工具都使用镜像中的 node 用户。 数组形式的 postCreateCommand 不经过 shell；端口属性只告诉支持工具如何处理端口 3000。 配置保留在仓库中，因此代码评审能看到环境权限和初始化行为的变化。

检查脚本读取的就是提交后的配置，不是另外维护的一份说明。 它只能证明 JSON 能解析并确认几个关键字段；真正的发布门禁还应运行 devcontainer build 或 devcontainer up，因为只有构建过程会解析镜像、Feature、用户和挂载的组合。

让创建命令快速失败

第一份配置引用了这个创建脚本。它先验证实际运行时，再执行项目安装步骤；这里用短输出代替安装， 让示例保持自包含。真实 Node 项目应在验证通过后运行 npm ci，并把 package-lock.json 提交到仓库。

const expectedMajor = 24;
const actualMajor = Number(process.versions.node.split(".")[0]);

if (actualMajor !== expectedMajor) {
  throw new Error(`expected Node ${expectedMajor}, got ${process.version}`);
}

console.log(`runtime=${process.version}`);
console.log("setup=ready");

runtime=v24.14.0
setup=ready

命令失败会阻止后续生命周期阶段，错误不会被 || true 隐藏。 脚本放在源码树中，比一条不断增长的 shell 字符串更容易测试和评审。 如果工具必须等到依赖安装完成后再连接，可以显式设置 waitFor: "postCreateCommand"； 默认等待点是 updateContentCommand，所以不能假设连接一定晚于 postCreateCommand。

用 Compose 增加数据库

多服务环境把开发主容器与数据库放在同一个 Compose 项目中。 app 通过服务名 db 和端口 5432 访问 PostgreSQL；数据库没有 ports，因此不会因此直接发布到宿主机。 健康检查让 depends_on 等待数据库可接受连接，而不只是等待容器进程启动。

services:
  app:
    image: node:24-bookworm-slim
    user: node
    command: sleep infinity
    volumes:
      - ..:/workspace
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:17-alpine
    environment:
      POSTGRES_DB: app
      POSTGRES_USER: app
      POSTGRES_PASSWORD: local-only
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app -d app"]
      interval: 2s
      timeout: 2s
      retries: 10
    volumes:
      - postgres-data:/var/lib/postgresql/data

volumes:
  postgres-data:

{
  "name": "node-with-postgres",
  "dockerComposeFile": "compose.yaml",
  "service": "app",
  "workspaceFolder": "/workspace",
  "remoteUser": "node",
  "shutdownAction": "stopCompose",
  "forwardPorts": [3000]
}

docker compose -f .devcontainer/compose.yaml config --quiet
docker compose -f .devcontainer/compose.yaml config --services

db
app

docker compose config --quiet 验证并解析 Compose 文件，第二条命令列出依赖排序后的服务。 这还没有证明数据库能启动；CI 必须继续创建环境，并从 app 内部做一次实际连接检查。 示例密码只适用于可丢弃的本地数据库，生产凭据不能写进配置。

陷阱

延伸阅读

• Development Container 规范
• devcontainer.json 元数据参考
• Dev Container Features 规范
• Dev Container 锁文件规范
• Dev Container CLI
• VS Code Dev Containers 文档