devcontainer能直接隔离项目依赖且不污染本地环境，其核心是将vscode编辑、终端、调试能力完整移入容器，所有命令在容器内执行；必须在项目根目录创建.devcontainer文件夹并放入合法json格式的devcontainer.json，字段大小写敏感，需正确配置镜像、端口转发、生命周期命令等。
能直接隔离项目依赖，且不污染本地环境——这是 DevContainer 最实在的价值。它不是“另一个 Docker 教程”，而是把 VSCode 的编辑、终端、调试能力完整搬进容器里，让 npm run dev、pytest、go test 全部在容器内执行，本地只留一个干净的编辑器。
devcontainer.json 是唯一入口，别漏掉 .devcontainer 目录
VSCode 不会自动识别任意位置的配置文件。必须在项目根目录下创建 .devcontainer 文件夹，并把 devcontainer.json 放进去。漏掉这个目录或拼错名字（比如写成 devcontainer.json 在根目录下、没套 .devcontainer），VSCode 就根本不会弹出 “Reopen in Container” 提示。
-
devcontainer.json必须是合法 JSON，字段名大小写敏感（如forwardPorts不能写成forwardports） - 如果用
docker-compose.yml，devcontainer.json中必须明确指定"dockerComposeFile": "docker-compose.yml"和"service": "app" - 路径挂载默认是双向同步的，但
.git、node_modules等不建议在容器内生成后反向写回主机，容易权限错乱
选镜像别只看“最新版”，优先用微软官方 devcontainers 镜像
直接写 "image": "python:3.12" 或 "node:20" 看似简单，但这些基础镜像不含 VSCode 所需的 dev tools、非 root 用户配置、或 git、curl 等常用工具，后续要自己写 Dockerfile 补全，反而增加维护成本。
- 推荐从
mcr.microsoft.com/devcontainers/下找对应语言的镜像，例如：mcr.microsoft.com/devcontainers/python:3-3.11、mcr.microsoft.com/devcontainers/node:18 - 这些镜像已预配好非 root 用户、SSH 服务、常用 CLI 工具，且和 VSCode Remote 插件深度兼容
- 若需额外软件（如
postgresql-client、jq），优先用features字段声明，而不是改写 Dockerfile ——features可复用、可缓存、升级透明
端口转发失效？检查 forwardPorts 和容器内服务绑定地址
配置了 "forwardPorts": [3000] 却访问不到服务，大概率不是 VSCode 问题，而是容器内服务只监听了 localhost:3000（即 127.0.0.1），导致外部（包括主机）无法连接。
- Web 框架如 Express、FastAPI、Django 默认可能只绑
127.0.0.1；必须显式设为0.0.0.0:3000 - 数据库服务（如 PostgreSQL）也要确认
listen_addresses = '0.0.0.0'和pg_hba.conf允许来自172.x.x.x网段的连接（Docker 默认桥接网络） -
forwardPorts只做端口映射，不改服务监听行为；它不会自动把localhost重写成0.0.0.0
postCreateCommand 和 postAttachCommand 容易混淆
这两个命令触发时机完全不同，用错会导致环境初始化失败或调试器连不上。
-
postCreateCommand：仅在容器首次构建完成、**尚未启动 VSCode 服务前**执行一次，适合装全局依赖（如pip install -r requirements.txt）、初始化数据库 schema -
postAttachCommand：每次 VSCode **连接到已运行容器时**都执行，适合启动后台进程（如npm run watch）、检查环境变量、打印版本信息 - 若在
postAttachCommand里执行耗时操作（如make build），每次打开终端都会卡住；应移到postCreateCommand或用onCreateCommand替代
真正难的不是写对第一行 JSON，而是理解容器生命周期和 VSCode 连接机制之间的耦合点——比如 postAttachCommand 在热重连时也会触发，而 forwardPorts 对监听地址毫无感知。这些地方一旦忽略，就会陷入“配置看起来没问题，但就是不通”的循环。
