必须用 devcontainer.json 而非直接 ssh，因其是声明式配置唯一入口，确保环境可复现、一键重建及镜像一致性；直接 ssh 无法满足这些需求。
直接装 Remote-Containers 扩展，配好 devcontainer.json，就能在容器里完整开发——不是挂载目录凑合用，而是编辑、终端、调试全在容器上下文中运行，环境变量、路径、依赖全部原生对齐。
必须先确认 Docker CLI 可用且权限正常
VSCode 不会自己启动 Docker 服务，它只调 docker 命令。如果点 “Reopen in Container” 没反应或报错 Failed to connect to Docker daemon，大概率是这一步卡住了。
- 在终端执行
docker info --format '{{.OSType}}'，应返回linux、darwin或windows - 运行
docker run --rm hello-world确认基础能力正常 - Linux/macOS 用户需确保当前用户在
docker组里：sudo usermod -aG docker $USER，然后重新登录终端 - 别用
sudo code启动 VSCode，否则容器内文件 UID 易错乱，后续git或npm install可能失败
devcontainer.json 三个字段不能少
这个文件必须放在项目根目录下的 .devcontainer/devcontainer.json，VSCode 只认这个路径。漏掉关键字段会导致卡在 “Building image…” 或进容器后没终端、没插件。
-
"image"或"build"二选一：快速验证用"image": "mcr.microsoft.com/vscode/devcontainers/python:3.11"；要加系统包就写"build": { "dockerfile": "Dockerfile" }，且Dockerfile必须基于dev-containers/base或显式安装vscode-server -
"customizations.vscode.extensions"必须显式列出来，比如["ms-python.python", "esbenp.prettier-vscode"]；容器不继承你本地的插件列表 -
"forwardPorts"是调试刚需：Flask 默认跑5000，就得写[5000]；不填就只能靠docker exec进去 curl，浏览器打不开
文件权限和用户属主最容易踩坑
默认情况下，VSCode 以宿主机当前 UID 启动容器进程。但多数基础镜像（如 python:3.11-slim）只有 root 用户，结果就是：你在编辑器里新建的文件属主是 root，git status 却显示 modified —— 因为宿主机 UID 对不上。
- 最稳解法：在
devcontainer.json加"remoteUser": "vscode"和"runArgs": ["--user", "vscode"] - 如果用了自定义
Dockerfile，必须在里面创建该用户并加进sudo组：RUN useradd -m -u 1001 -G sudo vscode - 别设
"remoteUser": "root"：虽然能过构建，但所有生成文件都是root:root，后续协作时git commit会因权限拒绝失败
真正麻烦的不是配置本身，而是错误信息藏得深：postCreateCommand 失败不会弹红框，只在 Dev Container 日志里闪一下；forwardPorts 漏写，服务明明在跑，浏览器就是连不上——这些都得看右下角状态栏提示，点开 “Dev Container” 日志才能定位。
