必须用 Remote-Containers 扩展 + .devcontainer/devcontainer.json，其他方式（SSH、docker exec、Docker 插件直连）都不能算“联动”，只是临时访问容器；Remote-Containers 扩展装错或未启用会导致 VSCode 无法识别容器开发模式，常见现象是左下角无 Reopen in Container 选项或命令面板搜不到对应命令。
必须用 Remote-Containers 扩展 + .devcontainer/devcontainer.json，其他方式（SSH、docker exec、Docker 插件直连）都不能算“联动”，只是临时访问容器。
Remote-Containers 扩展装错或没启用，VSCode 就根本识别不了容器开发模式
常见错误现象：点左下角远程连接图标，没有 Reopen in Container 选项；或者命令面板里搜不到 Remote-Containers: Reopen in Container。
- 确认插件 ID 是
ms-vscode-remote.remote-containers（发布者必须是 Microsoft），别装成第三方同名插件 - Linux 用户执行
docker info不能报permission denied；若失败，运行sudo usermod -aG docker $USER后需完全退出终端重登 - macOS/Windows 用户检查 Docker Desktop 是否运行，且 WSL2 后端已启用（不是 Hyper-V）
- 不要用
sudo code启动 VSCode，否则容器内文件 UID 映射会错乱，后续git commit或npm install直接失败
.devcontainer/devcontainer.json 放错位置或缺关键字段，构建就卡住或进不去终端
这个文件不是可选配置，VSCode 只认项目根目录下的 .devcontainer/devcontainer.json，放错路径（比如放在 ./config/ 或漏掉 .devcontainer 文件夹）等于没写。
-
"image"或"build"字段二者必填其一，不能都空着；快速验证可用"image": "mcr.microsoft.com/vscode/devcontainers/python:3.11" - 用
"build"时，"dockerFile"路径必须相对于.devcontainer/，例如"dockerFile": "Dockerfile" -
"customizations.vscode.extensions"必须显式列出插件 ID，如["ms-python.python", "esbenp.prettier-vscode"]；不写就只有裸编辑器 -
"forwardPorts"不填，Flask 的5000或 Next.js 的3000就不会在右下角显示可点击链接，localhost:3000也打不开
Dockerfile 里不处理用户权限，git status 一直显示 modified
VSCode 默认以宿主机当前 UID 启动容器进程。但多数基础镜像（如 python:3.11-slim）只有 root 用户，结果你新建的文件属主是 root:root，而宿主机用户无法修改，git 认为文件权限变了，持续标为 modified。
- 查宿主机 UID：
id -u（常见是1001） - 在 Dockerfile 中创建对应用户：
RUN useradd -m -u 1001 -G sudo vscode && chown -R vscode:vscode /home/vscode - 在
devcontainer.json加上："remoteUser": "vscode"和"runArgs": ["--user", "vscode"] - 绝对不要设
"remoteUser": "root"—— 后续所有生成文件都是 root 属主，协作时别人拉代码直接Permission denied
多容器场景下，devcontainer.json 无法直接编排服务依赖
devcontainer.json 只管单个开发容器本身，它不支持 docker-compose.yml 那种多服务启动与网络互通。想让 Flask 容器连上 PostgreSQL 容器，得靠外部编排，再把数据库地址暴露给开发容器。
- 用
docker-compose.yml启动整套服务，确保数据库容器暴露端口并加入同一自定义网络 - 在
devcontainer.json的"runArgs"里加--network myapp_default（网络名按 compose 自动生成的填） - 应用代码里数据库 host 改成 compose 服务名（如
postgres），而非localhost - 别指望
devcontainer.json自动拉起 Postgres——它只负责你当前编辑的这个容器，其他服务得提前跑好
最常被忽略的是 UID/GID 对齐和 devcontainer.json 的路径硬编码规则。这两个点一错，整个环境就陷入“能进容器但没法 git、没法 npm install、浏览器打不开”的静默故障，排查起来比修 Dockerfile 还费时间。
