Dev Containers 配置必须严格使用 .devcontainer/devcontainer.json 路径，image 和 build 不可共存，挂载需显式声明 workspaceMount 或 mounts，扩展须通过 extensions 字段声明，环境差异需结合日志持续调优。
Dev Containers 配置文件必须放在 .devcontainer/ 目录下，且主配置名只能是 devcontainer.json
VSCode 不会自动识别任意位置或任意命名的容器配置。如果你把 devcontainer.json 放在项目根目录、.vscode/ 里，或者叫成 container.json，它根本不会触发 Dev Containers 功能。
常见错误现象：Reopen in Container 按钮灰掉、命令面板搜不到 Dev Containers: Reopen in Container、弹窗提示 “No dev container configuration found”。
- 确保路径是
.devcontainer/devcontainer.json（注意是点开头的隐藏目录） - Windows 用户要注意：不要用资源管理器直接新建“以点开头”的文件夹，建议用终端
mkdir .devcontainer - 如果项目已有
Dockerfile，推荐在devcontainer.json中用"dockerFile": "Dockerfile"显式指向，而不是依赖默认查找逻辑
devcontainer.json 中 image 和 build 不能共存，选错会导致构建失败或镜像拉取异常
这是团队配置最常翻车的地方：想复用基础镜像又想加几行 RUN，就同时写 "image": "node:18" 和 "build": { "dockerfile": "Dockerfile" } —— VSCode 会直接报错 Invalid devcontainer.json: 'image' and 'build' cannot both be specified。
使用场景判断依据很简单：要不要定制构建过程？
- 纯用公开镜像（如
python:3.11-slim），就只配"image" - 需要装私有 CLI、预置 SSH key、改系统 locale，就必须删掉
"image"，只留"build"，并在Dockerfile里FROM那个基础镜像 -
"build": { "context": ".." }这种跨目录引用要小心：VSCode 构建时工作目录是.devcontainer/，不是项目根目录，相对路径容易错位
挂载项目代码必须用 mounts 或 workspaceMount，别依赖默认行为
VSCode 默认会把当前打开的文件夹作为 workspace 挂进容器，但这个行为不可靠：遇到符号链接、网络盘、WSL 路径混用时，经常出现容器内看不到文件、保存不生效、Git 状态异常等问题。
正确做法是显式声明挂载点，尤其当项目结构复杂或团队成员系统不一致时：
- 优先用
"workspaceMount": "source=${localWorkspaceFolder},target=/workspace,type=bind,consistency=cached"（macOS / WSL 推荐cached，Linux 用delegated） - 如果还要挂载其他目录（如公司内部工具链），加到
"mounts"数组里，例如"source=/opt/tools,target=/opt/tools,type=bind,readOnly=true" - 避免用
"/host/path"这种绝对路径——不同成员机器路径不同，会导致配置无法共享；一律用${localWorkspaceFolder}或${localDevContainerConfig}这类变量
扩展安装必须写进 extensions 字段，远程安装的扩展不会同步到容器内
很多人以为在容器里手动装了 ms-python.python 就一劳永逸，其实这只是装在当前容器实例上。下次重建容器、换机器、队友拉代码，全得重来，还容易版本不一致。
Dev Containers 的扩展管理是声明式的，靠 devcontainer.json 中的 "extensions" 数组驱动：
- 填入 Marketplace ID，比如
"ms-python.python"、"esbenp.prettier-vscode"，不是插件名 - 团队统一用 Prettier，就别让每人自己配
.prettierrc，直接在devcontainer.json里加"settings"块，例如"editor.formatOnSave": true - 某些扩展（如
ms-azuretools.vscode-docker）需本地 + 容器双端安装，这时要在"extensions"里写两次：一次放本地（不带前缀），一次放容器（带ms-azuretools.vscode-docker）
真正难的是环境差异收敛：有人用 M1 Mac，有人用 Windows + WSL2，还有人直连 Linux 服务器。同一份 devcontainer.json 在三台机器上可能触发三种不同的挂载策略、构建缓存行为和扩展加载顺序。别指望一次配完就永远稳定，得把 docker build 日志、Remote-Containers 输出通道、以及容器内 df -h 的结果都纳入日常排查范围。
