必须用remote-containers扩展并配置.devcontainer/devcontainer.json，否则编辑、调试、终端均在宿主机运行；devcontainer.json必须置于项目根目录下.devcontainer/子目录中，且需正确设置image或build、customizations.vscode.extensions、forwardports、remoteuser等字段，同时确保docker cli可用及用户权限正确。
VSCode 里跑 Docker 容器不是“连上就行”，必须用 Remote-Containers 扩展 + .devcontainer/devcontainer.json，否则编辑、调试、终端全在宿主机，环境根本不对齐。
devcontainer.json 必须放在 .devcontainer/ 目录下
VSCode 只认这个路径，放错位置（比如根目录或 .vscode/）会导致 “Reopen in Container” 按钮灰掉或直接弹出镜像选择框。它不读 Dockerfile，也不看 docker-compose.yml —— 那些只是构建环节的辅助文件。
-
"image"和"build"字段二选一：快速验证用"image": "mcr.microsoft.com/vscode/devcontainers/python:3.11"；要加系统级工具（如curl、git、jq）就得写"build": { "dockerfile": "Dockerfile" }，且该Dockerfile必须基于mcr.microsoft.com/devcontainers/base:ubuntu或显式安装vscode-server -
"customizations.vscode.extensions"必须显式声明，例如["ms-python.python", "esbenp.prettier-vscode"]；容器不会继承你本地装的插件 -
"forwardPorts"要填你服务实际监听的端口，比如 Flask 默认是5000，就写[5000]；漏掉就只能手动docker exec -it ... curl http://localhost:5000，浏览器打不开
docker CLI 不通，Remote-Containers 就彻底瘫痪
VSCode 不自己启动 Docker，只调你本地的 docker 命令。报 “Failed to connect to Docker daemon” 或 “Cannot connect to the Docker daemon”，90% 是这一步没过。
- 在系统终端（不是 VSCode 内置终端）执行
docker info --format '{{.OSType}}'，应返回linux/darwin/windows - Linux 用户必须运行
sudo usermod -aG docker $USER，然后**完全退出当前桌面会话再重新登录**（newgrp docker或仅重启 VSCode 无效） - macOS/Windows 用户确认 Docker Desktop 已启动，且设置中勾选了 “Start Docker Desktop when you log in”
- 别用
sudo code启动 VSCode：root 用户无法访问普通用户的/var/run/docker.sock，后续所有容器内文件 UID 都会错乱
容器内文件权限错乱，git/npm install 失败
默认行为是：VSCode 以宿主机当前 UID 启动容器进程，但基础镜像（如 python:3.11-slim）只有 root 用户。结果你在编辑器里新建的文件属主是 root:root，而本地 git 或 npm 是以你自己的 UID 运行，直接 Permission denied。
- 在
devcontainer.json中加这两项："remoteUser": "vscode"和"runArgs": ["--user", "vscode"] - 如果用了自定义
Dockerfile，必须在里面创建该用户：RUN useradd -m -u 1001 -G sudo vscode，再USER vscode - 别设
"remoteUser": "root"：虽然能过构建，但所有生成文件都是root:root，协作时git commit会被拒绝
forwardPorts 不写，服务就等于没暴露
forwardPorts 不是可选项，是调试刚需。VSCode 依赖它自动把容器端口映射到宿主机，并在右下角状态栏显示可点击链接（如 http://localhost:3000）。不填，你就得记着每次手动开终端、docker port <container-id></container-id>、再复制粘贴 URL。
- 多个端口就写成数组：
[3000, 5000, 8080] - 如果服务监听的是
0.0.0.0:3000但没 forward，浏览器访问localhost:3000就是连接被拒绝（Connection refused） - 某些框架（如 Next.js）默认只监听
127.0.0.1，得额外加启动参数改成--host 0.0.0.0，否则即使 forward 了也连不上
真正卡住人的从来不是语法或命令，而是 devcontainer.json 少一个字段、docker 组没生效、或者 remoteUser 和 Dockerfile 里的用户没对上——这些地方一错，整个环境就处于“看似在跑，实则不可用”的状态。
