dev containers 统一开发环境需满足三点：devcontainer.json 必须置于 .devcontainer/ 目录下；image 和 build 字段不可共存；必须显式配置 workspacemount 或 mounts 及可靠的 postcreatecommand 检查。
Dev Containers 能统一团队开发环境，但前提是 devcontainer.json 放对位置、用对字段、不混用 image 和 build——这三个点踩错一个，Reopen in Container 按钮就灰掉，新成员卡在第一步。
devcontainer.json 必须放在 .devcontainer/ 目录下
VSCode 只认 .devcontainer/devcontainer.json 这个固定路径。放错位置是团队新人最常遇到的“无响应”问题：
- 放在项目根目录（
devcontainer.json）→ VSCode 完全无视 - 放在
.vscode/devcontainer.json→ 不触发容器启动逻辑 - 文件名写成
container.json或DevContainer.json→ 大小写敏感，Mac 上也可能失败
Windows 用户尤其注意：资源管理器无法直接创建以点开头的文件夹。必须用终端执行 mkdir .devcontainer，再用 VSCode 新建文件，或用命令面板运行 Dev Containers: Add Development Container Configuration Files 自动生成。
image 和 build 不能同时出现在 devcontainer.json 中
这是配置里最硬的校验规则。VSCode 启动时会直接报错：Invalid devcontainer.json: 'image' and 'build' cannot both be specified。选哪个取决于你是否需要定制构建过程：
- 纯用公开镜像（比如
mcr.microsoft.com/vscode/devcontainers/python:3.11）→ 只配"image": "..."，删掉整个build字段 - 要装私有 CLI、预置 SSH key、改系统 locale → 删掉
image，只留"build": { "dockerfile": "Dockerfile" }，并在.devcontainer/Dockerfile里写FROM那一行 -
"build": { "context": ".." }这类跨目录引用极易出错：VSCode 构建时工作目录是.devcontainer/，不是项目根目录，相对路径得从这个子目录出发算
挂载项目代码必须显式声明 mounts 或 workspaceMount
VSCode 默认挂载行为在符号链接、WSL、网络盘等场景下极不可靠，常见现象包括容器内看不到文件、Git 状态异常、保存后内容不生效。别依赖默认，显式控制才稳定：
- 用
workspaceMount声明主工作区挂载点，例如："workspaceMount": "src=/path/on/host;dst=/workspaces/my-project;type=bind;consistency=cached" - 若需额外挂载（如密钥、配置），用
mounts数组，格式同 Docker CLI 的--mount，例如：{ "source": "/Users/me/.aws", "target": "/home/vscode/.aws", "type": "bind" } - 避免使用
runArgs+-v，它绕过 Dev Containers 的挂载生命周期管理，容易导致 postCreateCommand 执行时机错乱
postCreateCommand 是环境就绪的最终守门人
它不是可有可无的“锦上添花”，而是验证容器是否真正 ready 的关键环节。没加检查，就等于把环境一致性交给了运气：
- 脚本里必须包含明确退出码：检查
node --version≥ 18.17.0？docker version是否存在？~/.aws/credentials是否可读？任一失败就exit 1 - 不要只写
"postCreateCommand": "npm install"：如果package.json不存在或网络失败，命令静默跳过，开发者以为环境好了，实际缺依赖 - 推荐把检查逻辑抽成独立脚本（如
.devcontainer/check-env.sh），用"postCreateCommand": "./.devcontainer/check-env.sh"调用，便于本地调试和复用
真正难的不是写配置，而是让 postCreateCommand 在所有成员机器上都跑通——它暴露的是镜像层缺失工具、挂载权限不对、甚至宿主机 Docker Desktop 未登录私有 registry 这些底层事实。
