Xcode Cloud 構建產物只保留 30 天？2026 備份教學

Xcode Cloud 構建產物備份應在構建完成後立即開始，不要等到需要排查崩潰時才下載。按 Apple 截至 2026 年 8 月 30 日 的官方說明，構建資訊與產物最多可存取 30 天；偶爾發佈可在當天手動下載，持續發佈的專案則應使用 App Store Connect API 自動歸檔，並在獨立儲存或常駐遠端 Mac 上完成恢復驗證。Apple 的 Xcode Cloud 工作流程文件確認了這項保留邊界。

這篇適合依賴 Xcode Cloud 發佈 App、卻從未獨立保存構建產物的獨立開發者。
如果你需要回溯歷史版本的崩潰報告、長期保留符號資訊，或希望由小型團隊集中管理 xcarchive 和 xcresult，可以按以下時間線建立流程。

Xcode Cloud 構建產物備份：先畫出 30 天時間線

「最多保留 30 天」代表你在這段期間內可能仍可存取官方產物，不代表它適合充當永久倉庫。你需要先按照日後是否會重新簽名檢查、符號化崩潰、重現測試結果或接受稽核，決定哪些檔案值得長期保存。

Apple 文件將 Xcode Cloud 的構建、工作流程與產物分開處理。App Store Connect 中的構建記錄、Xcode Cloud 工作流程產物，以及你自行上傳的附加檔案，不應混成一個沒有索引的壓縮檔。App Store Connect API 的構建與產物文件可用來核對構建執行資訊與對應關係。

產物或記錄	發佈當天的處理	長期保留的原因
App Archive／`xcarchive`	下載並記錄 App、版本與 Build Number	重新檢查發佈內容、定位符號檔與簽名關聯
符號資訊	與對應構建放在同一歸檔目錄	用於日後將崩潰堆疊轉換成可讀函式名稱
`xcresult`／測試結果	保存能代表發佈品質的測試結果包	查閱測試紀錄、失敗案例與測試環境證據
構建日誌	只保留能解釋成功或失敗的必要日誌	協助追查腳本、依賴或簽名步驟的異常
一般分支構建	依團隊價值決定是否短期保留	不應讓低價值的日常構建佔滿長期儲存

長期歸檔不應包含憑證私鑰或未加密的 API Key。產物目錄應保存可追蹤的識別資料，例如 App 識別、版本、Build Number、工作流程名稱、構建識別碼與下載時間；敏感憑證則由獨立的秘密管理機制處理。

構建完成當天：手動下載與建立基線

低頻發佈的專案不必一開始就維護複雜自動化。先用一次官方下載建立「基線」，後續 API 腳本才能知道應該產生哪些檔案、如何命名，以及恢復時要檢查什麼。

第一步：定位正確的構建

在 Xcode 或 App Store Connect 中找到成功完成的工作流程，再核對 App、版本、Build Number、分支與工作流程名稱。不要只依照檔案名稱判斷版本，因為一個工作流程可能產生多個構建或多類產物。

第二步：下載官方產物

依照介面提供的下載選項保存 xcarchive、符號資訊、xcresult 或相關日誌。Apple 官方說明支援透過 Xcode、App Store Connect 或 App Store Connect API 下載可用產物；可參考Artifacts API 的資源說明核對產物資源。

第三步：建立可追蹤目錄

可使用下列目錄邏輯，實際值請換成已脫敏的專案資料：

archive/
  AppIdentifier/
    Version/
      BuildNumber/
        Workflow/
          BuildID/
            archive.xcarchive
            symbols/
            tests.xcresult
            manifest.json
            checksums.txt
            build.log

manifest.json 不需要保存秘密內容，只記錄產物名稱、類型、來源、構建識別碼與相對路徑。若檔案來自自行上傳的腳本，也要標明「外部附加檔案」，避免日後誤以為它是 Xcode Cloud 原生產物。

第四步：記下校驗結果

下載完成後，先確認壓縮檔能解開、目錄不是空的，並將校驗值寫入 checksums.txt。這一步不是為了證明檔案一定可恢復，而是讓你能辨認儲存過程中的檔案變更或不完整下載。

第五步：保存索引而不是只保存壓縮檔

把 App、版本、Build Number、工作流程、構建 ID、歸檔位置與狀態寫入團隊可查閱的索引。日後收到崩潰報告時，你應能先由版本和 Build Number 找到構建，再由構建找到符號檔，而不是逐一打開多個無法辨認的壓縮檔。

第一週：App Store Connect API 能否自動備份構建產物？

可以，但 API 不是「自動永久保存」按鈕。你仍要自行處理篩選條件、下載、儲存位置、重試、狀態記錄與恢復驗收。App Store Connect API 可用來查找構建執行，再沿著 Actions 與 Artifacts 資源取得可下載產物；取得構建動作產物的官方端點文件可作為實作時的欄位對照。

自動化流程可按以下順序設計：

讀取指定 App 與工作流程的構建執行資料。
篩選成功完成、符合發佈條件的 Archive 或發佈工作流程。
取得該構建動作的 Artifacts 資訊，不把普通分支構建全部下載。
下載每個產物，保存檔案名稱、類型、構建 ID、工作流程與執行時間。
計算校驗值，將成功或失敗狀態寫入索引。
對暫時性下載錯誤執行重試，最後仍失敗便發出告警。

憑據要分開管理。App Store Connect API Key 是 API 存取憑據；程式碼簽名資產包括憑證、私鑰與 Provisioning Profile；SSH 或 VNC 則是遠端 Mac 的登入權限。三者用途不同，不應把它們放在同一個環境變數檔或歸檔目錄。建立 API 流程前，先閱讀App Store Connect API 的整體鑑權與資源文件，並只授予自動化工作所需權限。

以下是部署前的可勾選驗收清單：

[ ] 已用測試 App 或脫敏構建確認 API 能找到正確工作流程。
[ ] 已區分成功 Archive、失敗構建與普通分支構建。
[ ] 已確認下載檔案與 App、版本、Build Number、構建 ID 對應。
[ ] 已將 API Key 與簽名私鑰分開保存，沒有寫入日誌。
[ ] 已為重複執行設定幂等鍵，例如構建 ID 加產物類型。
[ ] 已記錄下載失敗、重試次數與最後一次錯誤。
[ ] 已在獨立儲存位置完成至少一次解壓與讀取測試。
[ ] 已設定構建完成後的補償掃描，避免事件遺失。

事件觸發與定時輪詢：哪種方式較適合你的發佈節奏？

Xcode Cloud webhook 可以在構建事件發生時通知外部任務，但 webhook 本身不是制品儲存服務。你需要讓接收端根據構建 ID、工作流程和結果狀態啟動下載，再將產物寫入自己的儲存位置。Apple 的 Xcode Cloud webhook 文件可用來核對事件設定與通知行為。

觸發方式	適合情況	必須補上的控制
定時輪詢	發佈頻率低、團隊可接受延後歸檔	設定時間範圍、避免重複下載、保留失敗清單
構建完成事件	發佈頻率高、希望盡快離開 30 天窗口	驗證事件內容、處理重送、加入補償掃描
事件加輪詢	產物價值高、不能接受漏檔	以構建 ID 做幂等，定期檢查未完成項目

低頻發版可先採用定時任務，降低維護成本；高頻發版則適合由 webhook 觸發，再保留定時補償掃描。不要把「收到 webhook」視為備份成功，只有下載、校驗、索引和恢復檢查全部完成，才算一個完整歸檔。

發版驗收：下載成功不等於 `xcarchive` 可恢復

Xcode Cloud 構建刪除後，不能把恢復能力當作理所當然。若產物仍在官方可存取窗口內，可以嘗試重新定位和下載；一旦超過官方保留邊界，能否恢復取決於你是否早已把副本保存到自己的儲存位置。不要把第三方個案或論壇猜測當成 Apple 的恢復承諾。

發佈版本完成歸檔後，應執行一次脫敏恢復演練：

從獨立儲存取出指定版本的歸檔包。
解壓並檢查 xcarchive 目錄結構是否完整。
讀取其中的版本資訊，核對 App Store Connect 的構建資料。
找到符號資訊，確認它與相同 Build Number 對應。
開啟 xcresult，檢查測試摘要、失敗項目與測試環境資訊是否可讀。
以一份脫敏崩潰報告進行符號化分析，確認符號檔確實可用。
將恢復結果、檔案校驗值與發現的缺項寫回索引。

Apple 的崩潰報告與裝置日誌診斷文件說明了診斷所需的分析方向；而測試結果解讀文件則可協助你確認 xcresult 是否包含可用的測試資訊。這也是為什麼只保留 App 二進位檔通常不夠：沒有對應符號和測試證據，日後排查能力會明顯下降。

長期運行：讓儲存、遠端 Mac 與清理規則各自負責

內部測試、候選發佈和正式發佈不必採用同一套保留策略。你可以按版本風險、崩潰排查需求、稽核要求與儲存成本訂定規則，但不要在沒有團隊政策或法規依據時，硬套一個統一保存年限。

職責可以這樣劃分：

本地硬碟：適合短期下載、人工檢查和快速取用，不應是唯一副本。
通用物件儲存：適合保存歸檔包、校驗資訊與索引，並由權限和生命周期規則管理。
常駐遠端 Mac：適合需要定期打開 Xcode 產物、執行符號化、處理恢復腳本或作為固定下載節點的團隊。

如果你目前使用的 Windows 或 Linux 工作站只能透過零散方式保存檔案，常見缺點是沒有原生 Xcode 讀取環境、簽名與 API 權限容易混在一起，以及下載任務無法在離線時持續執行。把歸檔資料單純放在個人電腦，也會讓磁碟故障、帳戶離職或檔案路徑變更成為恢復風險。

當你需要定期用 Xcode 開啟歷史產物、執行符號化或持續運行下載腳本時，租用 VMSPIN 的常駐遠端 Mac 會比臨時找一台可用電腦更容易維持固定環境。你可以先參考遠端 Mac 上的 iOS 自動化測試與打包方向；若只是在發版週期使用，也應先按實際頻率比較短期租用與自購 Mac 的總成本，再查看VMSPIN 的遠端 Mac 方案與週期選項。

每月安排一次抽查，並在每次正式發佈後完成一次歸檔核驗。抽查不只確認檔案仍存在，還要隨機取出一個版本，核對索引、解壓 xcarchive、讀取 xcresult，以及確認符號資訊可以支援崩潰分析。若恢復失敗，應立即標記該版本，而不是等下一次線上事故才發現備份只是看似成功。

Xcode Cloud 適合執行構建與測試，但不應被當作長期制品倉庫。你可以從今天的下一個發佈構建開始建立手動基線；當專案進入持續發版階段，再以 App Store Connect API 加上事件或輪詢、獨立儲存和遠端 Mac 恢復演練，讓每個可追溯的版本真正離開 30 天窗口前完成備份。