Dev Containers 与 Codespaces：把开发环境变成可验证合同
新人环境“能打开”为什么仍然不能交付
新同事在 Codespaces 中打开仓库，编辑器、Node.js 和数据库都已启动，看起来比手工安装顺利得多。第一次提交却暴露出三个问题：容器以 root 创建文件，本地无法修改；updateContentCommand 依赖个人 Token，预构建一直失败；端口被公开转发，测试数据可从外网访问。问题不在容器能否创建，而在团队没有把开发环境当成一份需要审查、验证和退出的合同。
devcontainer.json 描述开发工具怎样创建或连接开发容器。镜像或 Dockerfile 决定系统层，Features 叠加可复用工具，生命周期命令恢复项目状态，用户与挂载决定文件归属，端口决定网络暴露，平台负责提供 VM、身份与 Secret。Codespaces 可以消费这份定义，但云端宿主、计费、数据保留和权限模型不会因此变成本地 Docker。
一份可靠合同要保持这些不变量：干净 clone 能创建；重建后工具链和测试仍一致；仓库不含个人凭证；容器创建的源码文件可由宿主用户维护；预构建不依赖用户 Secret；停止和删除后，端口、算力、缓存与凭证都有明确归属。
从可提交的最小环境开始
先在项目中创建：
.devcontainer/
devcontainer.json
Dockerfile
scripts/dev/
bootstrap.sh.devcontainer/Dockerfile 把稳定系统工具固化进镜像：
FROM mcr.microsoft.com/devcontainers/base:ubuntu
RUN apt-get update \
&& DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends jq \
&& rm -rf /var/lib/apt/lists/*
USER vscode基础镜像在团队基线中应进一步锁定可审查的 tag 或 Digest，并通过依赖更新流程升级。不要在 Dockerfile 中使用 Token ARG 拉私有依赖，构建参数和镜像层都可能泄漏它。
创建入口只能有一个主模型：image 直接消费预构建镜像，启动快但定制必须在镜像发布链完成；build 引用 Dockerfile，适合仓库内可审查构建；dockerComposeFile 交给 Compose 创建多服务拓扑，并用 service 指定开发工具附着的主容器。不要同时保留 image 与 build 期待客户端猜优先级，也不要把数据库、消息队列和应用进程都塞进一个 Dockerfile。
devcontainer.json 建立第一版合同：
{
"name": "your-project-dev",
"build": {
"dockerfile": "Dockerfile",
"context": ".."
},
"remoteUser": "vscode",
"updateRemoteUserUID": true,
"features": {
"ghcr.io/devcontainers/features/node:1": {
"version": "22"
}
},
"containerEnv": {
"APP_ENV": "development"
},
"remoteEnv": {
"EDITOR": "code --wait"
},
"forwardPorts": [3000],
"portsAttributes": {
"3000": {
"label": "Web application",
"onAutoForward": "notify"
}
},
"postCreateCommand": "bash scripts/dev/bootstrap.sh",
"hostRequirements": {
"cpus": 2,
"memory": "4gb",
"storage": "16gb"
},
"customizations": {
"vscode": {
"extensions": ["dbaeumer.vscode-eslint"]
}
}
}Feature ID 中的 :1 只固定 major，发布方仍可在该 major 下更新内容。团队需要审查 Feature 来源与安装脚本，记录构建时解析到的版本和最终镜像 Digest，并通过依赖更新流程重建；不能把 major 标签当作不可变证据。
containerEnv 进入整个容器且在容器生命周期内静态存在，修改后通常要重建；remoteEnv 只影响支持工具启动的远端进程、终端和任务，更适合编辑器会话变量。Compose 模型的容器级变量应写在 Compose 的 environment 或受控 env_file 中，devcontainer.json 只保留 remoteEnv。这些位置都不是 Secret 存储。remoteUser 决定终端、任务和调试进程用户，containerUser 才改变容器整体运行用户；不能把二者混为一谈。
生命周期脚本必须幂等且失败可见
scripts/dev/bootstrap.sh 不应把成功藏在一串无条件继续的命令中：
#!/usr/bin/env bash
set -euo pipefail
test -f package-lock.json || {
echo "package-lock.json is required" >&2
exit 23
}
npm ci
npm test
printf 'bootstrap_ok node=%s uid=%s\n' "$(node --version)" "$(id -u)"生命周期顺序影响预构建和凭证：initializeCommand 在宿主执行，后续启动也会执行，并且一次会话中可能运行多次；onCreateCommand、updateContentCommand、postCreateCommand 在容器首次创建链路中依次执行；postStartCommand 每次成功启动后执行；postAttachCommand 每次工具连接后执行。前一阶段非零退出时，后续阶段不会继续。waitFor 默认只要求工具等待到 updateContentCommand，并不改变脚本顺序；如果把一个阶段写成对象，对象内命令会并行执行，彼此有依赖的步骤必须留在同一脚本中串行处理。
系统包进入 Dockerfile，可信通用工具进入固定 major 的 Feature，锁文件依赖进入幂等 bootstrap。数据库迁移、创建共享云资源和发布操作不能藏进生命周期脚本，因为一次重建或 prebuild 就可能产生外部副作用。
本地正向实验：创建、验证、重建
安装支持 Dev Container Spec 的客户端，或使用官方 npm 包提供的 devcontainer CLI。团队环境应记录实际安装版本并在升级窗口复测，不让全局工具静默漂移：
npm install --global @devcontainers/cli
devcontainer --version先检查 Docker/Podman 兼容入口，再从仓库根执行：
docker version
devcontainer --version
devcontainer read-configuration --workspace-folder .
devcontainer up --workspace-folder .
devcontainer exec --workspace-folder . bash -lc \
'node --version && id && test "$APP_ENV" = development && npm test'预期 read-configuration 和 up 退出 0，容器内输出约定的 Node major、非 root 用户、APP_ENV 与通过的测试。再创建文件验证 UID/GID：
devcontainer exec --workspace-folder . bash -lc \
'printf "uid=%s gid=%s\n" "$(id -u)" "$(id -g)" > .devcontainer-user-check'
ls -ln .devcontainer-user-check
rm -f .devcontainer-user-check宿主应能直接修改和删除文件。若 owner 变成不可维护的 root 或映射 UID，先核对镜像用户、remoteUser、containerUser、updateRemoteUserUID 和 Compose user，不要用 chmod -R 777 掩盖设计错误。
重建是最重要的正向验收。手工进入容器安装一个临时工具，然后删除并重新创建环境；临时工具应消失，Dockerfile、Feature、锁文件和 bootstrap 声明的工具应恢复。若重建后只有某位开发者能运行，环境合同仍未成立。
反向实验：让生命周期失败在正确位置
在可丢弃的临时 clone 中把 package-lock.json 重命名后执行。--remove-existing-container 很关键，否则 CLI 可能复用已经完成创建阶段的容器，使反例假通过：
set -eu
backup=package-lock.json.te05-backup
test ! -e "$backup"
mv package-lock.json package-lock.json.te05-backup
restore_lock() {
test ! -e "$backup" || mv "$backup" package-lock.json
}
trap restore_lock EXIT
set +e
devcontainer up --remove-existing-container --workspace-folder . \
> .te05-devcontainer.log 2>&1
rc=$?
set -e
restore_lock
trap - EXIT
printf 'up_rc=%s\n' "$rc"
grep -F 'package-lock.json is required' .te05-devcontainer.log
rm -f .te05-devcontainer.log
test "$rc" -ne 0
devcontainer up --remove-existing-container --workspace-folder .预期 up_rc 非零且日志包含明确原因。如果客户端返回成功、后续命令仍执行或只在编辑器通知里显示模糊失败，团队无法把它接入自动验证。反向实验只移动项目锁文件并在同一脚本中恢复；中断时先确认 .te05-backup 存在，再手工改回，禁止对仓库执行无范围删除。
多服务项目使用 Compose，而不是塞进一个容器
应用需要数据库时，让 Compose 管拓扑，Dev Container 只连接开发主服务：
name: your-project-dev
services:
app:
build:
context: ..
dockerfile: .devcontainer/Dockerfile
command: sleep infinity
volumes:
- ..:/workspace:cached
- node-cache:/home/vscode/.npm
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: 3s
timeout: 2s
retries: 20
volumes:
node-cache:对应配置：
{
"name": "your-project-compose-dev",
"dockerComposeFile": "compose.yaml",
"service": "app",
"runServices": ["app", "db"],
"workspaceFolder": "/workspace",
"shutdownAction": "stopCompose",
"remoteUser": "vscode",
"postCreateCommand": "bash scripts/dev/bootstrap.sh"
}dockerComposeFile 数组按顺序合并，后面的文件可以覆盖前面；service 是 IDE 附着目标，runServices 控制需要启动的依赖。shutdownAction: stopCompose 只停止服务，不等于删除 named volume。项目数据重置必须由 owner 明确执行 docker compose -p your-project-dev down --volumes，并先用 docker volume ls 确认没有其他环境复用。
Mount、端口与特权决定真实隔离边界
工作区 bind mount 让容器内代码直接修改宿主源码；named volume 适合依赖缓存，但会在容器删除后保留。不要挂载整个 home、生产 kubeconfig、云凭证目录或 Docker Socket。确需 Socket 的构建工具可以控制宿主 daemon，风险接近主机代码执行，应使用专用低信任环境或独立 daemon。
forwardPorts 是支持工具建立的转发，不等于 Docker ports 发布。Codespaces 还会为端口设置可见性；开发服务应默认私有，只有经过授权的演示端口才扩大可见范围。应用若只监听 127.0.0.1 或错误 interface，端口视图存在也可能访问失败，应先在容器执行 ss -lntp 和本地 curl，再检查转发策略。
调试器需要额外能力时，先增加单个 capAdd 并验证；privileged、securityOpt 放宽和宿主网络不是“调试不工作”的通用答案。陌生仓库同时请求 Socket、privileged、home mount 和生命周期脚本时，应按主机代码执行进行安全审查。
Secret 只声明需求，不把值写进合同
配置可以声明开发环境需要哪些 Secret：
{
"secrets": {
"PACKAGE_READ_TOKEN": {
"description": "Read-only package registry credential"
}
}
}这段元数据只会提示用户准备推荐的 Secret，不会保存或注入值。真实值由本地客户端、Codespaces repository/organization secret 或短期身份机制交付。不要写进 devcontainer.json、Dockerfile ARG、Feature option、Compose、Dotfiles 或日志。把 ${localEnv:NAME} 用在 containerEnv、remoteEnv 等属性时，会把客户端所在宿主的变量送入容器或工具进程；云端客户端所指的宿主也在云端，不能假设它能读取开发者笔记本环境。容器内可信代码仍可读取注入值，因此只适合已评估的短期最小权限凭证。
Codespaces prebuild 阶段会执行到 onCreateCommand 和 updateContentCommand，不会执行 postCreateCommand，也拿不到用户级 Secret。预构建需要的变量只能使用明确授权的 Codespaces repository/organization secret；需要用户身份的动作放到创建者接管后的 postCreateCommand 或显式登录流程。Secret 轮换后要停止并重启既有 Codespace，验证旧终端和缓存中没有继续可用的副本。Fork 创建的环境和没有仓库写权限的用户还会触发更严格的 Secret 边界，不能把主仓库成功结果外推过去。
Codespaces：同一合同，另一套宿主责任
仓库存在 .devcontainer/devcontainer.json 后，可从 GitHub 仓库的 Codespaces 入口或 CLI 创建：
gh codespace create --repo your-org/your-project --branch main
gh codespace list
name="${CODESPACE_NAME:?set the exact codespace name}"
gh codespace ssh --codespace "$name"创建后在远端执行与本地完全相同的合同检查：runtime major、id、锁文件安装、测试、端口、重建和清理。平台默认环境变量、仓库令牌和网络位置不同，不能用“配置文件相同”代替等价验证。
Dotfiles 是个人定制，不是项目基线。Shell 主题、别名可以放个人 Dotfiles；编译器、构建命令、格式化器和测试工具必须由项目环境声明。Dotfiles 脚本同样会执行代码，组织需要说明允许来源、失败处理和离职后的数据边界。
Prebuild 用存储换等待时间
预构建按仓库、分支、devcontainer.json 配置和区域生成。管理员选择触发方式、区域和保留版本后，GitHub Actions 构建模板；onCreateCommand 适合稳定的一次性准备，updateContentCommand 适合随源码更新的增量任务。
启用前先测量冷启动中镜像拉取、Feature、依赖安装和编译各占多少时间。只有可共享且不含用户身份的昂贵步骤进入 prebuild。每个区域和保留版本都会增加存储，Fork 的 prebuild 也可能由个人承担费用；团队应根据活跃区域、分支数量、命中率和等待时间决定，而不是对所有分支、所有区域开启。
反向验收要故意让 updateContentCommand 缺少依赖，确认 prebuild Workflow 非零、通知能到 owner。最新构建失败后，平台可能继续使用同一组合下较早的成功 prebuild；因此新 Codespace “启动很快”不是修复证据，必须核对 .prebuild 状态、提交 SHA 和依赖版本。修复后等待新 Workflow 成功，再新建 Codespace 证明没有继续命中陈旧模板。
休眠、保留与数据边界
停止 Codespace 终止计算计费，但存储仍可能保留；自动删除策略决定未使用环境何时销毁。未提交修改、home 目录、扩展缓存和转发配置不能被当作永久资产。离开前提交或导出需要保留的源码，先停止环境并撤销专用临时凭证，再删除目标 Codespace：
name="${CODESPACE_NAME:?set the exact codespace name}"
gh codespace stop --codespace "$name"
gh codespace delete --codespace "$name"
gh codespace list最后一条命令应证明目标实例不再存在。删除 Codespace 会停止后续存储增长，但不会抹去本计费周期已经累计的使用量；repository/organization Secret 也不会因为删除一个环境而自动删除。
组织治理至少限制可用 machine type、创建范围、端口可见性、idle timeout、retention、基础镜像来源和预算。敏感仓库还要评估数据驻留、私网访问、审计日志、浏览器剪贴板和扩展遥测。云开发环境能降低开发机差异，但会把源码、缓存和会话身份放到第三方计算边界，安全 owner 与采购 owner 都要参与决策。
从故障证据定位哪一层坏了
创建阶段一直卡住
先读 Dev Container 创建日志，按基础镜像、Feature、Dockerfile、mount、用户、生命周期顺序定位。宿主能拉镜像而 Codespaces 失败时，检查云端 Registry 权限、企业 CA 和 prebuild Secret，不要把个人 Token 写进仓库救火。
Rebuild 后工具消失
工具只装在旧容器可写层。系统工具移入 Dockerfile，通用工具使用可信且固定 major 的 Feature，项目依赖由锁文件和 bootstrap 恢复；连续重建两次验证幂等性。
本地成功，Codespaces prebuild 失败
重点检查用户级 Secret、宿主路径、CPU 架构和只在 Dotfiles 中存在的命令。把预构建步骤改为不依赖用户身份的仓库事实，再由 postCreateCommand 完成用户阶段。
端口存在但页面不可达
在容器内检查进程、监听地址和 curl，再看 forwardPorts、端口可见性与组织策略。不要直接增加 Docker ports 或公开可见性，这可能绕开平台访问控制。
云账单持续增长
按 owner、仓库、machine type、运行时长、存储、prebuild 区域与保留版本拆账。先收紧 idle timeout 和 retention，再减少低命中 prebuild 区域与版本；不能只要求开发者“记得关”。
架构取舍与长期治理
工具链复杂、跨平台差异大、新人频繁加入或本地与云端需要共享定义时，Dev Container 的收益最大。只有一个运行时和少量依赖的项目，版本管理器加仓库任务可能更轻；容器仍共享宿主 kernel，也不会消除 CPU 架构、文件系统和 daemon 差异。
预构建镜像能降低启动时间并集中扫描，但会引入 Registry、更新节奏、缓存陈旧和存储成本。成熟做法是预构建稳定系统层，项目依赖由锁文件恢复，并在代表性的本地运行时与 Codespaces 中执行同一验收脚本。
.devcontainer 应有 CODEOWNER。镜像、Feature、mount、capability、生命周期、端口和 Secret 声明变化都经过 Review；升级在 Linux、Windows/WSL、macOS、x86_64、ARM64 的支持矩阵中验证。回退使用上一份已验证配置和镜像 Digest，同时保留源码与数据恢复路径，绝不依靠全局 prune。
Dockerfile、Feature 与项目锁文件分别承载稳定系统层、通用工具和项目依赖。image、Dockerfile 或 Compose 入口有明确工程理由，Compose 的附着 service 与依赖服务可验证。生命周期顺序、执行位置、重复次数、失败退出码和幂等性经过正反实验。
remoteUser、containerUser、UID/GID 和 bind mount owner 在代表平台验证。containerEnv 与 remoteEnv 的影响范围明确，真实 Secret 未进入 Git、镜像层和 Dotfiles。forward 与 publish 已区分，Codespaces 端口默认保持私有。
Socket、privileged、capability 和宿主挂载都有最小权限审查。本地与 Codespaces 执行同一 runtime、测试、端口、重建和清理验收。prebuild 不依赖用户 Secret，区域、触发、保留版本和失败通知有 owner。
machine type、idle timeout、retention、存储、预算和数据边界纳入组织策略。环境删除前源码可恢复，删除后端口关闭、算力释放、临时凭证撤销。