必须用devcontainer.json配置，镜像优先选mcr.microsoft.com/vscode/devcontainers/python:3.11而非python:3.11-slim；需置于项目根目录下.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]。
立即学习“Python免费学习笔记（深入）”；
这个字段不是可选功能，是调试刚需：
- 不填，端口默认不暴露，
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": "devuser""runArgs": ["--user", "1001:1001"] - 如果镜像里没有对应用户，需配合
Dockerfile创建：RUN groupadd -g 1001 devuser && useradd -u 1001 -g devuser devuser - 别用
"runArgs": ["-u", "root"]—— 表面能过pip install，但git会因 umask 和 home 目录权限持续出错
镜像选错，后续全是坑
python:3.11-slim 看似轻量，但缺 git、curl、gcc、openssh-client，连 pip install 某些包都会失败；更关键的是它没预装 vscode-server，导致 Remote-Containers 启动卡死或反复重连。
mcr.microsoft.com/vscode/devcontainers/python:3.11 是专为 VSCode 设计的镜像，自带：
- 完整开发工具链（
git、curl、make、gcc） - 预配置的
vscode-server和devcontainer支持逻辑 - 非 root 默认用户（UID/GID 自动映射兼容性更好）
如果你真需要 slim 镜像，必须手动补全所有依赖，且确保 vscode-server 安装成功——这比直接换镜像成本高得多。
