App Store Connect API 4.5.1 截圖介面怎麼遷移？2026

API 4.5.1 發佈說明將 4 類舊資源列為棄用：App Screenshot Sets、App Screenshots、App Preview Sets 和 App Previews。遷移目標是以 App Asset Library 的圖片、影片及 placement 管理素材，不是只替換 API 路徑名稱。Apple 發佈說明列明資源棄用狀態；素材庫 API 概覽說明新的資源模型。

先在程式碼、CI 設定及發佈腳本中搜尋舊資源呼叫，並記錄每個資源的使用目的。盤點範圍至少包括：

• 哪些工作建立或更新 App Screenshot Sets、App Screenshots、App Preview Sets 或 App Previews。
• 每個資源對應的應用程式版本、地區語言、素材類型與展示順序。
• 哪些呼叫只上傳素材，哪些還負責建立頁面關聯或推進發佈流程。
• 發生失敗時，腳本會重試、覆寫、刪除，還是留下待人工處理的資源。

將這份盤點作為遷移前基線。若團隊只記錄「上傳成功」，卻沒有舊資源 ID、目標頁面和素材排序，切換後很難分辨問題來自產圖、API 呼叫還是頁面關聯。

App Asset Library 的設計重點，是把圖片或影片素材與其展示位置分開管理。遷移前，先整理素材要出現在哪個頁面、版本或實驗位置；再按官方商店頁面素材 placement 說明建立對應關係。

不要把舊截圖集合直接視為新 placement。舊集合可能同時承載語言、版本和排序等資訊，而新流程需要明確處理素材資源與展示位置的關聯。將這些維度逐項對照：

• 頁面用途：App Store 版本本地化頁面、Custom Product Page 或實驗頁面。
• 語言：素材所屬語言是否與目標頁面一致。
• 媒體：圖片或影片的類型是否符合目標位置。
• 順序：新 placement 顯示的排列是否與核准的發佈素材一致。
• 重用關係：相同素材是否仍被其他頁面引用，避免替換或刪除時造成連帶影響。

若同一張圖片會出現在多個頁面，先確認每個目標位置都已建立並驗收，再處理舊資源。遷移文件可作為新舊資源映射依據：Apple 的 App Asset Library 遷移指引。

應用程式內活動也要做資源關係盤點。不要把活動截圖或影片當成一般版本截圖處理：記錄活動本地化、媒體類型和目標位置，並確認素材是否被多個頁面共用。Apple 的 4.5.1 說明亦列出部分應用程式內活動媒體資源的棄用狀態；實際替代關係須依發佈說明及素材庫文件核對，不應自行假設所有活動資源都能一對一轉換。API 4.5.1 發佈說明

遇到 iPhone Duo 等新展示類別，也不要把某次查詢得到的尺寸或限制長期寫死在程式碼。API 提供查詢有效素材規格的參考資料；應在建立素材前讀取當前返回的展示類型、尺寸及限制，並按官方素材規格參考資料更新驗證。

建議把規格讀取和素材驗證設為獨立步驟。規格查詢失敗時，不要悄悄套用陳舊常數繼續上傳；應讓工作停止並留下可診斷紀錄。

哪些舊截圖與預覽資源要列入盤點？

Apple 的 4.5.1 發佈說明將 App Screenshot Sets、App Screenshots、App Preview Sets 與 App Previews 列為棄用資源。請先找出程式實際呼叫及資源關聯，再映射到素材庫圖片、影片和 placement。棄用標記代表應規劃遷移，不代表已立即停止服務。

舊的截圖集合怎樣對應到素材庫？

不要直接把舊集合改名成 placement。先按應用程式版本、地區語言、媒體類型、展示順序和目標頁面整理關聯，再建立素材庫資源與 placement。於隔離應用驗證上傳、處理狀態和頁面結果後，才將正式流水線逐步切換。

活動截圖和影片要額外確認甚麼？

先核對活動本地化、媒體類型及目標位置，再確認素材庫資源與 placement 的關係。若替換或刪除素材，須先檢查其他頁面是否仍有引用。活動素材上傳成功，不代表它已在預期頁面展示；需以實際頁面核驗作為放行依據。

API 回應成功，代表頁面已經顯示新素材嗎？

不代表。成功回應只證明當前 API 步驟有結果，不能代替素材處理完成、placement 關聯正確或頁面展示正常的證據。保留資源 ID、處理狀態及頁面核驗紀錄，並分開檢查這幾項結果。

截圖在 Mac CI 產生，是否要重做整個節點？

不一定。先確認節點是否負責 macOS 截圖產生或相關工具執行；若節點只負責呼叫 API，通常可先獨立調整上傳與 placement 流程。保留產圖工作，用隔離流水線驗證新素材管理鏈路，不要只因 API 遷移就重建構建環境。

Mac CI 截圖上傳應拆成可獨立驗收的工作。Apple 的素材上傳流程文件說明上傳流程；你仍須在實際測試應用中確認處理結果和頁面展示，不能把 API 成功回應直接當成發佈完成。

照以下步驟建立隔離驗收鏈路：

• [ ] 確認產圖位置。記錄截圖由哪個工作產生、產物存放位置及呼叫 API 的工作。若素材不是在 macOS 上產生，也沒有 macOS 專用工具依賴，不要因這次 API 遷移就更換 CI 節點。
• [ ] 準備測試素材與目標頁面。選定測試應用、版本本地化或活動頁面，明確記錄語言、素材類型、預期順序和 placement。
• [ ] 取得當前規格。查詢有效展示類型、尺寸及限制，再驗證輸入素材；不要把某次返回值當作永久不變的規格。
• [ ] 執行素材預留與上傳。依官方流程處理素材預留、檔案上傳及提交，記錄每次 API 呼叫結果與資源 ID。重試前先判斷原請求是否已建立資源，避免重複建立或覆寫。
• [ ] 等待並核對處理狀態。將上傳成功與素材處理完成分開記錄。處理尚未完成或回報失敗時，不要建立「已可展示」的放行結論。
• [ ] 建立 placement 並查看頁面。核對實際頁面的語言、素材類型和順序；以畫面或可追溯的人工核驗紀錄確認結果。
• [ ] 驗證失敗回復。在隔離環境測試上傳失敗、處理失敗及 placement 建立失敗時的重試與清理方式，並確認共用素材不會被誤刪。

新舊流程並行時，將舊資源與新素材逐項比對：資源用途是否一致、placement 是否指向預期頁面、展示順序是否相同、失敗時是否能回到已知可用路徑。舊資源棄用不等於已立即停服，因此不應以未經確認的停用日期作為切換倒數依據。

按條件決定切換方式：

• 若隔離流水線已證明素材處理完成、placement 關聯正確，而且頁面展示與核准素材相符，則先切換一條非生產發佈路徑，再擴大覆蓋範圍。
• 若 API 回應成功但處理狀態未確認，則暫停放行，保留原路徑並補足狀態檢查。
• 若處理完成但頁面缺圖、語言錯誤或順序不符，則先回查 placement 和頁面關聯，不要只重傳素材。
• 若刪除或替換可能影響其他頁面共用的資源，則先停止清理操作，查清引用關係後再處理。
• 若隔離測試仍無法重現預期展示，則暫緩正式切換，保留舊流程與問題紀錄，避免同時變更多個環節。

每次驗收保留呼叫日誌、資源 ID、處理狀態、placement 資訊及頁面核驗紀錄。這些資料可讓值班人員區分 API、素材處理和頁面展示問題，也能為回退決策提供證據。

若你的截圖工作確實需要 macOS，而現有實體節點又帶來採購等待、閒置容量或維護負擔，可把遠端 Mac 租賃納入替代方案比較；若素材由其他環境產生，則先完成 API 遷移，不必為此單獨更換構建節點。你可先查看 CALMVPS 方案與價格，確認按需使用是否符合團隊的工作週期；需要臨時 Mac 驗證環境時，再了解 CALMVPS 遠端 Mac 方案。