VS Code Dev Containers 怎样让项目依赖在容器内一致

VS Code Dev Containers 要做到“每个人装出来都一样”，关键不是把命令写在团队群里，而是把镜像、扩展、Features、依赖安装和工作区路径一起写入项目的 .devcontainer/devcontainer.json。新成员打开仓库后执行一次重建，运行时和开发依赖就由容器配置负责。

官方地址：https://code.visualstudio.com/docs/devcontainers/containers/

1. 从命令面板生成项目级配置

打开项目根目录，按 F1，执行 Dev Containers: Add Dev Container Configuration Files...。选择与项目匹配的模板；如果仓库已经有 Dockerfile，也可以在向导中选择复用现有 Dockerfile。配置应放在 .devcontainer/devcontainer.json，这样它会跟着代码进入版本控制。

完成后先不要急着安装依赖。先检查资源管理器中是否出现 .devcontainer 目录，以及文件是否位于仓库根目录下。路径放错时，VS Code 可能找不到配置，团队成员就会回到手工创建容器的状态。

2. 把镜像、扩展和依赖安装写进 devcontainer.json

下面是一份适合 Node.js 项目的最小配置示例。它把基础镜像、编辑器扩展、端口和创建后安装动作集中在一个文件里；版本较稳定的项目还可以把 image 换成自定义 Dockerfile。

{
  // 固定团队使用的开发容器基础镜像
  "image": "mcr.microsoft.com/devcontainers/javascript-node:1-22-bookworm",
  "customizations": {
    "vscode": {
      // 扩展安装在容器环境，而不是依赖本机插件
      "extensions": ["dbaeumer.vscode-eslint"]
    }
  },
  // 只声明应用需要的端口，避免每个人手工转发
  "forwardPorts": [3000],
  // 创建容器后安装项目依赖；命令应能正常退出
  "postCreateCommand": "npm ci"
}

如果项目要使用可复用工具，可以在 features 中声明 Feature；需要安装系统包或编译工具时，把动作放入 Dockerfile 更适合，因为 Dockerfile 能利用构建缓存。不要把长期运行的服务写进 postCreateCommand，这个命令不退出会让容器创建流程一直停住。

3. 保存后重建并重新打开容器

保存 devcontainer.json 后按 F1，执行 Dev Containers: Rebuild and Reopen in Container。只修改配置文件不会让现有容器自动重建；如果只是执行 Reopen，仍可能使用旧镜像和旧依赖。

重建过程中，VS Code 会重新创建容器、安装声明的扩展，并执行 postCreateCommand。第一次构建时间较长属于正常现象。重建结束后，左下角的远程指示器应显示已连接到容器，资源管理器仍能看到项目源码。

4. 用三项状态确认依赖真的一致

验收不要只看“窗口打开了”。在容器内打开终端，依次确认工作区路径、运行时版本和依赖目录。下面命令只用于检查状态，中文注释说明每条检查的目的。

# 确认终端位于容器工作区，而不是宿主机目录
pwd

# 确认团队约定的 Node.js 主版本已经由容器提供
node --version

# 确认锁文件对应的依赖已经安装完成
test -d node_modules && echo "依赖目录已就绪" || echo "需要重新执行 npm ci"

再按 F1 执行 Dev Containers: Show Container Log，检查创建日志是否以成功状态结束；也可以打开 Remote Explorer，在 Containers 视图中确认目标容器正在运行。若扩展显示为本地安装，说明它没有写入 customizations.vscode.extensions。

5. 挂载与权限问题的处理边界

源码通常由 VS Code 挂载到容器工作区，容器重建不会删除宿主机源码；数据库文件、缓存或上传目录则应显式配置 volume 或 mounts，不要把持久化数据藏在容器可写层。若团队需要统一用户权限，可在容器配置中设置 remoteUser，避免 root 创建的文件让宿主机用户无法修改。

最后把 .devcontainer 纳入 Git，并在 README 记录“打开项目后执行 Rebuild”的入口。这样配置、依赖和验收标准才会一起交付。

常见问题

修改 devcontainer.json 后为什么看不到新扩展？

现有容器不会自动应用配置变化。执行 Dev Containers: Rebuild and Reopen in Container，让镜像和扩展重新按文件创建。

postCreateCommand 适合安装所有软件吗？

它适合创建后依赖安装和项目脚本；系统包、编译工具和耗时较长的固定步骤更适合放入 Dockerfile，以便利用构建缓存。

重建容器会删除项目代码吗？

通常不会，源码工作区来自本地挂载或复制的项目目录。但容器内部未声明持久化的临时数据可能消失，重要数据应使用 volume 或显式挂载。