结论是：必须用devcontainer.json配置，镜像优先选mcr.microsoft.com/vscode/devcontainers/python:3.11而非python:3.11-slim；权限不配对将导致git commit和pip install失败；文件须置于项目根目录下.devcontainer/devcontainer.json路径，且至少包含image、build或customizations.vscode.extensions之一，同时需配置forwardports和remoteuser+runargs以解决端口暴露与文件权限问题。
直接说结论：用 devcontainer.json 配，别手写 docker run；镜像优先选 mcr.microsoft.com/vscode/devcontainers/python:3.11，不是 python:3.11-slim；用户权限不配对，git commit 和 pip install 早晚崩。
devcontainer.json 必须放对位置、字段不能少
VSCode 只认项目根目录下 .devcontainer/devcontainer.json 这一个路径，放错地方（比如放在根目录或 .vscode/ 下）就完全没反应。
以下三个字段至少得有其一，否则卡在 “Building image…” 或进容器后没终端：
-
"image"：快速验证用，例如"mcr.microsoft.com/vscode/devcontainers/python:3.11-bullseye" -
"build"：要加系统包（如libpq-dev、curl）时必须用，且Dockerfile要放在.devcontainer/Dockerfile，内容必须基于dev-containers/base或显式安装vscode-server -
"customizations.vscode.extensions"：必须显式列出插件，比如["ms-python.python", "esbenp.prettier-vscode"]；容器里不会继承你本地装的插件
forwardPorts 不填，Flask/Django 就等于白跑
你在容器里 flask run --port=5000，宿主机浏览器打不开 localhost:5000？大概率是漏了 "forwardPorts": [5000]。
这个字段不是可选功能，是调试刚需：
- 不填，端口默认不暴露，
curl localhost:5000在宿主机上直接失败 - 多个服务要同时调试？写成数组，比如
[5000, 8000, 3000] - 填了但还是打不开？先确认容器内服务确实监听
0.0.0.0:5000，不是127.0.0.1:5000
remoteUser + runArgs 是文件权限问题的唯一稳解
新建的 Python 文件在 VSCode 里显示为 root:root，但 git status 却报 permission denied？这是最常被忽略的权限断裂点。
根本原因：宿主机 UID（比如 1001）和容器内默认用户（通常是 root）不匹配。解决方式只有一套组合拳：
- 在
devcontainer.json加这两行："remoteUser": "vscode""runArgs": ["--user", "vscode"] - 如果用了自定义
Dockerfile，必须在里面创建该用户：RUN useradd -m -u 1001 -G sudo vscodeUSER vscode - 别用
"containerUser": "root"应急——所有生成文件属主都是root，协作时别人git pull后改不了文件，npm install也会因权限拒绝失败
Docker daemon 连不上？先别怀疑网络
点 “Reopen in Container” 没反应，或者弹出 Failed to connect to Docker daemon，90% 是本地环境没准备好，跟网络无关。
按顺序检查这三件事：
- 终端执行
docker info --format '{{.OSType}}'，必须返回linux/darwin/windows；返回空或报错，说明 Docker CLI 根本没通 - Linux/macOS 用户确认当前用户在
docker组：groups命令输出里要有docker；没有就运行sudo usermod -aG docker $USER，然后彻底退出终端重登（newgrp docker不生效） - 别用
sudo code启动 VSCode——它会让容器内进程 UID 错乱，后续所有文件操作都可能出权限问题
真正麻烦的从来不是“怎么起容器”，而是“为什么 git 提交不了”“为什么 pip 安装报 permission denied”——这些几乎全指向同一个地方：remoteUser 和 runArgs 没配，或者配了但 Dockerfile 里没真正创建那个用户。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
