VSCode直连Docker容器必须安装Remote-Containers扩展（ms-vscode-remote.remote-containers），它自动部署VSCode Server、同步配置与插件、支持端口转发和调试；需正确配置.devcontainer/devcontainer.json，处理用户权限、路径映射及多容器场景。
VSCode 直连 Docker 容器需要 Remote-Containers 扩展
必须安装官方 ms-vscode-remote.remote-containers 扩展，仅靠内置终端或 SSH 插件无法实现完整开发环境挂载和调试支持。该扩展会自动在容器内部署 VSCode Server，并同步本地工作区配置、插件（按需）、断点和调试器。
- 确保已安装 Docker Desktop（macOS/Windows）或
dockerCLI +dockerd服务（Linux），且当前用户在docker组中 - 不要用 root 启动 VSCode；否则容器内文件权限可能错乱，导致
npm install失败或 Git 权限拒绝 - 扩展首次连接时会自动构建镜像或拉取基础镜像，耗时取决于网络和镜像大小，耐心等待状态栏出现
Dev Container提示
推荐用 .devcontainer/devcontainer.json 而非 docker run 命令
手动 docker run -it -v $(pwd):/workspace ... 启动容器后打开文件，只是“挂载目录”，不等于“Dev Container 模式”——缺失自动插件安装、端口转发、非 root 用户初始化、postCreateCommand 等关键能力。
-
.devcontainer/devcontainer.json是唯一被 Remote-Containers 识别的配置入口，放在项目根目录下 - 必须指定
"image"或"build"字段，二者不可同时省略；若用自定义Dockerfile，路径写相对.devcontainer/Dockerfile - 常见漏配：
"customizations.vscode.extensions"不写会导致容器内无 Prettier/ESLint；"forwardPorts"不设则localhost:3000在宿主机打不开
{
"image": "mcr.microsoft.com/devcontainers/python:3.11",
"customizations": {
"vscode": {
"extensions": ["ms-python.python", "esbenp.prettier-vscode"]
}
},
"forwardPorts": [3000, 8000],
"postCreateCommand": "pip install -r requirements.txt"
}
容器内用户权限和文件属主问题最常导致启动失败
VSCode 默认以 UID/GID 与宿主机当前用户一致的方式运行容器内进程。若基础镜像用 root 用户且未创建匹配 UID 的用户，git clone、npm ci 或编辑文件会报 Permission denied。
- 优先在
Dockerfile中用USER node或USER 1001:1001（查宿主机id -u和id -g）显式切换 - 若必须用 root 构建，可在
devcontainer.json加"remoteUser": "root"，但不推荐——后续所有文件属主都会是 root - 挂载卷内已有文件（如
node_modules）属主不匹配时，postCreateCommand可加chown -R $(whoami) .临时修复
调试 Python/Node.js 时端口和路径映射必须显式声明
容器内服务监听 localhost:3000，不代表宿主机能直接访问；VSCode 调试器也需知道源码路径如何对应容器内路径，否则断点不生效。
-
"forwardPorts"仅做 TCP 端口映射，不影响调试器行为；要启用调试，还需在launch.json中设置"justMyCode": true和"pathMappings" - Python 示例：若项目在容器内是
/workspace/myproj，本地路径是/Users/me/project，则pathMappings必须写{"/workspace/myproj": "${workspaceFolder}"} - Node.js 的
outFiles路径若含/workspaces/，而实际是/workspace/，断点会灰掉——检查容器内真实路径用pwd命令确认
多容器（如带 PostgreSQL 的 Compose 场景）需额外配置 "dockerComposeFile" 和 "service" 字段，且确保服务间网络互通，不是只靠端口转发。
