VS Code Dev Container 生命周期脚本怎样区分执行阶段

VS Code Dev Container 生命周期脚本的区分标准只有两个：命令在哪里运行，以及在一次创建还是每次启动时运行。initializeCommand 在宿主机初始化，onCreateCommand 在容器首次创建后运行，postStartCommand 则在容器每次成功启动时运行。把这三个阶段分开后，最常见的“依赖重复安装”和“宿主机命令跑进容器”问题就能避免。

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

最终结果：三个脚本各自只做一类工作

可以把一份配置想成三层：宿主机层负责准备“容器还看不到的东西”，创建层负责把容器第一次变成可用环境，启动层负责每次恢复工作区时都要做的轻量动作。下面的示例只覆盖标题限定的三个属性，不把 updateContentCommand、postCreateCommand 和 postAttachCommand 混入判断。

第一步：从命令面板进入 Dev Container 配置

打开项目后按 F1（macOS 也可以按 ⇧⌘P），输入 Dev Containers: Reopen in Container。如果只是修改了 .devcontainer 文件，选择 Dev Containers: Rebuild Container 让配置重新生效；配置文件通常位于项目的 .devcontainer/devcontainer.json。

编辑前先确认你看的是本地项目窗口，而不是已经附加到另一个容器的窗口。下图是一个原创的界面说明图，展示命令面板、配置文件位置和三个生命周期字段的对应关系，不是 VS Code 截图。

第二步：把命令放到正确的运行上下文

下面是一份 JSONC 配置。示例中的注释说明了运行位置和目的；命令本身只做轻量动作，便于你在第一次创建和后续重启时分别观察日志。

{
  "name": "Lifecycle Demo",
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",

  // 宿主机阶段：容器启动前准备本地共享标记文件
  "initializeCommand": "mkdir -p .devcontainer/.local && printf 'ready\\n' > .devcontainer/.local/host-ready.txt",

  // 首次创建阶段：命令在容器内执行，适合建立容器内目录
  "onCreateCommand": "mkdir -p .devcontainer/state && printf 'created\\n' > .devcontainer/state/created.txt",

  // 每次启动阶段：只做幂等检查，不重复执行昂贵安装
  "postStartCommand": "test -f .devcontainer/state/created.txt && printf 'container-started\\n' > .devcontainer/state/last-start.txt"
}

这里的关键不是三个文件名，而是上下文边界：initializeCommand 使用宿主机 shell，后两个命令使用容器内环境。数组形式适合不需要 shell 的单条命令；字符串形式可以使用重定向和 &&，但应把复杂逻辑移到项目脚本中，并让脚本具备幂等性。

配置保存后执行 Dev Containers: Rebuild Container。创建阶段的命令如果失败，后续生命周期脚本可能不会继续执行，所以安装命令要有清晰的退出码，不能把一个长期运行的前台服务直接塞进这里。

第三步：分别核对创建和重启的结果

第一次重建时，先在 VS Code 的 View 菜单打开 Output，再在右上角通道选择器中切换到 Dev Containers。创建完成后应能找到 initializeCommand 和 onCreateCommand 对应的日志；停止容器再执行 Dev Containers: Reopen in Container，关注的则是 postStartCommand。

核对结果时可以看三个信号：宿主机的 host-ready.txt 存在，容器内的 created.txt 只在首次创建时建立，以及每次重新启动后 last-start.txt 的内容被更新。下图是原创的结果验收界面说明图，用来帮助定位日志和状态文件，不表示本机已经运行过这组命令。

异常修正：重复执行或找不到文件怎么办

• 每次启动都重复安装：把安装动作放到 onCreateCommand，postStartCommand 只保留检查或启动动作。
• 宿主机找不到容器内路径：检查命令是否误放进 initializeCommand；只有挂载并且路径确实存在时，宿主机才可能读到它。
• 重建后仍看不到变化：使用 Dev Containers: Rebuild Container，不要只执行重新打开窗口；修改容器配置不会自动重建。
• 脚本偶尔失败：先在 Dev Containers 输出中确认失败阶段，再检查工作区路径、当前用户和依赖是否已准备好。

最后把实际项目里的复杂动作放到版本库脚本中，devcontainer.json 只保留阶段选择和入口参数。这样既能从配置文件看出运行边界，也方便团队在容器重建或恢复时复用同一套逻辑。

常见问题

initializeCommand 会在容器里运行吗？

不会。它用于宿主机或云端工作区的初始化上下文，适合准备容器创建前就需要的资源；容器内目录和依赖应放到容器侧生命周期命令。

onCreateCommand 为什么重启容器时不再执行？

它面向首次创建阶段。容器停止后再次启动时，应由 postStartCommand 承担每次都要运行的轻量动作。

三个属性能写成数组吗？

可以。数组会绕过 shell 直接执行命令；如果需要重定向、管道或 &&，使用字符串或把逻辑收进脚本文件，并在脚本中处理失败和重复执行。