Dev Containers 环境统一性取决于团队共维的 .devcontainer/devcontainer.json：必须置于项目根目录下 .devcontainer/ 中，严格避免 image 与 build 并存，挂载需显式配置 workspaceMount/mounts，多服务须用 dockerComposeFile+service，端口转发优先设 forwardPorts。
Dev Containers 插件本身不决定环境是否统一，真正起作用的是 .devcontainer/devcontainer.json 的内容是否被团队共同维护、版本控制且严格遵循约束条件。配置错一个字段，新成员点“Reopen in Container”就卡在拉取镜像或挂载失败。
devcontainer.json 必须放在 .devcontainer/ 目录下
VS Code 只识别固定路径：项目根目录下的 .devcontainer/devcontainer.json。放错位置是 70% 以上“Reopen in Container 按钮灰掉”问题的根源。
- 不能放在
.vscode/、config/或项目根目录平级 - Windows 用户用资源管理器手动建
.devcontainer文件夹容易失败，应改用终端：mkdir .devcontainer - 如果项目已有
Dockerfile，推荐在devcontainer.json中显式写"dockerFile": "Dockerfile"，避免 VS Code 默认查找逻辑失效
image 和 build 不能同时出现
这是团队配置最常翻车的语法错误。VS Code 会直接报错：Invalid devcontainer.json: 'image' and 'build' cannot both be specified。
- 纯用公开镜像（如
python:3.12-slim）→ 只配"image" - 需要装私有 CLI、预置 SSH key、改 locale → 删掉
"image"，只留"build"，并在Dockerfile中FROM那个基础镜像 -
"build": { "context": ".." }这类跨目录引用要小心：VS Code 构建时工作目录是.devcontainer/，不是项目根目录，相对路径极易错位
挂载项目代码必须显式声明 workspaceMount 或 mounts
别依赖 VS Code 默认挂载行为。遇到符号链接、WSL 路径混用、网络盘等情况，容器内常出现“文件看不见”“Git 状态异常”“保存不生效”等问题。
- 推荐用
workspaceMount显式绑定路径，例如："workspaceMount": "src=.:dst=/workspaces/my-app,type=bind,consistency=cached" - 若需额外挂载（如本地
~/.ssh），必须用mounts字段，格式为数组，每项是字符串："mounts": ["source=${localWorkspaceFolder}/.env,target=/workspaces/my-app/.env,type=bind,consistency=delegated"] -
consistency参数对 macOS/WSL 很关键：macOS 推荐cached，WSL 推荐delegated，否则文件变更监听可能延迟或丢失
多服务场景必须用 dockerComposeFile + service
单容器够用？那没问题。但凡涉及数据库、Redis、Mock Server 等依赖服务，硬塞进一个容器里只会让构建变慢、调试变难、权限变乱。
- 必须删掉
image或build字段，改用："dockerComposeFile": "docker-compose.yml", "service": "app" -
docker-compose.yml中主服务（service: app）的volumes挂载必须和devcontainer.json的workspaceMount一致，否则容器内看不到代码 - 端口转发优先写在
devcontainer.json的forwardPorts里，而不是靠docker-compose.yml的ports—— 后者只做容器间通信，前者才映射到宿主机
最容易被忽略的其实是 postStartCommand 和 onCreateCommand 的执行时机差异：前者在容器启动后、VS Code 连接前运行，适合做依赖安装；后者在镜像构建完成后、容器启动前运行，适合做一次性初始化（如生成密钥）。混用会导致命令执行失败却无提示。
