devcontainer.json必须至少包含"image"或"build"、"customizations.vscode.extensions"、"forwardPorts"三个字段，缺一不可；还需配置"remoteUser"和"runArgs"以解决文件权限问题。
VSCode 用 Remote-Containers 扩展配置 Docker，不是装个插件点几下就能跑通——核心是 devcontainer.json 的字段必须写对、顺序不重要但缺一不可，否则卡在 “Building image…” 或进容器后没终端、没插件、连不上端口。
devcontainer.json 必须填哪几个字段？
VSCode 只认项目根目录下 .devcontainer/devcontainer.json 这个路径，其他位置或文件名全无效。以下三个字段不能同时为空：
-
"image"或"build"：二选一。验证阶段直接用"image": "mcr.microsoft.com/vscode/devcontainers/python:3.11"；要加系统包（比如curl、git）就改用"build": { "dockerfile": "Dockerfile" }，且 Dockerfile 必须基于dev-containers/base镜像或显式安装vscode-server -
"customizations.vscode.extensions"：必须显式列出插件 ID，例如["ms-python.python", "esbenp.prettier-vscode"]；容器不会继承你本地装的插件 -
"forwardPorts"：调试时浏览器打不开服务，90% 是漏了这个。Flask 默认 5000、Next.js 默认 3000，就得写成[5000]或[3000, 5000]
“Reopen in Container” 没反应或报 Failed to connect to Docker daemon
这不是 VSCode 的问题，它只是调 docker 命令。先在终端里手动验证：
- 运行
docker info --format '{{.OSType}}'，应返回linux、darwin或windows - 运行
docker run --rm hello-world，确认基础能力正常 - Linux/macOS 用户检查是否在
docker用户组：groups命令输出里要有docker；没有就执行sudo usermod -aG docker $USER，然后彻底退出终端再重开（newgrp docker不生效） - 别用
sudo code启动 VSCode —— 容器内进程 UID 会错乱，后续git commit或npm install易失败
进容器后文件属主是 root，git status 显示 modified
宿主机 UID 和容器内用户不匹配导致。默认挂载的 /workspaces/xxx 目录属主是 root:root，但你在编辑器里新建文件，又以你自己的 UID 写入，Git 就认为权限变了。
- 最稳解法：在
devcontainer.json加这两行："remoteUser": "vscode""runArgs": ["--user", "vscode"] - 如果用了自定义
Dockerfile，必须在里面创建该用户：RUN useradd -m -u 1001 -G sudo vscode
并确保后续命令不切回root（比如别写USER root） - 别设
"remoteUser": "root"—— 虽然能过构建，但所有生成文件都是root:root，协作时别人拉代码后git add会直接 permission denied
调试时断点不命中，launch.json 里 pathMappings 怎么配？
容器内路径和宿主机路径不一致，VSCode 找不到对应源码。关键不是绝对路径，而是映射关系：
- 默认挂载点是
/workspaces/<folder-name>，所以"sourceFileMap"应该写成：{ "/workspaces/my-project": "${workspaceFolder}" } - 如果用了
mounts或mountsV2自定义挂载，映射路径要和实际target一致，比如挂到/app就得写{ "/app": "${workspaceFolder}" } - Python 调试还常漏掉
"justMyCode": false—— 否则进第三方库源码时断点失效
真正容易被忽略的是：容器用户 UID 必须和宿主机一致，且 remoteUser 和 runArgs --user 必须配对使用；只设一个，或者 Dockerfile 里没创建对应用户，都会让文件权限在 git / npm / pip 层面出连锁问题。
