App Store Connect 上傳失敗：2026 排查指南
Archive 已經成功，但 App Store Connect 找不到構建，或 Transporter 在上傳途中中斷。
最快解法：不要立即重做憑證，也不要連續增加構建號。先確認錯誤發生在歸檔驗證、帳戶授權、程式碼簽名、檔案傳輸，還是 Apple 端處理。
這篇適合首次上傳構建、尚未熟悉錯誤日誌位置的獨立開發者；也適合使用遠端 Mac 或自動化任務，遇到本機成功、遠端失敗的開發者。若小團隊正準備 TestFlight 測試或版本發布，可直接依照下方順序縮小範圍。
App Store Connect 上傳失敗，先按故障階段分流
「上傳失敗」不是單一問題。Archive、Validate App、Upload，以及 App Store Connect 的 Processing 屬於不同階段。每個階段產生的證據不同，修復動作也不同。
| 看到的症狀 | 優先查看的位置 | 不要先做的事 |
|---|---|---|
| Product > Archive 失敗 | Xcode Report Navigator、Build Settings、嵌入資源 | 不要先重做 Distribution Certificate |
| Archive 成功，Validate App 失敗 | Xcode Organizer 的驗證訊息 | 不要把模擬器可執行當成可提交證明 |
| Upload 中斷或登入失敗 | Xcode delivery log、Transporter error log | 不要重新編譯另一個歸檔檔案 |
| 上傳完成但沒有構建 | App Store Connect 的 Build Uploads | 不要盲目增加 version 或 build number |
| 顯示 Processing、Failed 或 Invalid Binary | 構建詳細頁面的錯誤與警告 | 不要只看 TestFlight 主畫面 |
Apple 說明，構建上傳後仍需經過系統處理，完成前不一定會立即出現在 App Store Connect；版本號與 Bundle ID 用於關聯應用程式記錄，build string 則用來識別單一構建。可參考 Apple 的 Upload builds 說明。
建議先保存五項資料：錯誤原文、發生時間、上傳工具、version、build number。這些資料比「再試一次」更能判斷問題究竟停在哪一層。
第一個分界：Archive 成功，不等於發布包可提交
Xcode 能在模擬器或 Debug 模式正常執行，不代表 Release 構建可以提交。發布流程至少要確認三件事：
- 目標 Scheme 使用正確的 Release 設定。
- Product > Archive 能在正確的平台與目的地完成。
- Organizer 中的 Validate App 沒有阻斷性錯誤。
Apple 的發布流程要求先建立 archive，再從 Organizer 執行 Validate App；這個驗證會進行有限度的自動檢查，但不等於完成 App Store Connect 的所有伺服器端檢查。可參考 Apple 的 Xcode 發布文件。
因此，遇到「Xcode 歸檔成功但無法上傳 App Store Connect」時，先查看 Validate App 的原始結果。常見檢查點包括：
- Bundle ID 是否與應用程式記錄一致。
- Release 設定是否混入 Development entitlements。
- Framework、Extension、資源檔是否被正確嵌入。
- 目標平台是否選錯，例如把 Mac Catalyst 與 iPad 目標混在同一個歸檔中。
- Archive 內的版本號與構建號，是否就是預期要提交的版本。
為什麼模擬器可以執行，發布包仍然會失敗？
模擬器執行主要證明目前建置目標可運作；它不會替代分發簽名、App ID、Provisioning Profile、嵌入內容與 App Store Connect 驗證。判斷發布包是否合格，應以 Organizer 的 archive 與 Validate App 結果為準。
帳戶、角色與 App 記錄：入口問題不要誤判成憑證問題
如果 Archive 與 Validate App 都成功，但上傳一開始就被拒絕，先檢查帳戶鏈路。App Store Connect 的上傳權限不是所有團隊成員都相同。Apple 列出的可上傳角色包括 Account Holder、Admin、App Manager 與 Developer；實際可見範圍仍會受到應用程式存取權限影響。可參考 Apple 的角色權限表。
需要逐項核對：
- Xcode 登入的 Apple Account 是否屬於正確 Team。
- App Store Connect 中是否已建立該 App record。
- 使用者是否被授予該應用程式的存取權限。
- 組織帳戶的合約、稅務或使用條款是否需要由 Account Holder 處理。
- 自動化流程使用的 API Key，是否屬於正確組織，且權限沒有被撤銷。
Apple Developer Program 的網站權限與 App Store Connect 權限並不完全等同。只被加入 App Store Connect 的使用者，未必能管理 Certificates、Identifiers & Profiles。可參考 Apple 的帳戶與角色說明。
若錯誤文字包含權限不足、App 不存在、無法存取或無法建立版本，先讓帳戶管理者確認應用程式記錄與角色，不要直接刪除本機 Keychain 的憑證。
程式碼簽名、Bundle ID 與構建號：三組資料必須對得上
遠端 Mac 上傳 App Store Connect 時簽名失敗，最容易出現的問題不是「沒有憑證」，而是簽名資產彼此不屬於同一條鏈。
| 核對項目 | 應該一致的內容 | 典型錯誤 |
|---|---|---|
| Team | Xcode、Apple Developer、App Store Connect 使用同一團隊 | 遠端 Mac 登入了另一個 Team |
| Bundle ID | 專案設定、App ID、Provisioning Profile 相同 | Extension 或主 App 使用不同識別字串 |
| Distribution Certificate | Profile 內包含可用的分發憑證 | 只有公鑰，私鑰不在遠端 Keychain |
| Provisioning Profile | 對應平台、App ID 與分發用途 | 使用 Development Profile 上傳商店構建 |
| Version / Build | App record 可接受的版本與唯一構建識別 | 讀取到舊 Archive 的構建號 |
Apple 文件指出，App Store provisioning profile 必須使用明確的 App ID，並選擇與該 App ID 相符的分發憑證；若選擇自動管理簽名，Xcode 可以代為管理分發 profile。可參考 Apple 的 App Store provisioning profile 文件。
修復時，先採取低風險動作：
- 在 Xcode Signing & Capabilities 確認 Team 與 Bundle Identifier。
- 執行
codesign或 Xcode Organizer 的簽名檢查，確認使用哪個 identity。 - 確認遠端 Mac 的 Keychain 同時有憑證與對應私鑰。
- 逐一檢查主 App、Extension、Notification Service 等目標。
- 保留現有憑證、私鑰與 profile 的備份，再決定是否重建資產。
提醒： 沒有備份私鑰與自動化所需的憑據前，不要一次撤銷全部 Distribution Certificate，也不要把所有 Provisioning Profile 全部刪除。這種做法可能讓原本可用的本機流程與 CI 流程同時失效。
Xcode、Transporter 與命令列：先固定同一個 Archive
上傳中斷時，工具本身只是觀察窗口，不應被當成第一個嫌疑對象。Xcode Organizer 適合查看歸檔、驗證與交付紀錄；Transporter 適合檢查交付進度、警告、錯誤與歷史紀錄；命令列則更適合無人值守工作。
建議使用同一個 .xcarchive 或由它匯出的 .ipa 交叉驗證：
- 在 Xcode Organizer 對該 Archive 執行 Validate App。
- 若驗證通過，先由 Xcode 上傳，不要重新編譯。
- 若 Xcode 上傳失敗，再用 Transporter 上傳同一個檔案。
- 記錄兩次操作的時間、帳戶、Team 與錯誤文字。
- 若只在自動化流程失敗，檢查工作階段、Keychain 解鎖、環境變數與工作目錄。
- 若使用 SSH，確認工作不會因連線中斷而被終止；必要時將任務交給可恢復的背景工作管理器。
- 儲存完整 delivery log，而不是只截取最後一行錯誤。
Apple 的 Transporter 指南說明，Transporter 可輸出詳細錯誤，也可指定錯誤日誌目錄；批次交付時應保留個別套件的紀錄。可參考 Transporter User Guide 的日誌說明。
Transporter 上傳 iOS App 失敗，如何查看日誌？
先看終端機輸出，再以 -errorLogs 將每個套件的錯誤寫入指定目錄。若是批次交付，應分離出該套件的個別日誌。日誌中要保留錯誤代碼、時間戳、套件名稱與 Apple 回傳訊息，這些內容比單純重新點擊 Upload 更有診斷價值。
構建已送出但不可見：改查 Apple 端處理狀態
如果 Transporter 或 Xcode 顯示交付完成，但 TestFlight 沒有立即看到構建，先進入：
Apps → 選擇 App → TestFlight → 平台 → Build Uploads
不要只看版本頁面。Apple 說明，構建會依 version number 分組，build number 用於識別單一構建；Build Uploads 可查看版本、構建號、上傳狀態、日期，以及錯誤與警告詳細內容。可參考 Apple 的構建與中繼資料文件。
不同狀態的處理方式如下：
- Processing：Apple 仍在處理。若超過 24 小時仍未變更，再提交 Feedback Assistant 或聯絡支援。
- Failed：處理已結束但發現問題。先開啟構建詳細頁，修正所有錯誤後再上傳。
- Complete：構建已處理完成，可供測試；若旁邊有警告標記，仍應查看內容。
- Invalid Binary：Apple 已收到構建，但檔案未符合上傳要求，通常需要修正後重新交付。
- Missing Compliance：構建缺少出口合規資料，先補充要求的資訊，再判斷是否需要重傳。
Apple 的狀態說明指出，若 Processing 超過 24 小時可能代表處理異常；若是 Failed，下一次上傳可以重用相同的 build number，不必為了狀態本身盲目遞增。可參考 Apple 的構建上傳狀態說明。
App Store Connect 上傳後看不到構建，應該怎麼辦？
先確認 Build Uploads 是否存在該次交付，再依狀態分辨「仍在處理」、「需要補資料」或「必須修正後重新上傳」。如果 Build Uploads 完全沒有紀錄，優先回查工具端的交付日誌、登入 Team、App record 與檔案是否真的送出。
遠端 Mac 發布鏈路：用同一份構建完成驗收
當錯誤只在遠端 Mac、SSH 或無人值守任務中出現，問題可能不在 App 本身，而在執行環境。此時不應只測試「能否登入」，而要測試整條發布鏈路。
可先依照 ProxyMac 的使用說明 確認遠端連線與工作階段，再執行以下清單：
- [ ] 互動式登入 Mac，開啟同一個專案並成功建立 Archive。
- [ ] 在 Organizer 中完成 Validate App，保存驗證結果。
- [ ] 使用相同 Archive 執行一次 Xcode Upload。
- [ ] 使用相同匯出檔案執行一次 Transporter Upload。
- [ ] 透過 SSH 執行不需圖形介面的驗證或上傳任務。
- [ ] 確認 Keychain 在非互動式工作階段仍可取得簽名私鑰。
- [ ] 人為中斷 SSH 連線後，確認背景任務是否仍能完成或安全失敗。
- [ ] 重新連線後，能取得完整日誌與目前處理狀態。
- [ ] 在 App Store Connect 的 Build Uploads 中核對 version、build number 與狀態。
驗收結果可分成三檔：
- 通過：互動式、SSH、無人值守三種方式都能使用同一份構建完成交付。
- 條件通過：只有互動式方式穩定，SSH 或背景任務仍需處理 Keychain、會話或日誌保存。
- 不通過：本機與遠端的 Team、Bundle ID、簽名資產或 Archive 內容不一致，尚不適合承擔持續發布。
若需要先固定遠端環境，可從 ProxyMac 的登入入口 建立一次可保留的 Mac 工作階段，再決定是否長期使用。重點不是「換一台電腦再試」，而是讓專案、簽名狀態、上傳檔案與錯誤日誌能夠被完整重現。
對只在臨時電腦、斷線 SSH 或無人值守任務中反覆失敗的團隊而言，原本的方案通常有三個缺點：環境容易被清理、私鑰與 Keychain 狀態不穩定、錯誤日誌難以保留。若改用本身可持續連線的 Mac 環境，便能先用同一份 Archive 完成對照測試，再決定是否需要長期打包機。需要臨時修復、跨裝置驗收或短期持續發布時，租用 ProxyMac 的 Mac 會比臨時拼裝本機或雲端任務更容易保留上下文；若是長期高負載編譯、必須接觸實體 iPhone 或需要固定硬體周邊，則仍應評估自購 Mac 的合理性。若要比較可用方案，可參考 ProxyMac 的方案與價格頁面，但應先完成上述故障定位，再選擇租用週期。
