Dev Containers配置文件必须置于.devcontainer/目录下且命名为devcontainer.json或Dockerfile；手动创建需先建目录再放文件，推荐用VSCode命令自动生成；优先使用features而非自写Dockerfile；避免混用dockerFile与features；勿误配mounts覆盖默认源码挂载；Windows用户需确保WSL2及Docker Desktop正常运行；修改配置后须“Rebuild Container”生效。
Dev Containers配置文件必须放在 .devcontainer/ 目录下
VSCode 读取 Dev Containers 配置时，只认 .devcontainer/devcontainer.json（或 .devcontainer/Dockerfile），不能放在项目根目录平级、也不能叫 devcontainer.yaml 或 .devcontainer.json（少个斜杠就失效）。常见错误是手动生成了 devcontainer.json 却没建 .devcontainer 文件夹，结果点击 “Reopen in Container” 没反应——VSCode 根本没发现配置。
实操建议：
- 用 VSCode 命令面板（
Ctrl+Shift+P/Cmd+Shift+P）运行Dev Containers: Add Development Container Configuration Files...，它会自动创建正确路径和基础模板 - 手动创建时，先建文件夹：
mkdir -p .devcontainer，再放devcontainer.json - 如果项目已有
Dockerfile，可直接在devcontainer.json中通过"dockerFile": "Dockerfile"引用，但该文件仍需位于.devcontainer/下或其子路径（如设为"dockerFile": "Dockerfile.base"就得把文件放进去）
devcontainer.json 中的 "features" 比自写 Dockerfile 更快更稳
很多人习惯从头写 Dockerfile 装 Python、Node、Rust 等工具链，但官方维护的 features（比如 ghcr.io/devcontainers/features/python:1）已预编译好二进制、处理好权限、适配多平台（x86/arm64），还能自动更新。自己写容易漏掉 non-root user 权限配置，导致 VSCode 终端默认以 root 运行，后续 npm install 或 pip install 出权限错误。
实操建议：
- 优先用
"features"字段声明依赖，例如：
"features": {
"ghcr.io/devcontainers/features/python:1": {
"version": "3.12"
},
"ghcr.io/devcontainers/features/node:1": {
"version": "20"
}
}
- 避免在
devcontainer.json中混用"dockerFile"和"features"——前者会完全接管构建过程，features不生效 - 想加自定义命令？用
"onCreateCommand"或"postCreateCommand"，而不是塞进 Dockerfile 的 RUN 指令里（后者无法访问挂载的源码，也难调试）
挂载源码时别用 "mounts" 覆盖工作区路径
默认情况下，VSCode 把本地项目目录作为 volume 挂载到容器内 /workspaces/<folder-name>。如果在 devcontainer.json 中误配 "mounts"，比如写成 "source=/path/on/host,target=/workspace,type=bind,consistency=cached"，就会覆盖默认挂载，导致打开的文件不是你编辑的那批，Git 状态异常，甚至保存后本地没变化。
实操建议：
- 除非有特殊需求（如共享某个配置目录），否则不要碰
"mounts"字段 - 需要额外挂载？用
"remoteEnv"+"containerEnv"控制环境变量，或通过"postCreateCommand"创建符号链接 - 确认挂载是否正常：进容器执行
ls -l /workspaces，应看到你的项目名目录；再cat /proc/mounts | grep workspace，验证 source 路径是你本地项目根
Windows 用户注意 WSL2 后端与 Docker Desktop 的状态耦合
在 Windows 上，VSCode Dev Containers 实际依赖 WSL2 中的 Docker daemon。如果 Docker Desktop 没启动、或 WSL2 发行版（如 Ubuntu-22.04）被关机、或 docker context 切到了远程主机，VSCode 就会卡在 “Building image…” 或报错 Cannot connect to the Docker daemon，而界面提示往往只写 “Failed to start dev container”。
实操建议：
- 终端里先跑
docker info，确保输出正常；再运行wsl -l -v，确认默认发行版状态是Running - VSCode 设置里搜
dev containers docker path，检查remote.containers.dockerPath是否为空（应为空，让它走默认） - 如果用 WSLg 或 GUI 工具，记得在 WSL 中执行
sudo service docker start（Docker Desktop 自动管理时通常不需要，但手动安装过 docker-ce 的用户容易忽略）
最常被忽略的是：改完 devcontainer.json 后没点 “Rebuild Container”，而是点了 “Reopen in Container”——后者复用旧镜像，所有新配置都不生效。重装依赖、换 Python 版本、加 features，都得 rebuild。
