iOS 開發憑證遷移：2026 更換打包 Mac 驗收清單

症狀：導入 .cer 後，Xcode 仍提示沒有私鑰，或新 Mac 能編譯卻無法 Archive、上傳。
最快解法：不要只搬憑證檔案；遷移包含私鑰的簽名身份，或在新 Mac 重新建立憑證，再逐項核對 Provisioning Profile、App ID、entitlements 和上傳憑據。

這篇適合三類人：準備把舊 Mac 換成遠端 Mac 的獨立開發者、維護無人值守 iOS 打包伺服器的小型團隊，以及舊 Mac 已損壞、需要判斷哪些密鑰可以重建的人。你不需要先理解所有證書類型，但必須按時間線完成驗收，不能把「編譯成功」當成「遷移完成」。

先分清：憑證檔案、私鑰與簽名身份不是同一件事

Apple 的代碼簽名指南明確指出，簽名身份由私鑰加數位憑證組成；憑證本身不是秘密，也不包含私鑰。只有兩者在同一個可用的 Keychain 中，codesign 或 Xcode 才能使用該身份完成簽名。Apple 代碼簽名指南：簽名身份與私鑰

因此，以下檔案不能互相替代：

• .cer：公開憑證，通常不能單獨完成簽名。
• .p12：常用於連同憑證與私鑰匯出的受保護檔案，必須由你設定密碼。
• .mobileprovision 或 .provisionprofile：Provisioning Profile，描述 App ID、憑證及可用能力等關係。
• App Store Connect API Key、APNs Key：服務或上傳用途的獨立密鑰，不是代碼簽名憑證。
• Xcode 專案設定：包括 Team ID、Bundle ID、Signing & Capabilities、配置名稱及自動簽名狀態。

你需要同時處理三個限制。第一，缺少私鑰時，導入公開憑證不會恢復簽名能力。第二，換了證書後，原有 Profile 可能不再匹配。第三，打包伺服器能讀取密鑰，不代表重啟後仍能安全且自動地讀取密鑰。

第一步：遷移前先鎖定簽名模式與成功標準

先把專案分成以下其中一種模式，不要在遷移途中混用：

1. Xcode 自動簽名：由 Xcode 根據團隊、App ID、Capabilities 和可用證書處理 Profile。
2. 手動簽名：專案或 Export Options 明確指定證書與 Profile。
3. 自動化簽名：由 CI、Shell、fastlane 或其他任務讀取 Keychain、Profile 和上傳憑據。

在舊 Mac 尚未失效時，建立一份脫敏清單，至少記錄：

• Team ID、Bundle ID 及所有 Target。
• Signing & Capabilities 內已啟用的 App Services。
• Debug、Release 使用的簽名模式。
• Apple Distribution 憑證及其對應私鑰。
• 各 Target 的 Provisioning Profile。
• App Store Connect API Key 或 Transporter 使用的上傳方式。
• 打包使用者、Keychain 名稱、任務啟動方式及重啟後行為。

最終成功標準不是「新 Mac 上的 Xcode 已登入」，而是同一個真實專案能完成：

Release Archive → 簽名驗證 → Export → App Store Connect 上傳 → 平台處理完成。

Apple 說明，App Store Connect 收到構建後仍需在平台處理，完成前不能只憑本地 IPA 判定上傳成功。Apple App Store Connect：上傳構建 另外，帳戶角色也會影響上傳操作；使用 API 或後台功能前，應按官方角色權限頁核對目前帳戶安排。

第二步：舊 Mac 上只匯出完整簽名身份

在舊 Mac 開啟 Keychain Access，搜尋與 Apple Distribution 或專案相關的身份。不要只看一行憑證名稱，應展開項目，確認其下方存在對應私鑰。

若看到憑證但沒有私鑰，先不要匯出，也不要以為它可以在新 Mac 上使用。這通常表示私鑰不在目前 Keychain，或該憑證原本是在另一個 Mac 建立。

建議按以下順序處理：

1. 在 Keychain Access 確認憑證與私鑰屬於同一個簽名身份。
2. 選取完整身份，以受密碼保護的格式匯出。
3. 將匯出檔案放入加密儲存位置，密碼不要與檔案放在同一處。
4. 另外下載仍有效的 Provisioning Profile。
5. 備份專案的簽名設定、Export Options 及自動化環境變數名稱。
6. 逐一盤點 App Store Connect API Key、APNs Key 等獨立憑據。

Apple 的官方說明也指出，私鑰不在憑證檔案內；如果更換開發機，必須從原系統匯出私鑰，再在新系統另行導入。Apple Code Signing Guide：遷移私鑰

注意：私鑰檔案、Keychain 密碼、API 私鑰內容和完整 CI 環境變數不可提交到 Git 儲存庫。日誌可以保留，但要先移除 Team 以外的敏感識別資料、Token、路徑中的帳戶名稱與密鑰內容。

第三步：舊 Mac 無法使用時，改走重建與輪換路徑

如果舊 Mac 已無法開機，先查找安全備份，而不是立即撤銷舊證書。可檢查的來源包括：

• 團隊受控的 Keychain 備份。
• 既有打包伺服器或隔離的自動化環境。
• 由負責人保存的受密碼保護簽名身份匯出檔。
• App Store Connect API Key 和 APNs Key 的獨立安全保存位置。

如果只有公開 .cer，不能從它反推出原私鑰。這時應在帳戶權限允許的情況下建立新證書，然後把新證書加入相應 Profile。Apple 提供的憑證簽署請求流程要求透過 Mac 的 Keychain Access 建立 CSR；重新建立時，私鑰會在新環境生成。Apple：建立憑證簽署請求

不要把「清理舊證書」當成一般整理工作。Apple 說明，撤銷證書後，包含該證書的 Provisioning Profile 會變成無效；如非必要，不要在新 Mac 尚未完成驗收前撤銷。Apple：撤銷憑證的影響

第四步：新 Mac 恢復 Keychain，再恢復專案關係

在新 Mac 導入完整簽名身份後，重新開啟 Keychain Access 檢查：

• 憑證是否顯示為有效。
• 憑證項目下是否能展開對應私鑰。
• 私鑰是否允許目標打包工具使用。
• 自動化使用的 Keychain 是否與互動式登入時相同。

接著再處理 Xcode：

1. 登入正確的 Apple Developer 團隊。
2. 核對 Team ID 與 Bundle ID。
3. 檢查每個 Target 的 Signing & Capabilities。
4. 確認 entitlements 沒有遺漏或誤指向另一個 App ID。
5. 導入或重新下載正確的 Provisioning Profile。
6. 若使用手動簽名，核對 Release 配置與 Export Options。
7. 若使用自動簽名，確認 Xcode 沒有因快取或團隊變更使用錯誤 Profile。

Provisioning Profile 包含單一 App ID 及分發憑證；啟用或停用 App Services、Profile 過期，或證書被撤銷，都可能要求重新生成。Apple：Provisioning Profile 更新規則 Apple 也說明，自動簽名會根據 Bundle ID、entitlements、註冊裝置及證書設定取得合適 Profile，但設定改變時仍可能需要更新。Apple：編輯、下載或刪除 Provisioning Profile

對無人值守打包機，還要測試 Keychain 的解鎖方式。你可以為專用打包使用者建立受控流程，但不應用移除密碼、廣泛放寬存取權或把私鑰明文放入腳本的方式換取「自動化成功」。

第五步：用真實 Archive 分層驗收，不要只看編譯結果

首次驗收應使用真實專案，而不是新建的空白 App。按以下層次記錄結果：

• Build 成功：代表程式碼可編譯，不代表簽名完整。
• Archive 成功：代表已產生歸檔，但仍需檢查簽名身份與 entitlements。
• Export 成功：代表可按指定方式輸出，但仍不能代替平台驗收。
• 簽名驗證通過：確認產物使用正確 Team、Profile 和證書。
• 上傳完成並處理成功：App Store Connect 顯示構建已完成處理，才算發布鏈路通過。

如果使用命令列，所有專案名稱、路徑、Team ID 和密鑰名稱都使用占位符，例如：

xcodebuild \
  -workspace <WORKSPACE_NAME>.xcworkspace \
  -scheme <SCHEME_NAME> \
  -configuration Release \
  -archivePath <ARCHIVE_PATH> \
  archive

驗收記錄應保留完整錯誤上下文，但對外分享或提交工單前要脫敏。常見分界如下：

• 「沒有私鑰」：先回到 Keychain Access，不要重新下載 .cer。
• 「Profile 不匹配」：比較 App ID、證書、Capabilities 和 entitlements。
• 「無法上傳」：分開檢查 Export 產物、App Store Connect 角色及上傳密鑰。
• 「構建長時間處理」：查看 App Store Connect 的上傳狀態與錯誤明細。

Apple 的上傳狀態分為 Processing、Failed 和 Complete；若構建長時間停留在 Processing，應按官方狀態說明進一步排查，而不是重複更換憑證。Apple：構建上傳狀態

中段 FAQ：遷移失敗時先判斷是哪一層出錯

上面的流程解決一般遷移路徑；以下情況則要分開處理，避免把上傳密鑰問題誤判成代碼簽名問題。

iOS 開發憑證要怎樣遷移到另一台 Mac？

先在舊 Mac 匯出包含私鑰的完整簽名身份，再於新 Mac 導入。.cer 只代表公開憑證，不能取代私鑰。Provisioning Profile、專案設定和 App Store Connect 上傳憑據要分開備份，不能只搬一個檔案就宣稱遷移完成。

為甚麼導入憑證後 Xcode 仍提示沒有私鑰？

因為導入的可能只是公開 .cer。在 Keychain Access 展開憑證項目，確認下方有對應私鑰；如果沒有，必須從原 Mac 導出完整身份，或在帳戶權限允許時重新建立證書並更新 Profile。

舊 Mac 無法開機，還能恢復 iOS 簽名嗎？

只有在其他安全備份或打包環境仍保存原私鑰時，才可能直接恢復。公開證書不能還原私鑰。找不到私鑰時，要建立新的簽名憑證，並評估哪些 Profile、CI 憑據和服務密鑰需要同步輪換。

更換遠端 Mac 後 Provisioning Profile 要重新生成嗎？

不一定。若原 Profile 仍有效，且 App ID、Capabilities 和證書沒有變更，可以先下載並導入。但新證書、Profile 過期、App Service 改動或舊證書撤銷，都可能要求重新生成。

怎樣確認新打包 Mac 可以正常簽名和上傳 App？

使用真實專案跑一次乾淨 Release Archive，逐層核對簽名身份、Team ID、Profile 和 entitlements，再完成 Export 及 App Store Connect 上傳。平台顯示構建處理完成後，再測試一次無人值守任務和重啟後的密鑰存取。

下線前決策：保留雙環境，還是立即切換

在新 Mac 已經完成一次成功上傳後，不要立即刪除舊環境。至少保留一段可回退窗口，並完成一次計劃任務或重啟後的打包測試。這不是為了追求兩套永久環境，而是避免新 Mac 的 Keychain 解鎖、Profile 快取或上傳密鑰在無人值守時才暴露問題。

你可以按以下條件作決定：

• 若舊 Mac 仍可用，且新 Mac 尚未完成真實上傳：保留雙環境，暫停清理舊密鑰。
• 若新 Mac 已完成 Archive、簽名驗證、上傳及平台處理：把新 Mac 設為主要環境，再保留舊 Mac 作短期回退。
• 若只有本地 Export 成功，沒有 App Store Connect 處理結果：不要下線舊 Mac，回到上傳驗收。
• 若舊 Mac 已損壞且找不到私鑰：走新證書與 Profile 重建流程，不要繼續嘗試用 .cer 修復。
• 若遠端 Mac 只作臨時發布：採短週期使用，完成發布演練後再決定是否保留常駐環境。
• 若團隊需要每日或按計劃打包：只有在重啟後任務仍能安全讀取 Keychain 和上傳憑據時，才適合轉為長期打包機。

結尾前對照：自有 Mac、雲端流水線與遠端 Mac

如果目前方案是直接在一台個人 Mac 上長期打包，常見缺點是硬碟空間和環境維護責任集中在單一設備、故障時難以即時接手，而且不容易讓團隊按權限共用一套可重現的 macOS 環境。若改用不透明的雲端流水線，則可能遇到環境限制、密鑰注入方式受限及除錯上下文不足。

若舊 Mac 即將停用，你可以先租用 MacDate 的遠端 Mac，以短週期完成簽名遷移、真實 Archive 和 App Store Connect 發布演練；確認流程可重複後，再按發版頻率決定是否保留為常駐 iOS 打包伺服器。選擇前可先查看遠端 Mac 方案與可用環境，並對照裸機 macOS 方案的費用說明。若你需要的是穩定、可保留的專用環境，也可以進一步比較可租用的 M 系列計算節點。