Dev Containers
“在我电脑上能跑”为什么会在重建后失效
新成员打开仓库，编辑器提示重新进入容器。窗口几分钟后亮起，终端里却没有团队约定的运行时；开发者手工安装工具后恢复工作，第二天执行 Rebuild，工具又消失了。另一个同事虽然使用同一份 .devcontainer/devcontainer.json，生成的文件却全部属于 root。CI 再次失败时，团队才发现镜像 tag、Feature、生命周期脚本、远端用户和缓存卷从未形成一份完整合同。
“把项目放进容器”只描述了运行位置。可重建的开发环境还要回答：源码挂到哪里，IDE 附着哪个容器，语言扩展在哪一侧运行，以哪个用户创建文件，首次创建和再次启动分别执行什么，端口如何到达本地，以及凭证如何在不进入镜像和仓库的情况下到达开发进程。Dev Container Specification定义的是这层开放元数据；VS Code Dev Containers、GitHub Codespaces 和其他 supporting tool 消费它，但各自支持的扩展字段并不完全相同。
因此，image、build.dockerfile 或 dockerComposeFile 只是构造入口。真正决定开发体验的是 Feature 版本、生命周期、remoteUser/containerUser、workspace、额外挂载、端口、凭证和主机能力边界。开发镜像可以包含编译器、调试器、Git、shell、语言服务和测试依赖，生产镜像则应更小、权限更窄、启动语义更确定；两者可以复用受控基础层，不能把开发工具、Docker socket 和个人凭证顺手带进生产制品。
受控启用与宿主基线
先确认主机上的容器运行时确实指向计划使用的 daemon：
docker version
docker compose version
docker context show预期客户端能访问明确的 daemon，Compose 命令可用，context 指向本机或受控远端。客户端版本存在不代表 daemon 可达；先解决 socket、Desktop/WSL 集成、远端 context、企业 CA 或代理问题，再进入 IDE。容器运行时本身的部署、镜像、volume 与 network 管理可参考本地运行时与容器工具。
在 VS Code 扩展市场搜索 Dev Containers，核对发布者为 Microsoft、扩展标识为 ms-vscode-remote.remote-containers，再按组织批准的稳定通道安装。组织若通过策略预装扩展，应同时锁定允许的发布者、更新通道和回退版本；不要让每台开发机自行追逐预发布版。安装后从命令面板确认能找到 Dev Containers: Reopen in Container、Show Container Log 与 Rebuild Container。
需要在 IDE 外复用同一合同，可按 Dev Container CLI 提供的 npm 入口安装参考实现，并记录实际版本：
npm install -g @devcontainers/cli
devcontainer --version
devcontainer read-configuration --workspace-folder .全局 npm 安装适合个人验证；团队和 CI 更适合在工具镜像或项目工具链中锁定 CLI 版本。read-configuration 用来观察归一化后的配置和 workspace mount，不应被当成严格校验器：JSONC 解析器可能忽略残缺字段并继续返回结果。CI 至少要断言归一化结果中的构造入口、用户和关键挂载，再执行 build 或 up 验证真实语义。
可以用不拉取镜像的反例确认门禁位置。把临时仓库的 .devcontainer/devcontainer.json 写成空对象后执行：
devcontainer read-configuration --workspace-folder .
devcontainer up --workspace-folder .第一条仍可能返回默认 workspace 信息；第二条应以非零退出码拒绝，并指出缺少 image、dockerFile 或 dockerComposeFile。如果流水线只运行第一条，这类配置会在开发者真正 Reopen 时才暴露。即使 up 成功，也只能证明当前 daemon 能创建环境，仍不能证明 Feature 供应链、目标 IDE 的 customizations、断点和端口行为满足项目要求。
陌生仓库的 .devcontainer 会触发镜像拉取、Dockerfile、Feature 和主机/容器生命周期脚本，点击 Reopen 之前应按主机代码执行权限审查。
元数据参考会随规范演进，Feature 参考也允许 OCI registry 中的独立发布单元持续更新。仓库必须锁定可审计的基础镜像摘要或更新策略，核对 Feature 发布者和 major，并在代表性 CPU 架构上定期重建；“配置能解析”和“昨天还能拉取”都不是长期可复现证据。
从规范到运行实例
devcontainer.json 可以位于 .devcontainer/devcontainer.json，也可按规范支持的位置组织多个定义。它描述如何创建或访问开发环境，Dockerfile 与 Compose 仍使用各自原生格式。IDE 先让容器运行，再在主容器中启动远端 Server、安装工作区扩展并执行开发命令。
用现成 image 最简单，适合团队认可的预构建开发镜像；build.dockerfile 适合安装与工作区无关、需要镜像缓存的系统工具；Compose 适合应用、数据库、消息组件等多服务联调，并通过 service 指定 IDE 真正附着的主容器。不要因为项目已有生产 Compose 就直接把 IDE 附着到任意服务，开发主服务需要稳定的工作目录、用户和长生命周期命令。
最小可运行定义
下面示例使用基础开发镜像和 Node Feature，把版本意图、扩展、端口和项目初始化放进一个可审查文件：
{
"name": "your-project-dev",
"image": "mcr.microsoft.com/devcontainers/base:ubuntu",
"features": {
"ghcr.io/devcontainers/features/node:1": {
"version": "22"
}
},
"remoteUser": "vscode",
"updateRemoteUserUID": true,
"postCreateCommand": "npm ci",
"forwardPorts": [3000],
"portsAttributes": {
"3000": {
"label": "Web app",
"onAutoForward": "notify"
}
},
"customizations": {
"vscode": {
"extensions": ["dbaeumer.vscode-eslint"]
}
}
}Feature 引用中的 :1 锁定 Feature major，不会锁定其每一次发布内容；version: "22" 又表达 Feature 所安装工具的版本，两层版本不能混为一谈。对高合规环境，应验证 OCI 发布者、Digest、Feature 源码、基础镜像摘要和上游下载；需要完全可复现时，把成熟工具安装固化到内部构建镜像并由流水线更新。
在 VS Code 命令面板执行 Dev Containers: Reopen in Container。首次构建完成后，状态栏应显示 Dev Container，集成终端执行：
id
pwd
node --version
git rev-parse --show-toplevel
npm test预期用户是 vscode，工作目录位于容器内 workspace，Node major 符合项目基线，Git 根正确，测试通过。随后启动项目并从 Ports 视图访问 3000 端口，确认访问的是容器内进程而非主机残留服务。
规范参考实现还可以在 IDE 外验证：
devcontainer up --workspace-folder .
devcontainer exec --workspace-folder . node --version
devcontainer exec --workspace-folder . npm test预期 up 返回创建环境的结构化结果，后两条在开发容器中执行。CLI 的安装方式和版本应在团队工具链中锁定；它与目标 IDE 对 customizations 的支持仍需分别验证。
三种入口如何选择
直接使用 image
image 入口最短，适合镜像已经包含稳定 OS 与公共工具的场景。优点是启动快、定义小；缺点是 tag 漂移、镜像内容不透明和定制能力有限。团队镜像应由流水线构建、扫描、签名并记录 Digest。个人不要把手工修改后的容器 commit 成“基线”。
使用 Dockerfile
Dockerfile 适合安装系统包、证书和与源码无关的工具。它在 workspace 挂载前构建，因此不能依赖仓库运行时文件做 npm ci。把稳定、昂贵、与源码无关的安装放在 Dockerfile；把依赖锁文件相关步骤放在生命周期脚本或专门的预构建流程。
{
"build": {
"dockerfile": "Dockerfile",
"context": ".."
},
"remoteUser": "devuser"
}context 决定 Docker build 能看到哪些文件，也决定缓存失效和敏感文件进入构建上下文的风险。配套 .dockerignore 必须排除 .git、本地凭证、构建输出和不必要的大文件。
使用 Docker Compose
Compose 入口通过 dockerComposeFile 指向一个或多个文件，用 service 指定 IDE 附着的主服务，runServices 可限制本次环境启动哪些服务：
{
"dockerComposeFile": [
"../compose.yaml",
"compose.devcontainer.yaml"
],
"service": "app",
"runServices": ["app", "db"],
"workspaceFolder": "/workspace",
"shutdownAction": "stopCompose"
}Compose 原生负责 image/build、network、volume、environment 与服务依赖；Dev Container 元数据负责 IDE 附着、工作区、远端用户、扩展与生命周期。生产 Compose 与开发 override 可以共享服务拓扑，但开发端口、源码 bind mount、调试 capability 和长生命周期命令不应污染生产定义。
生命周期脚本：执行次数就是工程语义
规范顺序是：主机侧 initializeCommand；首次创建容器时依次执行 onCreateCommand、updateContentCommand、postCreateCommand；每次启动执行 postStartCommand；每次 IDE 附着执行 postAttachCommand。waitFor 决定 UI 至少等待到哪个创建阶段，默认等待 updateContentCommand。
initializeCommand 在主机或云 VM 上执行，权限和工具链不受容器隔离，必须非常克制。postCreateCommand 适合根据 workspace 锁文件安装依赖；postStartCommand 适合每次容器启动都需要的幂等服务；postAttachCommand 可能在多次连接时重复运行，不适合迁移数据库、创建共享管理员或追加配置。
脚本失败要保留非零退出码，不要用 || true 把环境伪装成成功。对象形式中的多个命令可以并行，彼此有依赖时必须写成单条顺序脚本。长逻辑放进仓库脚本并接受 shellcheck、测试和代码审查，devcontainer.json 只调用稳定入口。
containerUser 与 remoteUser 不是同义词
containerUser 改变容器整体启动用户，相当于容器原生用户决策；Compose 场景通常由服务的 user 表达。remoteUser 不改变已有 ENTRYPOINT，而是决定 IDE Server、生命周期脚本、终端、任务和调试等远端进程使用哪个用户，默认等于容器用户。
这一区分允许 ENTRYPOINT 先以需要的身份初始化，再让开发者以普通用户工作，但也会产生权限错位：入口进程创建 root 文件，remoteUser 无法修改；或者生命周期脚本以普通用户执行，却试图写 /usr/local。修复方式是把系统安装移到镜像构建阶段，把可变缓存放到用户可写目录，并显式设置目录 owner，而不是把 remoteUser 改回 root。
updateRemoteUserUID 在本地 Linux bind mount 场景可让指定用户 UID/GID 与主机用户匹配，减少宿主文件变成陌生 owner 的问题。它是实现可选行为，远端 Docker、云环境、user namespace 与非 bind mount 场景可能不同。团队必须用实际创建文件的 UID、宿主权限和重建结果验证，不能只看 JSON 键存在。
挂载决定数据和主机权限边界
默认 workspace mount 让源码在容器重建后仍可恢复。workspaceMount/workspaceFolder 决定源码来源与 IDE 打开的路径；额外 mounts 可持久化包缓存、注入只读配置或连接主机资源。
{
"workspaceMount": "source=${localWorkspaceFolder},target=/workspace,type=bind",
"workspaceFolder": "/workspace",
"mounts": [
"source=your-project-npm-cache,target=/home/vscode/.npm,type=volume"
]
}bind mount 直接暴露主机路径，容器内进程按挂载权限读取或修改；named volume 与主机路径解耦，但会在容器删除后继续占用空间并保存旧缓存。每个 mount 都要有用途、owner、读写属性、保留期限和清理命令。不要把整个 home、.ssh、云配置目录或生产 kubeconfig 批量挂入容器。
在 Windows/macOS Desktop、WSL、远端 Docker 与 Linux 本机上，文件共享、大小写、UID/GID 和 I/O 性能不同。大仓可以评估容器 volume 中 clone，但要明确源码备份、Git 凭证和 IDE 打开路径；不能为了性能让源码只存在匿名 volume，最后无人知道如何导出。
端口：forward 不等于 publish
forwardPorts 请求 supporting tool 把容器端口转到开发者本地，portsAttributes 控制标签、自动转发行为和本地端口偏好。它服务 IDE 会话，不等于 Docker ports/-p 对主机或网络发布端口。
Compose 的 ports 可能让服务在 Docker 主机接口上长期监听；IDE 转发通常只面向当前用户。开发数据库、管理后台和调试协议优先使用本地可见转发，不要为了“VS Code 没识别到”改成 0.0.0.0 公网发布。验证要同时查看容器监听、Docker publish 和 IDE Ports 三层，退出时分别清理。
Docker socket、privileged 与 capabilities
把 /var/run/docker.sock 挂进开发容器，容器里的进程就能要求主机 daemon 创建特权容器、挂载主机目录并读取其他容器数据。Docker Engine 安全说明因此把 daemon 控制权限定给可信用户。即使当前 remote user 不是 root，能访问 socket 也不能视为低权限。
需要在开发容器内构建或运行容器时，先比较三种方案：在主机侧执行受控任务；通过受保护的远端 daemon/BuildKit 使用最小凭证；确有必要时使用经过审查的 Docker-outside-of-Docker 或 rootless Docker-in-Docker Feature。每种方案都要记录 daemon 所在位置、缓存归属、网络、凭证与清理责任。
privileged: true 会显著扩大容器能力，不应作为“调试不工作”的通用修复。优先只增加确实需要的 capAdd，配合默认 seccomp/AppArmor/SELinux；例如调试器需要的权限也应按目标内核和官方调试文档验证。任何 securityOpt 放宽都必须有威胁分析、替代方案和退出条件。
陌生仓库一旦同时请求 Docker socket、privileged、主机 home 挂载和生命周期脚本，应按主机代码执行权限审查，而不是普通编辑器配置审查。
Secrets：规范声明需求，平台负责交付
Dev Container 元数据参考中的 secrets 属性是“推荐 Secret”的元数据，键名可以带描述和文档；它不把值写入容器，也不定义所有平台都相同的 Secret 存储。真正的值可能由本地环境、IDE、Codespaces 或组织平台注入。
{
"secrets": {
"PACKAGE_READ_TOKEN": {
"description": "只读开发包仓库令牌",
"documentationUrl": "https://example.com/docs/dev-token"
}
},
"remoteEnv": {
"PACKAGE_READ_TOKEN": "${localEnv:PACKAGE_READ_TOKEN}"
}
}这里的域名是占位符。${localEnv:...} 只是把主机环境变量复制到远端进程环境，值仍可能被子进程、日志、崩溃信息或调试器读取。敏感度更高的凭证优先使用平台 Secret、短期 token、OIDC/工作负载身份或只读文件挂载，并在任务结束后撤销。不要把真实 .env、私钥或 registry auth 写进镜像层、Dockerfile ARG、Feature option、Compose 文件和仓库脚本。
Git 凭证转发、SSH agent 和 GPG agent 也属于凭证代理。它们比复制私钥更容易撤销，但容器内受信进程可能在会话期间借用代理。只对可信仓库启用，并验证关闭环境后代理不可继续使用。
重建、恢复与彻底清理
修改 devcontainer.json、Dockerfile、Compose 或 Feature 后，VS Code 不会自动重建。执行 Dev Containers: Rebuild and Reopen in Container，预期手工安装在旧容器可写层中的内容消失，而镜像、Feature、生命周期脚本和挂载中的声明内容恢复。若工具只有旧容器存在，就说明它没有进入环境合同，应移入镜像、Feature 或幂等生命周期脚本。
构建失败时先执行 Dev Containers: Show Container Log，必要时 Open in Recovery Container 或本地打开仓库修配置。排障顺序是 daemon/context、镜像拉取与证书、build context、Feature、创建参数、mount、用户、生命周期、IDE Server；不要一上来运行全局 docker system prune。
日常退出可选择 Reopen Folder Locally/Close Remote Connection，并按定义的 shutdownAction 确认容器是停止还是保留。Compose 的 stopCompose 只停止本环境服务，不必然删除容器、network、volume、镜像和 build cache。
彻底清理前先盘点，不按模糊名称批量删除：
docker ps -a
docker volume ls
docker image ls
docker builder du记录本次环境的容器 ID、Compose project、named volume 和镜像。确认没有其他工作区复用后，再删除明确对象：
docker rm -f <dev-container-id>
docker volume rm your-project-npm-cache
docker image rm <verified-dev-image-id>Compose 环境应从其定义目录使用明确 project 执行 docker compose down；是否加 --volumes 必须由数据保留策略决定。不要在共享 daemon 上运行无范围的 prune。最后撤销临时 token、关闭转发端口、检查源码仍可从 Git 恢复，并重新执行 docker ps -a/docker volume ls 证明目标对象已消失。
接入真实项目
项目接入从“仓库事实”开始：选择一个 CI 也认可的运行时版本，锁定依赖，提供健康检查或测试入口，再把开发专用工具叠加上去。postCreateCommand 调用仓库脚本，例如 ./scripts/dev/bootstrap.sh；脚本必须幂等、无交互、失败可见，并且不创建共享生产资源。
Compose 项目应把 app 作为 service，依赖服务使用开发专用账号、volume 和 network。IDE 扩展只列确实需要在容器运行的工作区扩展；格式化规则与检查命令仍由仓库配置和 CI 兜底，不能只依赖某个扩展版本。
项目第一次接入应完成一次干净 clone、Reopen、依赖安装、测试、应用启动、断点、端口访问、重建和清理。重建后再次运行相同命令，输出的 runtime major、测试结果和工作区路径应一致。对 x86/ARM 混合团队，还要分别构建，确认基础镜像和 Feature 提供对应架构。
常见失败：从哪一层坏掉就在哪一层修
Cannot connect to the Docker daemon
退出 VS Code，先在同一主机和同一用户执行 docker context show、docker version。若 CLI 失败，修 daemon、socket 权限、Desktop/WSL 集成或远端 context；若 CLI 成功，检查 VS Code 启动时继承的 PATH、DOCKER_HOST 和 context。不要用 sudo code 提权整个编辑器。
Feature 安装失败或版本漂移
从构建日志定位 OCI 拉取、目标架构、基础发行版、包管理器、上游下载或 GPG key。确认 Feature 引用的发布者和 major，再在代表镜像中单独构建。修复后用无缓存验证一次，并把可接受的版本/Digest 纳入依赖更新流程。
postCreateCommand 每次都很慢
判断是容器确实被重新创建、依赖缓存没有挂载、锁文件变化，还是脚本本身不幂等。系统工具移到 Dockerfile，项目依赖保留在锁文件驱动脚本，昂贵缓存用有 owner 的 volume；不要把整个 node_modules 在不同 OS/CPU 间共享。
容器里创建的文件宿主无法修改
在容器执行 id，在宿主查看文件 UID/GID，核对 containerUser、remoteUser、Compose user 与 updateRemoteUserUID。修正镜像用户和挂载目录 owner 后重建。把所有进程改成 root 只会把权限债务扩大。
Rebuild 后工具消失
这说明工具只存在旧容器可写层。根据性质把它写入 Dockerfile、可信 Feature、生命周期脚本或项目依赖，再重建两次验证。手工安装只适合临时诊断，不能成为团队基线。
服务在容器内可访问，本地不可访问
先在容器确认监听地址和端口，再检查 forwardPorts/Ports 视图，最后检查 Docker ports、本地端口冲突与代理。仅监听错误 interface 时修应用配置；不要无条件增加 host network 或 privileged。
Compose 关闭后数据或容器仍在
检查 shutdownAction、Compose project name、runServices 和外部 volume。停止、删除容器、删除 network、删除 volume 是不同动作。先确认数据 owner，再用明确 project 与对象名清理。
架构取舍与深水区
Dev Container 最适合工具链复杂、多人跨平台、需要新成员快速复现或本地与云工作区共享定义的项目。简单脚本库、只需一个系统运行时的项目，使用版本管理器和仓库任务可能更轻。容器不能消除宿主 kernel、CPU 架构、daemon、安全策略和文件系统差异。
预构建团队镜像能缩短启动并集中扫描，但会引入镜像仓库、发布节奏和陈旧风险；每次本地 Dockerfile 构建透明度高，却会消耗新人时间和公网带宽。成熟团队通常把稳定系统层预构建，把项目依赖按锁文件在创建阶段恢复，并用 CI 定期执行 devcontainer build 或等价验证。
多服务 Compose 能贴近联调拓扑，但每位开发者启动完整数据库、消息队列和观测栈会消耗大量 CPU、磁盘与端口。runServices 只启动必要依赖，重型共享服务使用开发专用环境与最小权限；不要让开发容器通过挂载生产 kubeconfig 或 Docker socket 跨越隔离边界。
最大的安全误区是“容器已经隔离”。bind mount 暴露源码和主机目录，socket 暴露 daemon，privileged/capabilities 改变 kernel 权限，生命周期脚本执行仓库代码，代理注入真实身份。Dev Container 应按可执行供应链资产进行 Review、Secret scan、镜像扫描和变更审批。
团队治理与长期维护
团队应为 .devcontainer 指定 owner，所有基础镜像、Feature、mount、capability、生命周期和端口变更都经过代码审查。Dependabot 或等价工具可以提出 Feature/镜像更新，但合并前必须在代表平台完成构建、测试、断点、端口、重建和清理。
建立支持矩阵：Windows+WSL/Docker Desktop、macOS、Linux、x86_64、ARM64 中哪些是正式支持，哪些仅尽力而为；再记录 VS Code/Dev Containers/CLI 版本、daemon 类型、镜像来源、代理 CA 和最大资源预算。目标工具不支持某个 spec 属性时要显式降级，不能假设所有 supporting tools 完全兼容。
环境合同还要有退出责任：容器和缓存保留多久、named volume 是否含数据、镜像由谁清理、云或远端 daemon 谁付费、Secret 何时撤销。新人完成首次任务后应能证明重建一致、无真实 Secret 进入 Git/镜像、无额外特权、退出后端口关闭，删除后源码仍可恢复。
devcontainer.json 的通用 spec 属性与 IDE 专用 customizations 已区分。image、Dockerfile 或 Compose 入口有明确选择理由，Compose service 指向开发主容器。Feature、基础镜像和工具版本可追溯，供应链与多架构经过验证。
生命周期脚本的执行位置、顺序、次数、幂等和失败语义清楚。containerUser、remoteUser、UID/GID 和挂载文件 owner 经实际创建文件验证。forward 与 publish 已区分，退出后端口、进程和依赖服务有清理证据。
Docker socket、privileged、capabilities、主机挂载均有最小权限评审。secrets 只声明需求，真实值不进入 Git、镜像层、日志和同步设置。Rebuild 后工具链、测试和调试仍一致，彻底清理不依赖全局 prune。