必须通过.devcontainer/devcontainer.json启动，否则vscode不会注入server、安装插件、转发端口或处理权限；该文件须严格置于项目根目录下.devcontainer/子目录中，命名、路径、json格式任一错误均导致识别失败。
直接说结论：不是“连上容器就行”，而是必须通过 .devcontainer/devcontainer.json 启动，否则 VSCode 不会注入 server、不装插件、不转发端口、不处理权限——你只是在用终端 ssh 连了个裸容器。
devcontainer.json 放错位置或格式错误，VSCode 根本不会识别
VSCode 只在项目根目录下扫描 .devcontainer/devcontainer.json，路径错一丁点（比如写成 .devcontainer.json 或放在子目录）就彻底失效。常见现象包括：右下角没绿色按钮、点「Reopen in Container」报错 “No dev container configuration found”。
- 必须是
.devcontainer/（带点）这个**固定文件夹名**，不能是devcontainer/或.vscode/devcontainer.json -
devcontainer.json必须是合法 JSON：字段名用双引号，末尾不能多逗号，布尔值写true不要写"true" - 关键字段只认三个：要么填
"image"（推荐新手），要么填"build": { "dockerfile": "Dockerfile" }，二者不能共存；漏掉任一都会卡在 “Building image…”
容器里 git / npm / curl 找不到？别直接用生产镜像
用 python:3.11-slim 或 node:18-alpine 这类镜像启动，大概率进容器后发现 git 命令不存在、npm install 报错缺少 curl、make 也没装——因为这些镜像是为运行服务精简的，不是为开发准备的。
- 优先选微软官方预置镜像：
mcr.microsoft.com/vscode/devcontainers/python:3.11、javascript-node:18-bullseye，它们默认装好git、curl、sudo、openssh-client和 vscode-server 依赖 - 如果必须自定义 Dockerfile，基础层别从
scratch或alpine开始，至少基于devcontainers/base:ubuntu-22.04 - 确认
postCreateCommand里没漏设 Git 用户："postCreateCommand": "git config --global user.name 'dev' && git config --global user.email 'dev@example.com'"
端口打不开、数据库连不上、localhost 失效？网络和绑定地址全错了
你在代码里写 http://localhost:3000，浏览器打不开；写 postgres://localhost:5432，连不上 compose 里的 db 服务——这不是配置漏了，是根本性误解了容器网络模型。
-
forwardPorts必须显式声明，比如[3000, 5432]，否则 VSCode 不会把宿主机端口映射过去 - 服务必须监听
0.0.0.0:3000，不是127.0.0.1:3000；Node.js 的app.listen(3000)默认只绑本地回环，得写成app.listen(3000, '0.0.0.0') - 多个容器间通信，用
docker-compose.yml里定义的 服务名 当 host，例如postgres://db:5432，不是localhost，也不是宿主机 IP - 想从容器内访问宿主机服务（比如本地 MySQL），macOS/Windows 用
host.docker.internal，Linux 得用真实网关 IP，并通过remoteEnv注入："DB_HOST": "host.docker.internal"
文件权限混乱、git status 异常、保存后内容消失？挂载用户没对齐
VSCode 默认以 root 用户挂载代码进容器，结果你新建的文件属主是 root，但本地 git 配置用的是你自己的 UID，混着提交就会触发 permission denied 或状态不一致。
- 在
devcontainer.json里加这两行："remoteUser": "vscode"和"runArgs": ["--user", "vscode"] - 如果用了自定义 Dockerfile，必须创建该用户并加 sudo 权限：
RUN useradd -m -u 1001 -G sudo vscode，再配免密 sudo - 别碰
workspaceFolder路径，保持默认/workspace；符号链接、WSL 混合路径、网络盘挂载都容易导致文件同步失败，这类路径尽量避免用于 Dev Container 工作区
最常被忽略的一点：VSCode 的 Dev Container 是独立容器进程，它不共享宿主机的环境变量、shell 配置、甚至 PATH。所有开发依赖、工具链、语言版本，都必须明确定义在 devcontainer.json 或对应镜像里——别指望“我本地装了 node，容器里自然有”。
