GitHub Codespaces 预构建配置减少启动等待

如果 GitHub Codespaces 每次创建都要重新准备依赖、扩展和项目初始化，可以给仓库配置预构建。它会针对仓库、分支和 devcontainer.json 的组合提前准备开发环境，创建 Codespace 时直接复用，适合依赖较多或初始化超过两分钟的项目。

官方地址：https://docs.github.com/en/codespaces/prebuilding-your-codespaces/configuring-prebuilds

最稳妥的做法是先为一个常用分支配置预构建，再根据依赖更新频率选择 Every push 或 On configuration change，并只保留实际会使用的区域和版本。

配置前先确定三个对象

第一是目标分支，例如 main；第二是该分支实际使用的 devcontainer.json；第三是仓库已经启用 GitHub Actions。预构建由 Actions 工作流创建和更新，如果 Actions 被禁用，配置页面即使能打开，也无法得到可用的预构建结果。

还要先想清楚“最新依赖”有多重要：依赖经常随提交变化，就优先考虑每次推送更新；依赖只在开发容器配置变化时才需要更新，可以减少工作流运行次数。

从仓库设置进入预构建配置

1. 打开目标仓库主页，进入 Settings。
2. 在左侧 Code, planning, and automation 区域选择 Codespaces。
3. 找到 Prebuild configuration，点击 Set up prebuild。

进入配置表单后，先在分支下拉框选择目标分支，再选择对应的配置文件。不要只凭文件名猜测：一个仓库可能有多套容器配置，应该让它与实际创建 Codespace 时使用的配置保持一致。

选择触发方式、区域和保留版本

1. 在触发方式中选择 Every push、On configuration change 或 Scheduled。
2. 如果团队只在少数地区创建 Codespace，打开区域限制，只保留实际使用的地区。
3. 在 Template history 中设置保留版本数，按回滚需要选择 1 到 5 个版本。
4. 确认仓库有权使用 Actions 和 Codespaces 后，点击 Create。

Every push 的新鲜度最高，但每次推送都可能触发更新；On configuration change 主要关注 .devcontainer/devcontainer.json 和它引用的 Dockerfile，运行更少但普通依赖变化可能不会立即进入预构建；Scheduled 适合可以接受延迟更新的团队。区域越多、保留版本越多，存储占用也会随之增加。

创建后如何确认预构建可用

1. 回到仓库的 Settings > Codespaces，在对应配置旁查看最新运行状态。
2. 如果需要定位失败原因，点击 See output，从关联的 Actions 工作流日志查看具体步骤。
3. 创建新 Codespace 时，检查机器类型选项旁是否出现 Prebuild ready。看到它，才说明当前仓库、分支、容器配置和区域组合有可用预构建。

如果工作流已完成但创建页没有 Prebuild ready，先核对分支、配置文件和区域是否完全匹配，再查看是否刚发生过配置更新。不要把工作流“完成”直接等同于所有组合都已经可用。

两个容易忽略的边界

• 预构建按仓库、分支、配置文件和区域组合生效，换了分支或容器配置后，原来的预构建不一定适用。
• 预构建会占用存储。若仓库很大或同时保留多个版本，应先缩小区域范围和版本数量，再观察创建速度是否满足目标。

常见问题

配置创建后一直没有结果怎么办？先看关联 Actions 工作流是否排队、失败或被禁用；再确认仓库的 Codespaces 和 Actions 权限，以及 devcontainer.json 中的初始化命令是否能完成。

什么时候不适合使用预构建？如果项目很小、创建环境本身很快，或依赖每次都强制实时变化，预构建带来的存储和维护成本可能超过收益。

最后确认清单

完成后按“分支和配置文件正确、触发策略符合依赖更新节奏、区域没有过度配置、保留版本数量可控、Actions 工作流完成、创建页出现 Prebuild ready”逐项确认。这样既能减少 Codespace 启动等待，也能避免把旧依赖和额外存储成本一起带进团队流程。