VSCode远程容器开发_Dev Containers标准环境快速搭建-VSCode-PHP中文网

dev containers配置文件必须置于.devcontainer/目录下且命名为devcontainer.json或dockerfile；手动创建需先建目录再放文件，推荐用vscode命令自动生成；优先使用features而非自写dockerfile；避免混用dockerfile与features；勿误配mounts覆盖默认源码挂载；windows用户需确保wsl2及docker desktop正常运行；修改配置后须“rebuild container”生效。

vscode远程容器开发_dev containers标准环境快速搭建

Dev Containers配置文件必须放在 .devcontainer/ 目录下

VSCode 读取 Dev Containers 配置时，只认 .devcontainer/devcontainer.json（或 .devcontainer/Dockerfile），不能放在项目根目录平级、也不能叫 devcontainer.yaml 或 .devcontainer.json（少个斜杠就失效）。常见错误是手动生成了 devcontainer.json 却没建 .devcontainer 文件夹，结果点击 “Reopen in Container” 没反应——VSCode 根本没发现配置。

实操建议：

用 VSCode 命令面板（Ctrl+Shift+P / Cmd+Shift+P）运行 Dev Containers: Add Development Container Configuration Files...，它会自动创建正确路径和基础模板
手动创建时，先建文件夹：mkdir -p .devcontainer，再放 devcontainer.json
如果项目已有 Dockerfile，可直接在 devcontainer.json 中通过 "dockerFile": "Dockerfile" 引用，但该文件仍需位于 .devcontainer/ 下或其子路径（如设为 "dockerFile": "Dockerfile.base" 就得把文件放进去）

devcontainer.json 中的 "features" 比自写 Dockerfile 更快更稳

很多人习惯从头写 Dockerfile 装 Python、Node、Rust 等工具链，但官方维护的 features（比如 ghcr.io/devcontainers/features/python:1）已预编译好二进制、处理好权限、适配多平台（x86/arm64），还能自动更新。自己写容易漏掉 non-root user 权限配置，导致 VSCode 终端默认以 root 运行，后续 npm install 或 pip install 出权限错误。

实操建议：

优先用 "features" 字段声明依赖，例如：

"features": {
  "ghcr.io/devcontainers/features/python:1": {
    "version": "3.12"
  },
  "ghcr.io/devcontainers/features/node:1": {
    "version": "20"
  }
}

避免在 devcontainer.json 中混用 "dockerFile" 和 "features"——前者会完全接管构建过程，features 不生效
想加自定义命令？用 "onCreateCommand" 或 "postCreateCommand"，而不是塞进 Dockerfile 的 RUN 指令里（后者无法访问挂载的源码，也难调试）

挂载源码时别用 "mounts" 覆盖工作区路径

默认情况下，VSCode 把本地项目目录作为 volume 挂载到容器内 /workspaces/<folder-name></folder-name>。如果在 devcontainer.json 中误配 "mounts"，比如写成 "source=/path/on/host,target=/workspace,type=bind,consistency=cached"，就会覆盖默认挂载，导致打开的文件不是你编辑的那批，Git 状态异常，甚至保存后本地没变化。

VSCode

避免常见的 VSCode 错误——设置冲突、调试器配置和扩展冲突。

下载

实操建议：

除非有特殊需求（如共享某个配置目录），否则不要碰 "mounts" 字段
需要额外挂载？用 "remoteEnv" + "containerEnv" 控制环境变量，或通过 "postCreateCommand" 创建符号链接
确认挂载是否正常：进容器执行 ls -l /workspaces，应看到你的项目名目录；再 cat /proc/mounts | grep workspace，验证 source 路径是你本地项目根

Windows 用户注意 WSL2 后端与 Docker Desktop 的状态耦合

在 Windows 上，VSCode Dev Containers 实际依赖 WSL2 中的 Docker daemon。如果 Docker Desktop 没启动、或 WSL2 发行版（如 Ubuntu-22.04）被关机、或 docker context 切到了远程主机，VSCode 就会卡在 “Building image…” 或报错 Cannot connect to the Docker daemon，而界面提示往往只写 “Failed to start dev container”。

实操建议：

终端里先跑 docker info，确保输出正常；再运行 wsl -l -v，确认默认发行版状态是 Running
VSCode 设置里搜 dev containers docker path，检查 remote.containers.dockerPath 是否为空（应为空，让它走默认）
如果用 WSLg 或 GUI 工具，记得在 WSL 中执行 sudo service docker start（Docker Desktop 自动管理时通常不需要，但手动安装过 docker-ce 的用户容易忽略）

最常被忽略的是：改完 devcontainer.json 后没点 “Rebuild Container”，而是点了 “Reopen in Container”——后者复用旧镜像，所有新配置都不生效。重装依赖、换 Python 版本、加 features，都得 rebuild。