VSCode远程容器连接失败主因是容器内环境未被正确接管，需检查权限（containerUser配置）、插件（Remote-Containers扩展及devcontainer.json中customizations.vscode.extensions声明）、端口监听（服务须绑定0.0.0.0而非127.0.0.1）。
能直接连上正在运行的容器，但绝大多数失败不是因为连不上，而是容器内环境没被 VS Code 正确接管——权限、插件、端口监听这三点卡住就动不了。
Remote - Containers 扩展必须装对位置
它只在本地 VS Code 安装，不进容器；但它的作用是让本地 UI 控制容器内的语言服务器、调试器和格式化工具。漏装或装错（比如装成 Remote-SSH）会导致“容器连上了，但 Python 不识别语法、F5 按钮灰掉”。
- 打开 Extensions 视图（
Cmd+Shift+X或Ctrl+Shift+X），搜Remote - Containers，认准发布者是Microsoft - 别装
Remote Development扩展包——它包含三个子扩展，但 Dev Containers 场景下只要Remote - Containers单独一个就够了 - 确认本地
docker --version可执行，且 Docker Desktop / daemon 处于运行状态
devcontainer.json 必须放在 .devcontainer/ 目录下
VS Code 只扫描项目根目录下的 .devcontainer/devcontainer.json（或 .devcontainer/Dockerfile）。放错路径（比如直接丢在项目根目录叫 devcontainer.json）会导致命令面板里压根不出现 Reopen in Container 选项。
- 手动创建时，先运行
mkdir -p .devcontainer，再把配置文件放进该目录 - 推荐用命令面板（
Ctrl+Shift+P）执行Dev Containers: Add Development Container Configuration Files，它会自动生成正确路径和基础模板 - 如果项目已有
Dockerfile，可在devcontainer.json中写"dockerFile": "Dockerfile"，但该文件仍需放在.devcontainer/下或其子路径中
containerUser 不设等于白配
官方镜像（如 python:3.11）默认只有 root 用户，而 VS Code Server 进程需要以非 root 用户身份写入 /home/vscode/.vscode-server。不设 "containerUser": "vscode"，终端打不开、插件装不上、/workspace 文件改不了都是常态。
- 用微软官方镜像（如
mcr.microsoft.com/vscode/devcontainers/python:3.11）可跳过用户创建，但必须显式声明"containerUser": "vscode" - 用自定义
Dockerfile时，必须加两行：RUN useradd -m -u 1001 -G sudo vscode和USER vscode，否则pip install --user会因$HOME不可写失败 -
"remoteUser"是无效字段——它只影响你手动打开的终端，默认继承containerUser，不解决 VS Code 自身权限问题
forwardPorts 生效的前提是服务监听 0.0.0.0
配置了 "forwardPorts": [5000] 却在浏览器打不开 localhost:5000？大概率是 Flask/FastAPI/Spring Boot 绑定了 127.0.0.1:5000，只接受容器内部访问。VS Code 的端口转发只是把宿主机请求发到容器 IP，但容器内服务必须监听 0.0.0.0 才能响应。
- Flask：启动时加
app.run(host='0.0.0.0', port=5000) - FastAPI：用
uvicorn main:app --host 0.0.0.0 --port 5000 - 验证方式：进容器终端执行
netstat -tuln | grep :5000，看到0.0.0.0:5000才算对 - 别依赖
localhost绑定——它在容器网络里等价于127.0.0.1，不是宿主机的localhost
最容易被忽略的是：customizations.vscode.extensions 里没填 ms-python.python 或 ms-vscode.cpptools，容器里就没有对应语言支持；哪怕你本地装了一百个插件，对容器内零影响。Dev Containers 是两套独立环境，插件必须明确声明在配置里才进容器。
