开发容器

开发容器（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文档