Remote-Containers扩展是唯一支持在VSCode中实现容器内编辑、运行与调试的方案；它依赖项目根目录下.devcontainer/devcontainer.json配置，需正确设置image或build、forwardPorts、sourceFileMap及remoteUser等字段，否则将导致启动失败、断点失效或权限错误。
Remote-Containers 扩展是唯一能让你在 VSCode 里真正“运行代码于容器中”的方案。其他插件（比如 ms-azuretools.vscode-docker）只能管理镜像或 exec 进容器，没法同步编辑、调试、终端上下文。
Remote-Containers 启动失败的常见原因
VSCode 不会自动识别任意 Dockerfile 或容器，它只认一个固定路径：.devcontainer/devcontainer.json。这个文件必须放在项目根目录下，且是隐藏目录（开头带点），不是 devcontainer.json 直接放根目录。
- Linux 用户常卡在静默失败：确认
docker ps能在 VSCode 内置终端里成功执行；若不行，说明用户没加入docker组，需运行sudo usermod -aG docker $USER并完全退出图形会话重登（newgrp docker不够） - Windows/macOS 用户要确保 Docker Desktop 正在运行，并检查设置：Windows 启用 WSL2 后端，macOS 开启 “Use Docker CLI from the terminal”
- 文件存在但启动卡在 “Building image…”：检查
devcontainer.json是否漏了必填字段，比如"image"或"build"二选一没写，或者"customizations.vscode.extensions"为空数组但没删掉该字段
devcontainer.json 里 image 和 build 怎么选
新手直接用 "image"，别碰 "build"——除非你明确需要定制基础环境或复现构建过程。
- 推荐起步镜像：
"image": "mcr.microsoft.com/vscode/devcontainers/python:3.11"（或其他语言对应版本），它自带git、curl、make、pip和vscode-server，不会出现command not found或pip install权限报错 - 别拿
python:3.11-slim或node:20-alpine硬凑：前者缺glibc和基础工具，后者缺bash和curl，连pip install --upgrade pip都可能失败 - 如果要用
"build"，Dockerfile 必须显式安装vscode-server（或基于mcr.microsoft.com/devcontainers/base:ubuntu），否则容器起来只有黑屏终端，VSCode 根本连不上
代码能跑，但断点不命中、localhost:5000 打不开
问题不在代码本身，而在路径映射和网络上下文没对齐——容器里的 localhost 和你浏览器访问的 localhost 默认不互通。
-
"forwardPorts"必须显式声明，例如 Flask 项目就写[5000]；不写就得手动查端口：docker port，再输完整地址 - Python 断点不命中？在
.vscode/launch.json里加"sourceFileMap"：{ "/workspaces/your-project": "${workspaceFolder}" }，否则调试器找不到宿主机路径对应的容器内路径 - 解释器路径别设成宿主机的，比如
/usr/bin/python3是错的；应指向容器内真实路径，如/usr/local/bin/python；虚拟环境也得在容器终端里建：python -m venv /workspaces/myproject/.venv
文件权限混乱、git 提交异常
默认挂载进容器的代码属主是 root，而你在宿主机用自己 UID 操作 git，混着来就会触发 permission denied 或 git 状态错乱。
- 在
devcontainer.json里加这两行："remoteUser": "vscode"和"runArgs": ["--user", "vscode"] - 如果用了自定义 Dockerfile，必须在里面创建该用户并加 sudo 组：
RUN useradd -m -u 1001 -G sudo vscode，否则pip install -g会因权限失败 - 别把
.git目录挂载进容器时设为只读，否则 commit 会失败；VSCode 默认挂载是可写的，除非你手动改了mounts配置
容器里跑代码不是“把代码扔进去”，而是让整个开发上下文（路径、用户、端口、调试器）都对齐。最容易被忽略的是 sourceFileMap 和 remoteUser 这两个字段——它们不报错，但会让断点失效、权限出问题，直到你花半天排查才发现是配置漏了。
