dev containers 需满足路径、字段、用户、挂载四要素才生效：.devcontainer/devcontainer.json 位置与结构须严格匹配；image 与 build 字段不可共存；windows+wsl2 需从 wsl 终端启动 code .；shell 启动模式影响工具链加载，需在 postcreatecommand 显式 source；挂载推荐显式配置 workspacemount；用户权限需确保 home 可写；团队协作须同步扩展 id、挂载及用户配置。
Dev Containers 不是“一键启动就万事大吉”的黑盒，它依赖几个硬性条件才能真正接管你的开发环境——路径对、字段对、用户对、挂载对，错一个，Reopen in Container 就只是换个终端而已。
devcontainer.json 文件位置和结构必须严格匹配
VSCode 只认 .devcontainer/devcontainer.json 这个路径：开头带点、是目录不是文件、在你打开的 VSCode 工作区根目录下。写成 devcontainer.json（没点）、.devcontainer.json（是文件不是目录）、或者放在 .vscode/ 里，VSCode 都不会识别。
-
image和build字段不能共存，同时出现会报错Invalid devcontainer.json: 'image' and 'build' cannot both be specified - 空文件或只有注释的
devcontainer.json不会触发容器启动逻辑 - Windows 用户若用 WSL2，必须从 WSL2 终端里执行
code .打开项目；用 Windows 版 VSCode 直接双击打开，插件默认不生效
容器内命令找不到（如 node、conda、git）的常见原因
不是镜像没装，而是 shell 启动模式不对：Dev Containers 默认以 login shell 启动（例如 /bin/bash --login），但很多工具（conda、nvm、sdkman）的初始化脚本只在交互式 shell 或手动 source 时才加载。
- 确认
devcontainer.json中设置了"terminal.integrated.defaultProfile.linux": "bash" - conda 用户需在
postCreateCommand显式 source："postCreateCommand": "source /opt/conda/etc/profile.d/conda.sh && conda activate base" - nvm 同理：
"postCreateCommand": "source ~/.nvm/nvm.sh && nvm use 18" - Git 不可用？大概率是容器内没设
user.name和user.email，加进postCreateCommand或用features自动配置
挂载代码和权限问题最容易被忽略
VSCode 默认把工作区挂到 /workspace，但这个行为在符号链接、网络盘、跨 WSL/Windows 路径混用时极不稳定——你改了文件，git status 看不到；保存后内容消失；甚至 ls 都列不出文件。
- 显式声明
workspaceMount比依赖默认更可靠："workspaceMount": "source=${localWorkspaceFolder},target=/workspace,type=bind,consistency=cached" - 官方镜像默认用
vscode用户，但HOME目录可能不可写，导致pip install --user或npm install -g失败 - 在 Dockerfile 里加
RUN chown -R vscode:vscode /home/vscode，并在devcontainer.json中写明"remoteUser": "vscode" - 别在
postCreateCommand里跑npm install——它只在首次创建容器时执行，重启后不重跑；高频依赖建议写进Dockerfile
团队协作时最常翻车的三个配置点
提交到 Git 的 .devcontainer/ 目录，本质是环境契约。但很多人只改了镜像，却忘了同步扩展、挂载或用户配置，结果“别人拉下来打不开”。
-
customizations.vscode.extensions必须填扩展的完整 ID（如"ms-python.python"），不是名字，也不是 marketplace 页面 URL -
mounts字段若用于复用本地~/.npm或~/.cargo，要显式声明；但不要挂载整个/home/vscode，会覆盖容器初始化的用户配置 - 想复用项目已有
Dockerfile？在devcontainer.json中用"build": { "dockerfile": "Dockerfile" }显式指向，别依赖自动查找
真正的难点不在写配置，而在理解 VSCode 是如何把本地操作翻译成容器内行为的——比如你点保存，是宿主机在写，还是容器在写；你敲 git commit，走的是容器里的 git 还是本地的 git；这些边界一旦模糊，问题就变成“现象诡异、日志无错、重启解决”。
