remote-containers扩展是唯一能实现vscode完整容器环境接管的方案，必须安装ms-vscode-remote.remote-containers插件并配置.devcontainer/devcontainer.json文件，二者缺一不可；其他方式无法同步插件、处理权限或转发端口。
Remote-Containers 扩展是唯一能真正把 VSCode “搬进”容器的方案，其他方式（比如手动 docker exec、SSH 连入、或只装 Docker 插件）都做不到环境接管——编辑、调试、终端、插件全在容器上下文中运行。
必须装对扩展：认准 ms-vscode-remote.remote-containers
VSCode 商店搜 “Remote Containers”，安装时务必确认发布者是 Microsoft，ID 是 ms-vscode-remote.remote-containers。装错同名第三方插件，或者只装了 docker 插件，都会卡在“重载窗口失败”或状态栏不显示 Dev Container 图标。
Linux 用户还需确认当前用户已加入 docker 组：sudo usermod -aG docker $USER，改完必须完全退出桌面会话再重登；Windows/macOS 用户检查 Docker Desktop 是否正在运行，且 WSL2 后端已启用（不是 Hyper-V）。
devcontainer.json 必须放在项目根目录的 .devcontainer/ 下
这个文件不是可选配置，也不是 Dockerfile 的替代品。没有它，点 “Reopen in Container” 只会弹出镜像选择框，后续无法预装插件、转发端口或执行初始化命令。
关键字段不能空或冲突：
-
"image"和"build"必须二选一，不能都空，也不能同时存在 - 用
"image"时，优先选官方预置镜像，如"mcr.microsoft.com/vscode/devcontainers/python:3.11"；别直接用python:3.11-slim，它缺git、curl、bash，连pip install都可能失败 -
"forwardPorts"不写，容器里跑的flask run或npm start就不会在 VSCode 右下角显示可点击链接，宿主机也打不开localhost:5000 -
"customizations.vscode.extensions"必须显式声明，例如["ms-python.python", "esbenp.prettier-vscode"]；容器里不会自动同步你本地装的插件
权限和挂载路径混乱是 Git 提交失败的常见原因
默认挂载进来的代码目录属主是 root，你在 VSCode 里新建文件，ls -l 看到的是 root:root；但本地 git 操作又以你自己的 UID 运行，混着来就触发 permission denied 或状态异常。
解法直白有效：
- 在
devcontainer.json中加"remoteUser": "vscode"和"runArgs": ["--user", "vscode"] - 如果用了自定义
Dockerfile，必须在里面创建该用户：RUN useradd -m -u 1001 -G sudo vscode，再USER vscode -
"containerUser"字段才是真正决定 VSCode Server 和/workspace写入权限的；"remoteUser"只影响你手动打开终端时的默认用户，一般不用单独设
连不上 Docker daemon？先查 docker info 输出
Remote-Containers 不走 SSH，是直连本地 /var/run/docker.sock。报错 "Cannot connect to the Docker daemon" 几乎全是权限或配置问题：
- 终端执行
docker info，若返回permission denied，说明 Docker CLI 未正确授权，不是网络不通 - 跨主机连接（如 Windows 主机连 Linux 服务器）需改
/etc/docker/daemon.json加"hosts": ["tcp://0.0.0.0:2375"]并开放防火墙端口——注意2375不加密，生产环境禁用 - VSCode 本身不管理 Docker，它只是调用你本地的
docker命令；没装好 CLI 或 daemon 不响应，所有功能都会卡在 “Building image…”
devcontainer.json 字段语义、以及 daemon 连接方式这四点，最容易被跳过或误配，一旦出问题，现象就是“看着像连上了，但改不了文件、跑不起服务、提交不了 Git”。
