建置失敗後才發現舊日誌或測試結果已無法取得，會讓追查卡在第一步。
最快解法：Xcode Cloud 建置完成後，立即下載需要留存的產物；可在 Xcode 或 App Store Connect 手動保存，也可用 App Store Connect API 自動化。下載後核驗檔案，再存入受權限控管的歸檔位置；不要把 API 回傳的臨時下載網址當成永久連結。
適合需要重現歷史失敗、保留測試證據的小型團隊。
如果您負責 CI 或發佈流程，這份 runbook 可協助建立可核驗的產物留存與存取流程。
先辨識建置完成後要保存的內容
Xcode Cloud 會提供建置相關資訊與產物。團隊不一定要把每個檔案永久保存，應先按用途選範圍：發佈追溯需要能對應版本的封存檔；崩潰診斷需要符號資訊；測試復現則可能需要測試結果與相關日誌。
Apple 說明，Xcode Cloud 的建置資訊和產物最多可存取 30 天。這是雲端可存取期限，不是團隊的保存期限；若有超過這段時間仍需查閱的要求，就應在期限內建立自己的副本。Apple 的 Xcode Cloud 工作流程與封存說明
| 留存目的 | 優先確認的產物 | 需要避免的缺口 |
|---|---|---|
| 重現建置問題 | 建置日誌、建置識別資訊、對應提交 | 只存錯誤截圖，沒有上下文 |
| 追蹤發佈版本 | 應用封存檔或二進位檔、版本資訊 | 檔案未連結至提交或建置 |
| 分析崩潰 | 符號資訊及對應版本 | 符號檔與應用版本錯配 |
| 留存測試證據 | 測試結果及相關報告 | 只保留「成功／失敗」摘要 |
不要因為能下載就把所有檔案永久堆進同一個目錄。先確認檔案是否含有程式碼、內部路徑或其他敏感資訊，再決定誰能讀取、保存多久，以及何時清除。
在人工查看時先完成一次手動封存
低頻建置或需要人工檢視內容時，先使用 Xcode 或 App Store Connect 查看建置報告。確認目標建置、相關動作及可下載的產物，再下載所需檔案。Apple 的說明列出透過 Xcode、App Store Connect 或 API 取得及封存產物的方式；可先以官方 Xcode Cloud 操作說明核對目前介面與流程。
手動方式常見的風險不是下載按鈕，而是責任沒有落地：沒人負責保存、檔案散在個人電腦，或檔名無法辨認來源。第一次操作時，就把保存位置、命名方式和負責角色一併定好。遇到需要日後查驗的建置，不要只依賴瀏覽器下載目錄。
用 API 把產物資訊接進團隊流程
自動化不是直接猜測檔案網址，而是先按 Apple 文件所列的資源關係查詢資料：定位工作流程與建置，再找到建置動作的產物。App Store Connect API 提供工作流程與建置資源說明，也提供列出建置動作產物的端點文件。取得產物資料後，依產物屬性文件辨認名稱、類型及下載所需資訊；需要讀取單一產物時，參照產物資源端點文件。
| 作法 | 適合情境 | 主要風險 | 建議控制 |
|---|---|---|---|
| Xcode 或 App Store Connect 手動下載 | 低頻處理、需要人工挑選 | 忘記下載、保存位置不一致 | 指定負責人和固定歸檔路徑 |
| API 自動取得並下載 | 希望讓建置後流程可重複執行 | 認證外洩、下載中斷、檔案未核驗 | 隔離憑據、記錄建置識別資訊、驗證副本 |
| 只留雲端連結 | 暫時查看或交接 | 網址時效有限，日後可能無法取用 | 不作為長期封存方式 |
API 請求需符合 Apple 的認證要求。建立金鑰時，依Apple 的 App Store Connect API 金鑰文件設定適當權限；產生請求權杖時，依JWT 認證文件處理。私密金鑰與權杖應放在受控的秘密管理位置，不要寫入原始碼、建置日誌或提交紀錄。
提醒：產物資料中的下載網址只在有限時間內有效。取得網址後應立即下載，並以團隊實際保存的檔案作為後續查驗來源，不要把網址留在文件中當作封存副本。
建置完成後執行下載與歸檔
把自動化拆成能逐項查核的階段。這樣遇到 API 查詢成功、但檔案沒有落地的情況時，可以找出失敗環節，而不是只看到整條工作流程報錯。
- [ ] 觸發流程：選定團隊現有的建置完成後處理方式。不要假設 Apple 對第三方歸檔流程提供特定觸發保證；需確認觸發事件或排程在團隊環境中的實際行為。
- [ ] 定位建置：從 API 回應中確認目標工作流程與建置，不要只依靠容易重複的顯示名稱。
- [ ] 取得產物資料：依官方端點查詢建置動作與產物資源，記錄回傳的識別資訊、檔名和類型。
- [ ] 立即下載：取用回傳的下載資訊並完成檔案傳輸。若下載失敗，應重新查詢產物資訊，而不是不斷重試已逾時的舊網址。
- [ ] 核驗副本：檢查檔案是否存在、能否開啟，以及檔案類型是否符合預期。若團隊使用雜湊或儲存平台版本紀錄，也可一併保留核驗結果。
- [ ] 留下關聯資訊：將檔案對應至建置識別資訊、提交版本和工作流程，並記錄執行結果。
- [ ] 限制存取：只授權需要讀取的人員與自動化角色，避免在錯誤訊息或除錯輸出中暴露 JWT 和金鑰內容。
任何一步失敗，都要留下足以重跑或調查的狀態，例如「查無產物」、「下載未完成」或「檔案核驗失敗」。避免將失敗流程記成成功，否則看似完整的歸檔目錄會掩蓋實際缺檔。
核驗留存、權限與清理責任
Xcode 建置產物能不能在數月後派上用場，取決於檔案和上下文是否一起保存。僅保留封存檔，可能無法解釋它對應哪次建置；僅保留測試摘要，也可能不足以重現故障。至少要讓團隊能從目錄或索引追到建置、提交、工作流程與產物類型。
保存期限則應由團隊按發佈追溯、故障處理及合規需求決定。不要把 Apple 雲端可存取期限當成自動歸檔規則，也不要假設雲端仍可取用就等於團隊已完成長期保存。若團隊需要以 macOS 工具檢查封存檔或進行後處理，可先閱讀遠端 Mac CI 工作流程與驗收資訊，再確認現有流程是否需要獨立的 Mac 環境。若需要評估租用 Mac 的成本與方案，也可查看方案與價格資訊。
每次調整 API 流程、權限或檔案保存位置後，都應用真實工作流程驗收：讓新的建置走完查詢、下載、核驗與讀取流程，再確認授權人員能從團隊保存位置取回檔案。這能揭露只在測試環境成立的路徑、權限或檔案格式問題。
常見問題
Xcode Cloud 的雲端產物會一直保留嗎？
不會。Apple 文件指出建置資訊與產物最多可存取 30 天。需要保留更久時，應及時下載至團隊管理的儲存位置；雲端可存取時間與團隊自訂的歸檔期限是兩件事，不能互相替代。
用 App Store Connect API 自動下載時，應先做什麼？
先依 Apple 認證文件建立並管理 API 金鑰，再產生 API 請求所需的 JWT。接著依工作流程、建置、建置動作與產物資源逐步查詢。欄位和端點可能隨文件更新，實作時應核對官方 API 參考，而非依賴未驗證的範例。
測試結果和建置日誌要如何納入歸檔？
先在建置報告中確認可取得的內容，再按測試復現或故障排查需要挑選要保存的項目。下載後將結果連結至建置與提交資訊，並實際打開檔案確認可讀。若只保存摘要，需先確認摘要足以支援團隊日後的調查。
API 提供的下載網址適合作為團隊歸檔連結嗎？
不適合。Apple 文件指出產物下載地址只有有限時間有效，不能當永久連結。應在取得後儘快下載並核驗，再透過團隊管理的儲存位置或索引提供取用；日後需要重新下載時，應重新查詢產物資訊。
若目前的做法是只靠 Xcode Cloud 雲端頁面、由個人手動下載，或把短期網址貼進文件，常見問題是期限過後無法取回、責任人不明，以及沒有 macOS 環境執行後續檢查。Xcode Cloud 仍可負責建置；若工作流程還需要在 macOS 上驗證封存檔或執行後處理，租用 metalvnc 的遠端 Mac 可作為補充環境，不必為間歇性工作先購買實機。若團隊要長期執行固定且繁重的工作，或必須接觸實體介面，則應先評估自有 Mac 是否更合適。
常見問題
Xcode Cloud 的建置產物可以在雲端查看多久？
Apple 文件說明，Xcode Cloud 建置資訊與產物最多可供存取 30 天。這是雲端可存取期限，不代表團隊的保存策略；需要日後追查的檔案應在期限內另行下載，並依團隊要求設定自己的保存位置與清理規則。
如何透過 App Store Connect API 下載 Xcode Cloud 產物？
先依 Apple 的要求建立 API 金鑰並為請求產生 JWT，再查詢工作流程、建置及建置動作的產物資源。讀取產物屬性取得下載所需資訊後，立即下載檔案；端點、欄位和認證細節應以 Apple 當下的 API 文件為準。
Xcode Cloud 的測試結果和建置日誌要怎樣保存？
先從建置報告確認哪些日誌、測試結果或封存檔能解答團隊的追查需求，再透過 Xcode、App Store Connect 或 API 取得相應產物。保存時以建置識別資訊和提交版本建立關聯，並實際開啟檔案確認內容，而不是只記錄下載成功。
App Store Connect API 回傳的產物下載網址可以長期使用嗎？
不可以把它當作永久連結。Apple 的 API 文件指出，產物下載網址只在有限時間內有效。流程應在取得網址後立刻下載檔案，並確認本地或團隊儲存位置已有可讀副本；日後取用應使用團隊管理的歸檔路徑，而非舊網址。