必须满足三个硬性前提：本地或远程宿主机装好Docker、VSCode装了Remote-Containers插件、项目根目录下存在有效的.devcontainer/devcontainer.json；缺一不可，否则“Reopen in Container”将失败。
能直接用，但必须满足三个硬性前提：本地或远程宿主机装好 Docker、VSCode 装了 Remote-Containers 插件、项目里有有效的 .devcontainer/devcontainer.json。 缺任何一个，点“Reopen in Container”都只会卡在构建或连接阶段，不是插件问题，是链路断了。
devcontainer.json 是启动容器的唯一入口文件
VSCode 不会自动猜你要用什么镜像或装什么工具，全靠这个 JSON 文件驱动。它不叫配置“模板”，而是运行时指令清单。
常见错误现象：Dev Container Configuration not found、点击左下角绿色箭头后无反应、F1 里搜不到 Remote-Containers: Reopen in Container
- 必须放在项目根目录下的
.devcontainer/子目录中（路径是.devcontainer/devcontainer.json，不能放错位置） - 文件名大小写敏感，不能写成
DevContainer.json或devcontainer.JSON - 如果只写
"image": "node:18"，VSCode 会直接拉取并启动——但没指定forwardPorts就看不到服务，没写postAttachCommand就得手动装依赖 - 想复用官方镜像但加点东西？优先用
"features"字段，比如"git": "latest"比自己写 RUN apt install 更轻量、更可缓存
Dockerfile 和 image 二选一，别混着用
devcontainer.json 里要么填 "image" 指向已有镜像，要么填 "build" 指向本地 Dockerfile，不能同时存在，否则 VSCode 会报错 Invalid devcontainer configuration: only one of 'image' or 'build' is allowed。
使用场景差异：
- 快速验证或单语言小项目 → 直接用
"image": "mcr.microsoft.com/vscode/devcontainers/python:3.11"，微软维护，预装pip、git、curl等基础工具 - 需要定制 Python 包、私有 CLI 工具、非标准系统库 → 写
Dockerfile，并在devcontainer.json中写"build": { "dockerfile": "Dockerfile" } - 注意：
build.context默认是.devcontainer/目录，如果Dockerfile在项目根目录，得显式写"context": ".."
端口转发和文件挂载是默认开启的，但行为不可见
VSCode 启动容器时，会自动把项目目录以 volume 方式挂载进容器的 /workspace（除非你改了 workspaceFolder），也会自动做 localhost:3000 → container:3000 的端口映射——但前提是你在 devcontainer.json 里写了 "forwardPorts": [3000]。
容易踩的坑：
- 前端跑在
localhost:5173，但没加到forwardPorts数组里 → 浏览器打不开，查日志也看不出问题 - 容器内程序监听
127.0.0.1:8000→ 主机连不上，必须改成0.0.0.0:8000（这是容器网络模型决定的，不是 VSCode 的锅） - 用
postAttachCommand跑npm run dev，但命令退出后终端就断了 → 改成"onCreateCommand"或加&后台运行，否则调试器连不上进程
离线环境必须提前准备好 vscode-server
Remote-Containers 在容器里运行的不是“VSCode 客户端”，而是 vscode-server——一个精简版服务进程。它默认从微软 CDN 下载，离线时会卡死在 Installing VS Code Server 步骤，且不报错、不超时、不重试。
解决方法只有两个：
- 在有网机器上先跑一次完整流程，让 VSCode 自动下载并缓存
vscode-server；之后把整个~/.vscode-server目录打包复制到离线宿主机对应路径 - 在
Dockerfile里用COPY把提前下载好的vscode-server二进制文件打进镜像，并通过"overrideCommand": true和自定义 entrypoint 启动它（复杂度高，仅建议企业级标准化场景）
别指望用 --network=host 或代理绕过——vscode-server 的下载逻辑是硬编码的，不走系统代理，也不读环境变量。
