Xcode Cloud 建置產物怎麼長期保存？2026 歸檔指南

症狀：歷史建置記錄還在，所需的 Archive、日誌或測試結果卻未必仍能從 Xcode Cloud 下載。
最快解法：先列出要保留的產物，在平台可用期間下載，按建置與來源提交整理，最後實際開啟檔案演練復原。

這份指南適合需要保留正式版本 Archive、符號檔或發布日誌的獨立開發者。
如果你要回看測試結果、截圖，或讓團隊成員按建置和提交找回發布材料，也可依下列情境建立歸檔規則。

Xcode Cloud 建置產物歸檔：平台存取不等於長期保存

Xcode Cloud 適合執行建置與測試工作流，但不要把它當成永久歸檔庫。Apple 說明，建置完成後，產物只能在有限期限內存取，最長為 30 天；因此，需長期留存的項目應在期限內下載到團隊可控制的位置。Apple 的 Xcode Cloud 工作流文件說明產物的可用期限與發布用產物的歸檔建議。

要分清兩種狀態：產物仍可在平台下載，只代表目前有存取入口；團隊完成外部下載、記錄來源並驗證檔案，才算建立了可復原的歸檔。工作流記錄或建置狀態可以協助你定位一次執行，但不能代替已下載的檔案。

Xcode Cloud 建置產物可以保留多久？
不要把最長期限當成每個團隊都能依賴的存放期限。以 Apple 文件所列的最長 30 天為界，將正式發布、可能需要診斷的建置列入優先下載；若需要更長期保存，應由你自己的歸檔流程承接。

正式版本診斷：Archive 與符號檔各自負責

正式版本出現崩潰時，Archive、符號資訊和建置日誌解決的是不同問題。Archive 是發布或後續處理所需的建置產物；dSYM 等符號資訊則協助將崩潰堆疊還原成可辨識的函式與程式位置；建置日誌記下建置過程中的設定與錯誤。不要只留其中一種，就假設日後一定能完成診斷。

Apple 說明，除錯資訊的產生方式與建置設定有關；發布前應確認所需符號資訊確實存在，並將它與對應建置一起保管。Apple 的除錯資訊建置說明可用來核對相關設定。

請先從建置記錄確認 App、版本、工作流、建置識別資訊和來源提交，再決定哪些檔案要留。若故障調查需要重現建置環境或判讀特定警告，日誌也可能有用；如果只需日後符號化崩潰，則優先確保 Archive 與相符的符號資訊成對保存。Apple 的建置問題排查文件可協助判讀部分建置訊息，但不會取代你自行保存的日誌。

測試結果回看：證據要連回原始建置

測試結果包、截圖與建置日誌，只有在能辨認來源時才有長期價值。若團隊需要重現測試失敗，請把結果包和相關截圖與工作流、建置記錄、來源提交及測試條件建立關聯；若只留下檔案，卻沒有記錄它來自哪次建置，日後就難以判斷結果是否適用於目前程式碼。

歸檔的測試結果要怎樣驗證能否復原？
從你實際保存的位置取回檔案，確認測試結果包能開啟、截圖可讀，並能由歸檔記錄找到對應的建置與提交。若結果包無法開啟，或來源資訊缺漏，就把它記為未通過復原驗收，而不是視為已完成歸檔。Apple 對 Xcode Cloud 結果包與問題回報的相關說明可作為理解結果資料的參考。

測試結果與建置日誌適不適合長期保存，取決於你是否會用它們重現問題、提供發布證據或交接調查；不要因為平台提供下載，就把每次執行的所有檔案都永久保存。

團隊交接：依建置與提交找回發布材料

交接時，檔案命名和索引方式比單純堆放檔案更重要。可依 App、工作流、建置識別資訊和來源提交建立資料夾或索引欄位，再把 Archive、符號資訊、日誌、測試結果與截圖記錄在相同項目下。這樣接手者不必猜測某個 .xcarchive 或 dSYM 對應哪一個版本。

App Store Connect API 可用於讀取 Xcode Cloud 的工作流、建置與產物資訊；Apple 的工作流與建置 API 說明和 Build Runs 資源文件可協助你把建置記錄連回工作流。實際歸檔時，建議在索引中保留可辨識的建置資訊與提交識別，不要只記錄下載日期。

Xcode Cloud 的 Archive 和符號檔要如何備份？
先從對應建置確認可取得的產物，再下載 Archive 與相符的符號資訊，並將它們放在同一筆歸檔記錄下。若正式版本需要日後排查，再按用途補上建置日誌；不要把不同建置的 Archive 和 dSYM 混放，否則檔案雖在，符號資訊仍可能無法用於目標版本。

部分留存：按用途取捨，而非每次全存

你可以用下表建立團隊規則，之後依專案的發布與支援需求調整；這是留存決策框架，不代表 Apple 規定的保存清單。

什麼情況不必保存全部材料？
如果一次建置沒有發布、診斷或測試重現用途，你可以依內部規則只保留必要記錄。相反地，正式發布或仍在調查的版本，應先確認 Archive、符號資訊與相關證據已經下載並通過驗收，再依團隊政策清理其他副本。沒有專案資料支撐時，不要臆測儲存容量或成本。

API 自動下載：先找產物，再保存檔案

怎樣透過 App Store Connect API 下載 Xcode Cloud 建置產物？
自動化流程可先定位工作流及建置記錄，再查詢該建置關聯的產物，讀取產物資訊後取得下載入口，最後下載並更新歸檔狀態。Apple 的產物資訊文件、單一產物讀取介面與產物屬性說明應作為核對 API 欄位和可用資訊的依據。

不要把 API 回應中的下載網址當成永久連結保存。下載網址可能有時效性；若下載工作失敗，應重新查詢產物資訊並依官方文件確認連結是否仍有效，而不是無限重試舊網址。API 認證也應獨立管理：只在自動化執行所需範圍內使用憑據，避免把令牌或下載網址寫入公開日誌。令牌建立和請求方式以 Apple 的API 令牌文件為準。

把下載狀態、檔案校驗結果、來源建置與錯誤原因分開記錄。如此即使下載中斷，你也能區分「尚未下載」「下載失敗」和「已下載但未驗證」，避免把未完成的作業誤標成已歸檔。

復原演練：用勾選清單完成驗收

留存規則只有經過取回測試，才能證明團隊真的能使用歸檔。挑選一筆正式發布或測試失敗記錄，從實際保存的位置取回檔案，再逐項檢查：

• [ ] 歸檔索引能對應到 App、工作流、建置識別資訊與來源提交。
• [ ] Archive 已下載，且能從保存位置開啟或由團隊指定工具讀取。
• [ ] 符號資訊與目標建置相符；若未保存，已記錄原因與責任人。
• [ ] 需要診斷或重現時，相關建置日誌、測試結果包與截圖可讀取。
• [ ] API 下載失敗、檔案不完整或產物缺漏時，狀態與後續負責人有明確記錄。
• [ ] 由另一位團隊成員依索引找回材料，並記下未能復原的項目。

最後，檢查歸檔位置的存取權限和備份政策是否符合你們的資料管理要求。若演練發現某類檔案無法開啟，先補齊流程或重新取得材料，不要只把問題留在備註裡。

目前流程與 Mac 環境：按實際工作量選擇

若你目前只在 Xcode Cloud 上短期取用產物，風險是平台期限過後缺少檔案；若由開發者各自下載到本機，則容易出現命名不一致、來源記錄分散或負責人離開後難以交接。這些問題應先靠歸檔索引、存取權限與復原演練處理，而不是單靠增加一台電腦就能解決。

如果團隊確實需要一個持續可用的 Mac 環境來整理或核對下載材料，可以把遠端 Mac 納入工作流程評估；它不會自動替你保存 Xcode Cloud 產物，也不能取代外部歸檔與驗收。若你正在比較自購與租用，可先參考Mac mini 價格指南，再按使用期間與維護責任衡量。對需要短期整理、測試復原流程或避免專為此用途購置硬體的團隊，租用 MacDate 的 Mac 環境可作為另一種選擇；請先核對MacDate 的方案與價格資訊，再以一次產物下載和復原檢查確認是否符合你的流程。