构建会在后台准备云端代理环境。每个智能体都会从预构建的机器启动，其中已备好仓库、工具和依赖项。
使用构建，你可以获得：
- 启动更快：克隆、安装和处理依赖项会提前完成，因此智能体可直接从就绪环境启动，无需每次启动时等待。
- 启动可靠：智能体始终从最新的成功构建启动。安装失败或配置错误不会替换可用构建。
- 环境可观测：你可以查看每个构建，检查其日志和提交，并追踪每个智能体使用的是哪个构建。
Build 的工作方式¶
Build 是已准备就绪的云端代理环境的可启动快照。Cursor 会在智能体运行前预先创建 Build，并让最新成功的 Build 保持就绪状态。
每个 Build 都经历以下生命周期：
- 触发：Build 可按计划启动、在您保存环境版本后启动、通过手动请求启动，或由智能体请求启动。请参阅Build 的发生时机。
- 准备：Cursor 基于您的基础镜像，在环境中每个代码仓库的默认分支创建克隆，并运行
install命令直至完成。 - 快照：Cursor 会保存机器的磁盘状态，以及环境版本和每个代码仓库的确切提交 SHA。
- 激活：成功的 Build 将成为活动 Build。
- 启动智能体：新的智能体、自动化和代码评审均从活动 Build 启动。
Cursor 会让活动 Build 的预热副本保持就绪。这省去了智能体启动时的代码仓库克隆和依赖安装。
如果新的 Build 失败，智能体将继续使用上一个成功的 Build。出错的依赖更新、安装命令或 Dockerfile 不会替换活动环境。
Build 何时运行¶
Cursor 会在四种情况下启动 Build。Builds 选项卡会标明每种 Build 的触发类型。
| 触发条件 | 运行时机 |
|---|---|
| 定期 | 对每个环境按固定计划运行 |
| 配置变更 | 保存环境配置或更改其机密信息时 |
| 手动 | 在 Builds 选项卡中选择 触发 Build 时 |
| 智能体请求 | 智能体运行测试 Build 时，例如在设置环境期间 |
定期 Build¶
Cursor 定期检查每个环境，并在发生变化时重新构建。这样可让活动 Build 始终接近各代码仓库默认分支的 head，使智能体以最新代码和预热的依赖缓存启动，无需在启动时拉取代码和重新安装依赖。
已跳过的 Build¶
如果自上次完成的 Build 以来没有任何更改，定期检查会跳过此次 Build：环境中所有代码仓库的默认分支均无新提交，配置和机密信息也没有更改。Builds 选项卡会将这些检查记录为 已跳过 状态。它们会在几秒内完成，不运行任何安装命令，并保留当前活动的 Build。
对于健康的环境，定期条目持续混合显示“已跳过”和“成功”状态是正常现象。变动较少的代码仓库大多会产生“已跳过”条目。活跃的代码仓库则会更频繁地重新构建。
Cursor 仅会跳过定期 Build。手动触发、由智能体请求以及因配置更改触发的 Build 始终会运行。
Build 和智能体启动时运行的内容¶
每个环境命令对应不同阶段：
| 命令 | 运行时机 | 用途 |
|---|---|---|
install |
每次 Build 期间 | 安装依赖、生成代码、编译产物和预热磁盘缓存 |
start |
每次智能体运行开始时 | 启动 Docker、数据库、隧道和其他服务 |
terminals |
每次智能体运行开始时 | 在与智能体共享的 tmux 终端中启动应用进程 |
确保 install 命令完整且幂等。它可以重复运行，也可能在已准备好的磁盘状态基础上运行。npm install、pnpm install 和 pip install 等命令本身就支持这种模式。
Build 仅保留磁盘状态。Cursor 对机器创建快照时，正在运行的进程、shell 导出的变量和
内存缓存都会停止。请将服务和其他特定于会话的工作放在 start 或 terminals 中。
你现有的环境输入仍然适用。Build 会使用已保存的快照、.cursor/environment.json、Dockerfile、安装命令和启动命令、机密信息以及网络设置。
Build 如何处理 Git 状态¶
Build 会记录运行时各代码仓库检出的提交。
- 默认分支运行从活动 Build 中记录的提交开始。定时 Build 会在后台刷新该提交。启用更新过期 Build后，如果 Build 超过您的过期阈值，智能体会在启动时拉取最新的默认分支代码。关闭该设置后，智能体会按原样使用 Build 记录的提交。默认阈值为 24 小时。将其设为
0可始终拉取。 - 功能分支运行从活动 Build 准备好的磁盘状态开始，然后 Cursor 会检出所请求的分支。源代码与您选择的分支一致，同时复用 Build 中的依赖项。
- 多仓库环境会为每个代码仓库记录一个提交，并同时准备完整工作区。
如果功能分支更改了依赖项，智能体会获得您的环境上下文和安装命令，以便在测试前刷新环境。
机密信息在 Builds 中的使用方式¶
Builds 可以访问团队和环境机密信息。可将其用于私有包注册表、artifact 存储及 install 所需的其他凭据。
用户机密信息仅会在智能体启动时添加。在 Builds 期间无法使用，也不会包含在共享 快照 中。
保存环境配置或更改其机密信息会触发新的 Build。
管理 Build¶
打开环境的 Builds 选项卡，以便：
- 查看每个 Build 的类型、状态和开始时间
- 打开 Build 查看其详细信息和日志
- 选择 触发 Build 以按需运行 Build
- 激活草稿 Build 或停用 Build
- 取消正在进行的 Build
- 从特定 Build 启动智能体
- 配置 更新过期 Build 和 过期阈值
每次智能体运行都会记录其所基于的 Build。利用此溯源信息，可将环境行为与该 Build 中的确切配置和代码仓库提交进行比较。
调试 Build¶
打开失败的 Build，查看其事件和日志。诊断失败原因时，智能体仍会从当前有效的成功 Build 启动。
如需精确复现，可从失败的 Build 启动智能体。智能体会打开处于失败状态的机器，以便检查日志、更新环境、运行测试 Build 并验证结果。
您还可以让 云端代理 通过内置的 Cursor Cloud MCP 检查和管理 Builds。例如：
检查此环境最新失败的 Build。修复环境
配置，运行测试 Build 并验证结果，然后再给出最终的
安装和启动命令。
Build 行为参考¶
智能体使用哪个 Build？¶
默认情况下，智能体会使用其所在环境中最新成功的活动 Build。
您也可以在测试或调试时，从特定 Build 启动智能体。
首次 Build 成功前会发生什么？¶
在首次 Build 成功完成前，智能体会采用标准的环境启动流程。Build 失败不会中断现有的智能体工作流。
源代码的新鲜度如何？¶
功能分支运行会在 Build 启动后检出所请求的分支。默认分支运行则从活动 Build 中记录的提交开始。如果开启了 更新过期 Build，且 Build 的时间早于 过期阈值，智能体会在启动时拉取最新的默认分支代码。
Build 会取代快照或 Dockerfile 吗？¶
不会。已保存的快照或 Dockerfile 定义了用于创建 Build 的基础机器。随后，Cursor 会克隆仓库、运行 install，并创建一个新的可启动快照。
Build 支持多个仓库吗？¶
支持。一个 Build 会准备环境中的所有仓库，并记录各仓库使用的 提交。
Builds 是否额外收费？¶
不收费。Cloud Agents 已包含 Builds。
