devcontainer.json 中 image 和 build 互斥：仅用 image 可快速拉取官方镜像，但无法定制；需定制则必须删掉 image、改用 build 并配 dockerfile，且服务须绑定 0.0.0.0 才能通过 forwardports 访问。
devcontainer.json 里 image 和 build 配置不能混用
直接写 image 就是拉取现成镜像，写 build 就必须配 Dockerfile ——这两条路径互斥。选错会导致 “The dev container configuration has syntax errors” 或构建卡在 “Building image…” 不动。
-
image适合快速启动，比如"image": "mcr.microsoft.com/vscode/devcontainers/python:3.11"，但无法定制系统级依赖（如特定版本的curl或libpq） -
build必须指定dockerfile路径，默认是.devcontainer/Dockerfile；若 Dockerfile 在别处，要写"dockerfile": "../dockerfiles/dev.Dockerfile" - 如果既想复用官方镜像，又想加几行安装命令，别硬改
image，改用features或在Dockerfile里FROM那个镜像再RUN
端口转发不生效？检查 forwardPorts 和 localhost 绑定
配置了 "forwardPorts": [3000] 却访问不了 http://localhost:3000，大概率是服务没绑定到 0.0.0.0。容器内默认只监听 127.0.0.1，而 VSCode 的端口转发是从宿主机连进容器的网络命名空间，不是 loopback 回环。
- Node.js 项目启动时加
--host 0.0.0.0（如npm run dev -- --host 0.0.0.0） - Python Flask 用
app.run(host="0.0.0.0", port=3000) - 确认容器里没防火墙（Ubuntu 镜像默认没 ufw，但自定义镜像可能开了）
- VSCode 端口转发状态在左下角点击绿色远程按钮可查看，已转发的端口会标为 “Forwarded”
多容器协作时，dockerComposeFile 配置容易漏 service 字段
用 docker-compose.yml 启动多个服务（比如 app + db + redis），VSCode 默认不知道该把代码挂载到哪个容器、该在哪个容器里开终端。不设 service，就会报错 “No service specified in devcontainer.json” 或直接连到第一个 service（通常是 alphabetically first，不一定是 app）。
-
"service": "app"必须和docker-compose.yml里的 service 名完全一致（区分大小写） -
workspaceFolder是容器内挂载路径，推荐统一用/workspace，避免某些 CLI 工具硬编码路径 - 如果主服务用了
command: sleep infinity，确保它没被健康检查或 restart_policy 干扰——VSCode 依赖这个容器保持运行来维持连接 - 数据库类服务（如 PostgreSQL）不用挂载代码，但要在
forwardPorts里加上它的端口，方便本地 psql 或 DBeaver 连接
postCreateCommand 和 postAttachCommand 执行时机不同
这两个钩子看着像，行为却差很远：postCreateCommand 只在首次构建容器后执行一次（相当于初始化），postAttachCommand 每次连接容器都执行（相当于每次打开终端前的准备）。搞反了会导致依赖重复安装、环境变量丢失或权限错误。
- 装全局工具（
pip install pre-commit）、生成密钥、初始化 git submodule，放postCreateCommand - 激活虚拟环境（
source venv/bin/activate）、设置 shell 提示符、启动 watch 进程，放postAttachCommand - 二者都支持数组写法，比如
"postAttachCommand": ["source ~/.bashrc", "cd /workspace"] - 如果命令失败，
postCreateCommand会让整个容器启动失败；postAttachCommand失败则只影响当前终端会话
实际用起来最常被忽略的是：Dockerfile 中的 COPY 或 ADD 如果路径写错，postCreateCommand 里跑 npm install 就会找不到 package.json；而这个错误不会直接报在 VSCode 弹窗里，只出现在构建日志末尾滚动屏里——得手动展开 “Dev Container Logs” 才能看到。
