Apple notarization CI 失敗怎麼排查？2026 修復指南

Apple notarization CI 失敗不一定表示程式碼簽章錯誤。提交成功只代表制品已送出；Apple 的公證服務仍須處理提交並回傳結果，而通過後是否完成票據裝訂，以及交付檔案是否可驗證，也各自需要確認。Apple 對公證流程與可提交制品的說明把這些動作放在同一條發佈工作流中，但它們並不是同一個驗收狀態。

排查時先確認 CI 停在哪一段，而不是先改憑證或重跑整條流水線：

• 提交前失敗：命令尚未取得有效提交識別碼，先查 CI 執行帳號、認證設定、Keychain 權限，以及是否成功連到 Apple 服務。
• 提交後處理中：已有提交識別碼，但狀態尚未顯示最終結果。保留識別碼並查詢狀態，不要把等待中的工作誤判為公證已接受。
• 處理結果不接受：讀取該次提交的官方日誌，按回報的檔案路徑與問題類型修正制品或簽章。
• 公證已接受但發布驗收未完成：另外確認票據裝訂和最終交付檔案驗證；接受結果本身不代表這兩項已完成。

Apple 的 Notary API 說明了如何查看提交狀態和取得日誌；排障時應保存提交識別碼、狀態回應及對應的日誌，而不是只留 CI 的「上傳成功」訊息。Apple Notary API 的提交狀態與日誌說明可作為核對依據。公證是 macOS 軟體分發流程的一環，不應與 App Store 審核混為一談。

notarytool 提交成功但公證狀態失敗，先查看什麼？

先用原提交識別碼查詢狀態，再讀取該提交的 Apple 日誌。若日誌指出簽章或制品問題，才把調查範圍轉向建構產物；若提交命令根本沒有建立可查詢的識別碼，則先檢查認證、工作環境及網路提交環節。notarytool 的提交、狀態查詢與日誌查詢應使用同一組工作脈絡，避免 CI 工作重試後遺失最初的提交識別碼。

處理憑證問題時，要分清楚三件事：用來簽署對外分發軟體的 Developer ID 憑證、可能用於安裝程式封裝的簽章，以及用來向公證服務提交工作的認證資料。它們用途不同；某個提交憑證無法使用，不能直接證明 Mac 節點上的應用簽章有問題。Apple 的程式碼簽章服務說明可用來核對簽章與簽章身分的概念。

建議把錯誤依責任邊界分類：

• 提交認證被拒或無法讀取：檢查 CI 服務帳號實際取得的憑證設定、Keychain 解鎖與存取權限，以及設定是否落在正在執行工作的環境中。
• 簽章身分或簽章鏈有問題：依 Apple 日誌所指向的路徑，檢查最終交付制品的簽章與完整性；不要只檢查中間建構產物。
• 提交無法建立或連線失敗：確認 CI 網路出口、DNS 或代理設定等提交條件，再參照 Apple Developer 系統狀態判斷是否需要進一步排除服務端因素。

提醒：同一個流水線錯誤訊息可能由不同階段造成。先保存完整輸出與提交識別碼，再調整權限或憑證，才能知道修正是否對應到真正的故障來源。

Apple notarization CI 日誌怎麼查，哪些錯誤指向簽章問題？

在保留原始提交識別碼的前提下，使用 notarytool 查詢該次提交的狀態和日誌；不要只搜尋 CI 輸出中的「failed」字樣。Apple 的常見公證問題說明可協助核對日誌指出的問題，並判斷它是否與簽章、制品內容或提交流程相關。

若日誌明確指向某個檔案或簽章問題，應沿著該路徑檢查實際送交公證的檔案；若日誌沒有給出可確認的制品原因，則不要自行把故障歸類為簽章失敗。也要保留命令輸出中的狀態及錯誤內容，避免整理後只剩下無法還原上下文的摘要。

macOS 應用公證失敗，應重簽、重傳還是修复制品？

決策依據應是失敗階段和 Apple 日誌，而不是「重簽一次比較保險」。Apple 的Mac 軟體封裝與分發說明涵蓋了分發制品的準備方式；排查必須對準真正要交付的檔案，而不能只確認較早階段的建構輸出。

• 若狀態顯示提交仍在處理，且尚無最終結果：保留提交識別碼並繼續查該筆狀態，不要建立新的提交來取代尚未確認的工作。
• 若日誌明確指出簽章、簽章鏈或權限問題：先修正被指向的簽章環節，再對最終分發制品重新檢查；只有確認制品簽章確實需要改動，才安排重簽。
• 若日誌指向封裝內容或檔案結構：修正打包流程，重新產生預定交付的檔案，再提交修正後的制品。
• 若原提交沒有建立、網路中斷，或流水線遺失提交脈絡：先確認 Apple 端是否已有可查詢的提交，再決定是否重新上傳，以免把同一故障變成多筆無法對照的工作。
• 若公證已接受但本地驗收失敗：不要重新簽章或重新提交來替代票據處理；先按交付格式檢查裝訂和最後的檔案驗證。

這樣可避免不必要的重跑，也能把修正留在正確故障域。若問題來自 CI 服務帳號無法讀取私鑰，修復制品本身不會解決權限問題；反過來，若 Apple 日誌已指出制品結構不符，只重試網路提交也不會改變檔案內容。

公證接受、票據裝訂和 Gatekeeper 驗證是不同的檢查點。接受結果表示公證處理得到接受狀態；對外分發前仍須按制品格式確認是否需要執行 stapling，並驗證裝訂後的最終交付檔案。Apple 的公證流程文件說明公證與票據裝訂在分發流程中的關係，具體做法應以實際分發格式及 Apple 文件為準。

可以在發布工作中記錄 xcrun stapler staple 的執行結果，並以 xcrun stapler validate 驗證相應檔案；若交付的是外層封裝檔，應確認目前檢查的對象與實際發給使用者的制品一致。不要把中間 .app 的檢查結果當成外層磁碟映像檔或安裝程式已驗證的證據，也不要假設所有封裝格式都能用相同方式裝訂。

公證通過後還要 stapler 嗎，怎樣驗證票據？

是否需要 stapling，要依制品類型和分發方式確認；不能僅憑公證已接受就推定票據已附加到交付檔案。完成對應的裝訂動作後，再驗證實際要發出的最終制品，並將工具輸出與制品版本一併保留。若驗證結果不符，先確認檢查路徑、檔案是否已重新封裝，以及驗證的是不是剛剛裝訂的那一份，而非立即重跑公證。

Mac CI 排障的目標不只是讓工作變成綠色，而是讓團隊能重現「送出了什麼、Apple 回報什麼、最終交付檔案是否完成驗證」。每次發佈至少保留下列證據：

• 最終制品的簽章檢查輸出，以及對應的檔案識別資訊。
• 公證提交識別碼與提交命令的結果。
• 該次提交的狀態回應和 Apple 公證日誌。
• 票據裝訂命令的結果，或依制品格式採用的處理紀錄。
• 對最終交付檔案執行驗證後的輸出。
• CI 使用哪個服務帳號與憑證設定的紀錄；不要把私鑰或認證資料本身寫入一般工作日誌。

依故障選擇下一步：

• 若提交無法建立或認證失敗：先檢查 CI 服務帳號、Keychain 存取和網路出口；在權限與連線問題排除前，不要反覆修改應用簽章。
• 若提交可查但狀態未完成：保留提交識別碼與狀態回應，繼續追蹤同一筆工作，不承諾固定處理時間。
• 若 Apple 日誌指出制品問題：把修正交給建構或封裝流程，重新驗證實際交付檔案。
• 若官方系統狀態或服務回應顯示疑似服務端問題：保存提交資料與系統狀態，避免把它當成節點故障直接改動憑證。
• 若公證已接受但票據驗證失敗：檢查制品格式、裝訂對象與最終檔案，不以重新上傳代替這些本地驗收動作。

若現有方案是由團隊自行維護的 Mac 節點，優點是硬體與環境控制較直接；但服務帳號、Keychain 權限、網路出口與節點維護也需要團隊自行持續承擔。對短期發佈、隔離測試或臨時補充建置容量的需求，遠端真實 Mac 可作為另一種選項；若工作長期且負載穩定，或必須連接特定實體設備，則應先比較自購與自行維護的適配性，不必為租用而租用。可先從 NUKCLOUD 遠端 Mac 服務了解方案，再以實際流水線驗證簽章、公證及最終制品檢查能否完整閉環；環境連線或操作問題則可參考 NUKCLOUD 說明中心。