Dev Containers 是将开发环境打包进 Docker 容器的沙盒方案，核心配置文件 devcontainer.json 必须位于 .devcontainer/ 目录下且语法正确，否则 VSCode 不识别；image 与 build 字段不可共存，端口转发需服务监听 0.0.0.0，挂载推荐显式配置 workspaceMount 而非依赖默认路径。
Dev Containers 不是用来“连远程服务器”的，它是把整个开发环境打包进 Docker 容器，在本地或远程宿主机上启动一个隔离、可复现、与宿主解耦的沙盒工作区。
devcontainer.json 是唯一入口，路径和结构错一个就失效
VSCode 只识别项目根目录下的 .devcontainer/devcontainer.json ——不是 devcontainer.json（少点），不是 .devcontainer.json（是文件不是目录），也不是 .vscode/devcontainer.json（位置错）。这个文件一旦存在且语法合法，右下角才会出现 Reopen in Container 按钮。
-
"image"和"build"字段不能共存，同时出现会直接报错Invalid devcontainer.json: 'image' and 'build' cannot both be specified - 空文件、只有注释、或顶层字段拼错（比如写成
images）都会导致 VSCode 忽略该配置 - Windows + WSL2 用户必须从 WSL 终端执行
code .，用 Windows 版 VSCode 双击打开项目，Remote - Containers扩展基本不工作
容器内命令找不到？大概率是 shell 初始化没走通
很多工具（nvm、conda、sdkman、甚至 git）依赖 shell 的 login 或 interactive 模式加载初始化脚本。Dev Containers 默认以 /bin/bash --login 启动，但某些镜像或配置会跳过 profile 加载。
- 确认
devcontainer.json中设了"terminal.integrated.defaultProfile.linux": "bash" -
nvm需显式 source："postCreateCommand": "source ~/.nvm/nvm.sh && nvm use 18" -
conda同理："postCreateCommand": "source /opt/conda/etc/profile.d/conda.sh && conda activate base" -
git报错please tell me who you are？补上："postCreateCommand": "git config --global user.name 'xxx' && git config --global user.email 'xxx@example.com'
端口转发不通？服务监听地址写死了 127.0.0.1
VSCode 的端口转发机制只代理绑定到 0.0.0.0 或 :: 的服务。如果应用默认监听 127.0.0.1:3000，容器内 curl localhost:3000 能通，但宿主机访问 localhost:3000 就超时。
- Flask：启动加
--host=0.0.0.0 --port=3000 - Next.js：设环境变量
NEXT_HOST=0.0.0.0 - Node HTTP server：确保
server.listen(3000, '0.0.0.0')，别漏掉第二个参数 - 检查是否被框架默认禁用：比如 Django 的
DEBUG=False会拒绝非ALLOWED_HOSTS请求，需同步配好
挂载代码不稳定？别依赖默认 /workspace，显式配 workspaceMount
VSCode 默认把工作区挂到容器内 /workspace，但这个行为在符号链接、WSL/Windows 混合路径、网络文件系统等场景下极易出问题：文件修改不触发保存、git status 不更新、甚至编辑后内容丢失。
- 改用显式挂载：
"workspaceMount": "src=/path/on/host,dst=/workspace,type=bind,consistency=cached" - Linux/macOS 下推荐
consistency=cached；Windows+WSL2 推荐delegated - 避免挂载整个
~或/home/vscode到本地，会覆盖容器预置的用户配置和 dotfiles - 若需复用本地
~/.npm或~/.cargo，单独用"mounts"字段挂载，路径要精确到子目录
真正麻烦的从来不是写配置，而是默认行为在不同系统、不同 Docker 后端、不同 shell 初始化链路下的隐式差异——这些地方不手动验证一遍，Reopen in Container 后看似进去了，其实只是个半残废环境。
