必须安装ID为ms-vscode-remote.remote-containers的官方插件，且项目根目录下需存在.devcontainer/devcontainer.json文件；否则VSCode不会触发容器开发流程，Reopen in Container将卡在加载或报错。
Remote-Containers 扩展必须装对 ID
装错插件就永远进不了容器——VSCode 商店搜 “Remote Containers” 会出现多个结果，唯一有效的 ID 是 ms-vscode-remote.remote-containers。装了第三方同名插件、或只装了 ms-vscode-remote.remote-ssh 或 ms-azuretools.vscode-docker，点 Remote-Containers: Reopen in Container 会卡在“正在加载”或直接报错 Cannot resolve the remote environment。
验证方式很简单：打开 VSCode 扩展面板，搜索已安装扩展，确认 ID 确实是 ms-vscode-remote.remote-containers；再看左下角状态栏，成功加载后应出现绿色的远程连接图标（⚡ 或 ?），点击能弹出容器相关操作菜单。
.devcontainer 目录和 devcontainer.json 缺一不可
VSCode 不会自动识别任意 Dockerfile 或 running container——它只认项目根目录下的 .devcontainer/devcontainer.json。没这个文件，Reopen in Container 就只会弹出镜像选择框，后续所有定制（端口转发、插件安装、初始化命令）全部失效。
-
"image"和"build"字段必须填且只能填其一：用预构建镜像就写"image": "mcr.microsoft.com/vscode/devcontainers/python:3.11"；想自定义就写"build": { "dockerfile": "Dockerfile" }，注意dockerfile路径是相对于.devcontainer/的 -
"forwardPorts"必须显式声明，比如[3000, 8000]，否则容器里跑的npm start或python -m http.server 8000在宿主机打不开localhost:8000，右下角Ports栏也不显示可点击链接 -
"customizations.vscode.extensions"漏配会导致容器内只有裸编辑器：没有ms-python.python就没法调试 Python，没esbenp.prettier-vscode就格式化失灵
容器内 UID/GID 不匹配会导致 Permission denied
VSCode 默认以宿主机当前用户的 UID/GID 启动容器内进程。如果基础镜像（比如官方 python:3.11-slim）只创建了 root 用户，又没创建对应 UID 的普通用户，git clone、pip install 或保存文件时就会直接报 Permission denied，连 /workspace 目录都写不进去。
解决方法不是加 sudo，而是改 Dockerfile：
FROM python:3.11-slim # 创建与宿主机 UID 匹配的用户（假设宿主机 UID=1001） RUN useradd -u 1001 -m -G root -s /bin/bash devuser USER devuser WORKDIR /workspace
或者更通用的做法：在 devcontainer.json 中加 "remoteUser": "devuser"，并确保 build 阶段已创建该用户。
首次启动慢？别急着关掉，关键步骤正在后台跑
点 Reopen in Container 后，VSCode 会依次做三件事：拉取/构建镜像 → 启动容器 → 安装扩展 → 运行 postCreateCommand。前两步耗时最长，尤其网络差时拉镜像可能卡住几分钟，但只要终端没报错、状态栏没变红，就别强制中断。
常见误判场景：
- 终端卡在
Building image...：检查 Docker 是否运行（docker info无 permission denied）、网络是否能访问 mcr.microsoft.com - 容器启动后插件一直“Installing…”：可能是扩展市场被墙，可在
devcontainer.json加"extensions": ["ms-python.python"]并提前下载离线包，或换国内镜像源 - 右下角
Ports不显示转发项：确认"forwardPorts"已写且容器内服务确实在监听对应端口（netstat -tuln | grep 3000）
真正容易被忽略的是：容器启动后，VSCode 会在后台静默安装语言服务器（如 pyright、rust-analyzer），这个过程不弹窗、不提示，但没装完就调试会失败——等状态栏右下角出现语言标识（如 Python）再开始写代码更稳妥。
