VS Code 怎样为已有项目添加 Dev Container 配置

已有项目第一次交给多人维护时，最容易失控的不是业务代码，而是每个人本机上的运行时、命令行工具和编辑器扩展不一致。VS Code 的 Dev Containers 扩展可以从现有项目出发生成容器配置，让项目用一套可提交的开发环境描述启动。

官方地址：https://code.visualstudio.com/docs/devcontainers/create-dev-container

这篇只讲一个具体任务：打开一个已经存在的项目，使用 Dev Containers: Add Dev Container Configuration Files... 生成起始配置。它不展开 Docker 镜像制作、生产部署，也不把生成的界面当成真实截图；文中的界面图是操作说明图。

开始前先确认三个入口

先把目标项目打开到 VS Code 的本地窗口。机器上需要能使用 Docker，VS Code 里还要安装 Dev Containers 扩展。官方文档把 Docker 本地安装、远程 Docker 主机和兼容 CLI 都列为可选运行方式；本文按最常见的本地 Docker 方式说明。

如果命令面板里搜不到 Dev Containers，先在扩展视图安装该扩展，再重新打开项目。不要一开始就手工创建多个配置文件，因为命令向导会根据项目内容提供模板，也能识别已有的 Dockerfile 或 Docker Compose 文件。

从命令面板进入配置向导

在项目窗口按 F1（macOS 也可以按 ⇧⌘P），输入 Dev Containers: Add Dev Container Configuration Files... 并执行。也可以从 VS Code 的快速操作入口进入同一个命令。

命令执行后，向导会根据当前目录中的文件给出可筛选的起始配置列表。这里的“起始”很重要：它负责生成可继续编辑的骨架，不代表项目已经完成全部依赖安装。

选择模板，还是复用项目已有配置

如果项目还没有容器配置，可以在模板列表里选择与项目语言和工具链接近的模板。例如 Node.js、Python 等模板会提供基础镜像和常见目录结构。列表会参考当前项目内容排序，但最终仍要按仓库实际依赖选择。

如果项目根目录已经有 Dockerfile 或 Docker Compose 文件，优先选择复用现有文件的入口。这样可以让开发容器继续使用团队已经维护的构建边界，避免向导再生成一套与现有环境平行的镜像定义。

选择时可以用下面这张判断表：

按项目需要添加 Features

模板确定后，向导通常还会进入 Features 选择。Features 是可以复用的工具安装和配置单元，适合添加 Git、语言运行时或 CLI 工具。只选择项目确实需要的项，避免把个人偏好的工具写进团队公共配置。

选择完成后继续。向导会把选择写入项目里的 Dev Container 配置。对于需要固定版本的工具，不要只依赖 latest；可以在生成后按团队的升级策略改成明确版本，并在提交前让维护者知道这个变更会影响构建环境。

检查生成的 devcontainer.json

完成向导后，重点查看项目中的 .devcontainer/devcontainer.json。VS Code 官方也支持把配置放在项目根目录的 .devcontainer.json，但团队项目通常使用 .devcontainer/devcontainer.json，因为 Dockerfile 和 Compose 扩展文件可以放在同一个目录中。

下面是一个可读的最小示例。JSON 本身不支持注释，所以把每个字段的作用写在代码块外，保持文件可以直接被工具解析：

{
  "name": "team-dev",
  "image": "mcr.microsoft.com/devcontainers/typescript-node",
  "forwardPorts": [3000],
  "customizations": {
    "vscode": {
      "extensions": ["dbaeumer.vscode-eslint"]
    }
  }
}

name用于标识开发容器，image指定起始镜像，forwardPorts描述需要从容器访问的端口，customizations.vscode.extensions则指定容器内安装的扩展。若项目需要根据源码安装依赖，可以再考虑 postCreateCommand；如果是镜像层面的工具，Dockerfile 往往更容易缓存和复用。

重新打开并确认配置真的生效

回到命令面板，执行 Dev Containers: Reopen in Container。第一次打开会构建容器，VS Code 会显示进度通知；构建结束后窗口会自动连接到容器。之后再次打开这个项目时，VS Code 会复用仓库中的配置。

如果你刚修改了 devcontainer.json、Dockerfile 或 Compose 文件，执行 Dev Containers: Rebuild Container，而不是只重新打开窗口。判断成功时看三个可见状态：左下角出现容器连接指示，项目文件仍然可访问，容器内终端可以使用模板或 Features 提供的工具。

# 用命令面板重新构建，让配置文件的修改进入新容器
# 先保存 .devcontainer 目录中的文件，再执行 Rebuild Container
echo "请在 VS Code 命令面板执行：Dev Containers: Rebuild Container"

# 构建完成后，在容器终端确认当前环境，而不是检查宿主机终端
printf 'container workspace ready\\n'

上面的命令块只用来提示验收位置，并不代替 VS Code 的构建过程。真正的成功标志是窗口已经重新连接到容器，且项目使用的是容器内的运行时。

两个常见选择失误

把模板当成最终生产镜像

模板解决的是开发环境起步，不等于生产镜像的安全、体积和发布策略。生成后应把团队真正需要的字段留下，把试用工具删掉，并把变更提交给项目维护者审阅。

改完文件却没有重建

编辑配置文件不会自动让当前容器重新构建。看到文件已经保存并不代表容器已经加载新字段；只要涉及镜像、Features、端口或安装命令，就执行 Rebuild Container，再从容器内的状态确认。

相关问题

已有 Dockerfile 还需要 devcontainer.json 吗？

需要。Dockerfile 描述镜像如何构建，devcontainer.json 负责告诉 VS Code 如何使用这个镜像、安装扩展、转发端口和进入工作区，两者职责不同。

为什么选择了 Feature，容器里却没有新工具？

通常是只重新打开了窗口，没有让配置重新构建。保存配置后执行 Rebuild Container，并查看容器构建通知和容器内终端。

团队应该把哪些文件提交到 Git？

一般提交 .devcontainer/devcontainer.json 以及它引用的 Dockerfile、Compose 扩展文件和必要脚本；不要提交本机密钥、个人路径、临时缓存或含凭据的环境文件。

最短路径是：打开已有项目 → F1 → 执行 Add Dev Container Configuration Files → 选模板或已有 Dockerfile/Compose → 选必要 Features → 检查 .devcontainer → Rebuild/Reopen in Container。这样生成的配置才真正进入团队项目，而不是只停留在当前电脑。