VSCode本身不运行Docker容器代码，真正执行环境在容器内；Remote-Containers扩展实现编辑、终端、调试投射进容器，依赖.devcontainer/devcontainer.json配置文件位于项目根目录下隐藏子目录，且需确保Docker服务正常、用户已加入docker组、端口转发与containerUser配置正确。
VSCode 本身不运行 Docker 容器中的代码，真正执行的是容器内的环境；Remote-Containers 扩展才是让编辑、终端、调试全部发生在容器里的关键组件。
Remote-Containers 扩展装了但“Reopen in Container”没反应
不是扩展失效，而是 VSCode 根本没识别到开发容器配置。它只认项目根目录下 .devcontainer/devcontainer.json 这个路径和文件名，少一个字符或放错位置都不行。
- 检查文件是否真在
.devcontainer/devcontainer.json（注意是点开头的隐藏目录，不是直接放在项目根目录下的devcontainer.json） - 确认
docker --version和docker ps能在 VSCode 内置终端中成功执行 - Linux 用户常见静默失败：用户没加入
docker组，执行sudo usermod -aG docker $USER后必须完全退出图形会话再重登（newgrp docker不够） - Windows/macOS 用户要确保 Docker Desktop 正在运行，且设置里启用了 WSL2 后端（Windows）或 “Use Docker CLI from the terminal”（macOS）
devcontainer.json 中 image 和 build 到底选哪个
选 image 是为了快和稳，选 build 是为了可控和复现——90% 的新项目该从 image 开始。
- 新手/验证阶段直接填
"image": "mcr.microsoft.com/vscode/devcontainers/python:3.11"，这是微软官方维护的镜像，自带git、curl、make、vscode-server，不会出现pip install失败或command not found - 想定制才用
"build": { "dockerfile": "Dockerfile" }，但你的Dockerfile必须基于mcr.microsoft.com/devcontainers/base:ubuntu或至少显式安装vscode-server，否则容器启动后只有黑屏终端 - 别拿生产镜像硬凑，比如
python:3.11-slim缺基础工具，node:20-alpine缺glibc，连pip install --upgrade pip都可能报错
容器里能跑代码，但断点不命中、浏览器打不开 localhost:5000
问题不在代码，而在路径映射和端口暴露没对齐——VSCode 调试器和浏览器看到的 “localhost”，默认不等于容器内的网络上下文。
-
forwardPorts必须写，比如 Flask 项目就填"forwardPorts": [5000]；它让 VSCode 自动做localhost:5000 → 容器:5000映射，不写就只能靠docker port查端口再手动输 - Python 调试断点不命中？检查
launch.json是否配了sourceFileMap："sourceFileMap": { "/workspaces/your-project": "${workspaceFolder}" } - 服务必须监听
0.0.0.0:5000，不能只绑127.0.0.1:5000；Flask 示例：app.run(host='0.0.0.0', port=5000) - 检查
python.defaultInterpreterPath是否指向容器内真实路径（如/usr/local/bin/python），而不是宿主机路径
为什么终端打不开、插件不生效、文件改不了
根本原因是没设 "containerUser": "vscode"。官方镜像（如 python:3.11）默认只有 root，而 VSCode Server 启动后会以该用户身份写 /home/vscode/.vscode-server——没这个目录或没写权限，直接报错。
-
containerUser决定三件事：VSCode Server 进程归属、挂载进来的项目目录属主、/home/vscode是否可写 - 如果用自定义
Dockerfile，必须显式创建用户并设好 home 目录：RUN useradd -m -u 1001 -G sudo vscode && chown -R vscode:vscode /home/vscode -
remoteUser没用：它只影响你手动打开的终端，不解决 VSCode 自身的权限问题 - 别用
root：会导致本地挂载卷文件属主变成root:root，主机上无法直接git commit或编辑
最常被忽略的其实是 containerUser 和服务监听地址这两个点——前者导致整个开发环境卡在空白终端，后者让端口转发形同虚设。它们不出错时一切正常，一出就是“什么都对，但就是不工作”的状态。
