構建會在後臺準備雲端代理環境。每個智能體都會從預構建的機器啓動，其中已備好倉庫、工具和依賴項。
使用構建，你可以獲得：
- 啓動更快：克隆、安裝和處理依賴項會提前完成，因此智能體可直接從就緒環境啓動，無需每次啓動時等待。
- 啓動可靠：智能體始終從最新的成功構建啓動。安裝失敗或配置錯誤不會替換可用構建。
- 環境可觀測：你可以查看每個構建，檢查其日誌和提交，並追蹤每個智能體使用的是哪個構建。
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。
