dev containers 是容器化工作区，通过 .devcontainer/devcontainer.json 配置在隔离容器中启动完整开发环境；需确保配置路径正确、镜像可拉取、wsl2 正确启用，并注意 extensions、mounts、postcreatecommand 等字段精准设置。
Dev Containers 本质是“容器化工作区”，不是 Docker 模板生成器
VSCode 的 Dev Containers 功能，核心作用是在一个隔离的容器里启动整个开发环境——包括语言运行时、工具链、依赖包、甚至 .vscode/settings.json 和扩展。它不负责帮你“生成”模板，而是读取项目根目录下的 .devcontainer/devcontainer.json，然后拉镜像、挂载代码、安装扩展、执行配置命令。
常见错误现象：Rebuild and Reopen in Container 后 VSCode 还在本地打开；或者容器启动后 git 不可用、python 命令报错找不到。
- 确认项目根目录下有
.devcontainer/devcontainer.json（不是devcontainer.json在子目录） -
devcontainer.json中的"image"或"dockerfile"必须指向可构建/拉取的镜像，不能写错路径或镜像名（比如写成node:18却没联网） - Windows 用户注意：WSL2 是必需后端，Docker Desktop 必须启用 WSL2 backend，且 VSCode 要从 WSL2 内启动（用
code .而非 Windows 版 VSCode 点开）
devcontainer.json 里最常配错的三个字段
很多人复制模板后改了镜像却忘了同步改其他字段，导致环境能起来但功能残缺。
-
"customizations.vscode.extensions"：必须填 VS Code 扩展的完整 ID（如"ms-python.python"），不是名字也不是 marketplace 链接；漏掉这个，Python语法高亮和调试都不会生效 -
"mounts"：若想复用本地~/.npm或~/.cargo，得显式挂载，容器内默认没有这些路径；但挂载/home/vscode到本地会覆盖容器初始化的用户配置 -
"postCreateCommand"：适合装 Python 包、Rust toolchain、Node 全局模块等；但别在这里跑npm install—— 它只在首次创建容器时执行，后续重启不触发；高频依赖建议写进Dockerfile
用 Dockerfile 自定义镜像比直接用现成镜像更可控
官方镜像（如 mcr.microsoft.com/vscode/devcontainers/python:3）省事，但升级慢、预装包版本固定、无法删减冗余工具。一旦项目需要特定 C 库、非标 Python 编译选项或私有 pip 源，就必须自己写 Dockerfile。
- 基础镜像建议选
FROM mcr.microsoft.com/vscode/devcontainers/base:ubuntu-22.04，它已内置nonroot用户、git、curl和 dev container 工具链 - 所有
RUN指令尽量合并（如RUN apt-get update && apt-get install -y xxx && rm -rf /var/lib/apt/lists/*），避免层过多拖慢重建速度 - 不要在
Dockerfile里用COPY . /workspace—— VSCode 默认会把项目根目录以 volume 方式挂载到/workspace，重复拷贝反而可能覆盖本地修改
容器内调试失败？先检查 PATH 和 shell 初始化
很多调试器（如 lldb、gdb、debugpy）在容器里起不来，不是插件没装，而是 shell 环境没加载完整。
- Dev Containers 默认用
/bin/sh启动，不会 source~/.bashrc或~/.zshrc；如果 Python virtualenv 激活逻辑写在.bashrc里，python命令就还是系统版 - 解决方案：在
devcontainer.json加"settings": { "terminal.integrated.defaultProfile.linux": "bash" }，再配合"postAttachCommand"手动激活环境 - 验证方式：打开容器终端，执行
echo $PATH和which python，确保路径指向你期望的位置（比如/opt/venv/bin/python）
真正卡住人的地方，往往不是不会写 devcontainer.json，而是以为容器“应该自动继承宿主环境”，结果 PATH、locale、ssh-agent、甚至时区都对不上。每次重开前，花 10 秒看一眼 docker ps 输出的容器名和状态，比反复 rebuild 更快定位问题。
