iOS 打包機遷移要備份什麼？2026 Xcode 27 清單
Apple 的 Xcode 27 官方系統需求頁已把 Xcode 27 的相容條件列為遷移前必查資料。對 Xcode 27 iOS 打包機遷移而言，獲勝者是「以恢復指標驗收的新主機」：適合準備退租遠端 Mac、重建打包機，或把持續整合任務交給另一台 Mac 的團隊。只複製專案目錄或重新安裝 Xcode，都不足以證明發布能力已經轉移。
本文的基準很直接：新環境必須能獨立解析依賴、完成建置、產生 Archive、使用正確簽名身份，並完成與原流程一致的上傳。只有在真實發布與舊主機離線測試都通過後，舊機才適合清理或退租。
這篇適合誰？
準備退租遠端 Mac，但不確定哪些檔案、憑據和金鑰必須帶走的獨立開發者。
需要把 Xcode 27 建置任務遷移至另一台 Mac 的 CI 維護者。
接手外包專案、重建故障打包機，並需要確認發布鏈路可恢復的小型團隊。
最後更新於 2026 年 9 月 8 日；版本與平台行為核對自 Apple 的 Xcode、簽名、Archive、App Store Connect 文件，以及自託管 Runner 官方移除流程。
先用發布能力，而不是檔案數量，定義遷移完成度
一個常見失敗案例是：專案已經複製到新 Mac，依賴也能下載，Debug 建置看似正常；到了正式發版，才發現舊主機的 Keychain 裡保存著唯一可用的私鑰。這不是檔案搬漏，而是遷移的驗收指標設錯。
遷移前先保存最近一次成功發布的對照基線。內容包括：
- Xcode 27 的安裝版本與系統相容條件。
- 專案入口、Workspace、Scheme、Build Configuration。
- 依賴解析結果、建置腳本與匯出設定。
- Bundle ID、Team ID、分發方式與簽名身份。
- Archive、版本號、Build 號碼、上傳結果與產物位置。
- CI 任務名稱、Runner 標籤、環境變數和告警入口。
Xcode 的 Archive 與分發步驟，應以 Apple 官方 Archive 與 App 分發流程作為驗收依據。不要以「新 Mac 上看得到憑證」代替真正的發布測試。
五項恢復指標
| 驗收指標 | 必須保留的對象 | 通過證據 | 舊主機清理條件 |
|---|---|---|---|
| 可重建性 | 原始碼、子模組、鎖定檔、腳本、必要設定 | 乾淨檢出後能解析依賴並建置 | 不再依賴舊主機目錄 |
| 工具鏈一致性 | Xcode 27、SDK、命令列工具、Scheme | 工具路徑與建置設定可追溯 | 新主機能完成目標工作 |
| 簽名可用性 | 憑證、私鑰、Provisioning Profile、Keychain 設定 | 能產生目標分發方式的 Archive | 私鑰已備份且有回退方案 |
| 產物可恢復性 | xcarchive、dSYM、xcresult、匯出設定 | 能開啟 Archive，並核對 UUID | 歷史版本仍能查核 |
| 自動化可接管性 | Runner、fastlane、API Key、環境變數、告警 | 新 Runner 完成隔離驗證任務 | 舊 Runner 已停止接單 |
源碼與工具鏈：可重新下載，不代表可獨立重建
更換 iOS 打包機需要複製哪些檔案？核心不是複製整個使用者目錄，而是帶走能重建發布流程的輸入。建議把內容分成「版本庫已有」、「可由鎖定檔重新取得」和「不在版本庫但不可遺失」三類。
必須逐項核對：
- 主專案、Workspace、子模組與必要的私有套件來源。
- Swift Package Manager、CocoaPods 或其他依賴的鎖定檔。
Gemfile、Gemfile.lock、fastlane 設定與建置腳本。- 未納入版本控制的設定檔、環境變數範本及必要的本機設定。
- Xcode 27 的安裝位置、命令列工具選擇和 Scheme。
- 私有倉庫的存取方式，但不把長期有效的 Token 直接寫進腳本。
可以先在新主機執行以下檢查。路徑必須改成脫敏後的實際位置：
xcode-select -p
xcodebuild -version
git submodule status
bundle exec fastlane --version
預期輸出應能對應原先保存的工具鏈基線，例如：
/Applications/Xcode.app/Contents/Developer
Xcode 27.x
[完成的子模組狀態]
fastlane [版本已記錄]
這段輸出的重點不是追求文字完全相同，而是確認新主機使用的 Xcode 路徑、命令列工具和自動化入口沒有偷偷指向舊硬碟。DerivedData、套件快取和暫存建置目錄可以加快工作，但不能當作專案可重建性的證明。
驗收時先建立乾淨檢出目錄，再解析依賴並建置。若只有複製後的工作目錄能成功，乾淨檢出失敗，代表版本庫或腳本仍缺少必要輸入。
簽名身份：憑證、私鑰與 Profile 必須分開驗收
遠端 Mac 退租前如何備份簽名憑證和私鑰？先確認 Apple Distribution 憑證、對應私鑰、Provisioning Profile 和 Keychain 使用方式，再進行任何匯出或撤銷。只下載 .cer 或只看到 Keychain 中的憑證，並不等於新主機擁有完整簽名身份。
Apple 的 身份匯入與 PKCS #12 說明是檢查憑證與私鑰匯入方式的依據。私鑰匯出檔必須以受控方式保存，密碼不能與檔案放在同一個共享目錄，也不應貼進 Shell 歷史、聊天工具或 CI 日誌。
Provisioning Profile 則應依照 Apple 的 Profile 管理文件重新下載或核對。備份清單至少包括：
- Apple Distribution 憑證名稱與有效狀態。
- 與該憑證配對的私鑰。
- 目標 Bundle ID 對應的 Provisioning Profile。
- 新主機的 Keychain 存取權限與解鎖方式。
- 自動簽名或手動簽名的明確選擇。
- 匯出位置、備份加密方式和回退責任人。
| 資產 | 可否單獨替代 | 新主機驗收方法 | 高風險動作 |
|---|---|---|---|
| Apple Distribution 憑證 | 不能替代私鑰 | 確認憑證與私鑰形成完整身份 | 撤銷前先記錄影響範圍 |
| 私鑰 | 不能由 .cer 還原 |
匯入受控 Keychain 後完成簽名 | 輪換前保留可回退備份 |
| Provisioning Profile | 可重新下載，但須符合 Bundle ID 與用途 | 用目標 Archive 核對簽名 | 刪除前確認沒有其他建置依賴 |
| App Store Connect API Key | 不等同簽名身份 | 以隔離任務測試上傳權限 | 撤銷前更新所有使用者 |
| CI 環境變數 | 不應直接公開 | 使用脫敏值完成流程測試 | 清除舊主機與日誌副本 |
完成匯入後，先做一個與正式分發方式一致的 Archive。驗收證據應是簽名成功、匯出設定正確，並能進入驗證或上傳流程，而不是 Finder 或 Keychain 裡出現幾個檔案。
產物保存：xcarchive 與 dSYM 的價值不同於 IPA
xcarchive 和 dSYM 是否需要長期保存？如果團隊需要日後重新匯出、核查歷史版本或分析崩潰，兩者都不應只因「可以重新建置」而立即刪除。IPA 是可交付檔案；xcarchive 則保留更完整的 Archive 資訊；dSYM 用於把崩潰位址對應回可讀的符號。
Apple 的 dSYM 缺失核對說明應作為符號檔核查依據。每個正式版本至少建立可追溯關係：
版本：<VERSION_PLACEHOLDER>
Build：<BUILD_NUMBER_PLACEHOLDER>
Archive UUID：<ARCHIVE_UUID_PLACEHOLDER>
dSYM：<DSYM_UUID_PLACEHOLDER>
匯出設定：<EXPORT_OPTIONS_PLACEHOLDER>
上傳紀錄：<UPLOAD_RECORD_PLACEHOLDER>
保存時不要只備份 IPA。應分別整理：
xcarchive：用於歷史 Archive 核查及後續匯出。dSYM：用於崩潰符號化與版本對照。xcresult：保留測試、建置與診斷結果。- Export Options：記錄 App Store、Ad Hoc 或其他目標的匯出選擇。
- 正式發布記錄：包含版本、Build、Archive UUID 和上傳結果。
備份完成後，實際開啟 Archive 並檢查內容。若只是把整個資料夾複製到另一個硬碟，卻沒有測試解壓、讀取和匯出，仍不能排除損壞副本。產物與快取也要分開：快取遺失通常可重新產生，正式 Archive 和符號檔則可能直接影響歷史版本恢復。
自託管 Runner：先接管，再停止舊主機接單
自託管 Runner 換到新 Mac 後如何恢復？新 Runner 應先以隔離標籤或非發布任務驗證，確認路徑、權限、環境變數、Keychain 和工具鏈都正確，再讓它接手正式工作。兩台主機同時接收同一類發布工作，可能造成重複建置、重複上傳或難以追查的版本衝突。
遷移清單應包含：
- Runner 名稱、標籤和所屬儲存庫或組織。
- fastlane 入口、Bundler 設定與工作目錄。
- App Store Connect API Key、Key ID、Issuer ID 和權限範圍。
- Team ID、Bundle ID、簽名身份及 Profile 路徑。
- LaunchAgent、排程工作、背景服務和日誌位置。
- 失敗告警、通知頻道和任務保留規則。
App Store Connect API Key 的建立、下載與管理規則，應核對 Apple 官方 API 文件。API Key 不是 Apple Distribution 私鑰的替代品，兩者必須在清單中分開標記。
可以先用占位符執行環境檢查，避免把真實帳號寫進文章、腳本或日誌：
echo "$APPLE_TEAM_ID"
echo "$APPSTORE_KEY_ID"
bundle exec fastlane ios verify_environment
輸出只應顯示脫敏值，例如：
TEAM_ID=<TEAM_ID_PLACEHOLDER>
KEY_ID=<KEY_ID_PLACEHOLDER>
environment check: passed
新 Runner 通過隔離驗證後，再停止舊 Runner 接單。若使用的自動化平台提供 Runner 移除功能，應依照其 自託管 Runner 官方移除流程操作。移除前記錄 Runner 名稱、標籤和回退方法；不要在尚未完成真實發布前直接刪除唯一的舊 Runner。
斷線測試與清理：什麼時候才可以退租舊 Mac？
舊打包機什麼時候可以安全清理？至少要先完成新主機上的真實 Archive、目標分發方式的驗證或 TestFlight 上傳，再暫時讓舊主機離線，重新執行關鍵流程。若流程仍讀取舊主機路徑、舊 Keychain 或舊 Runner，便不能清理。
可使用以下驗收卡：
| 狀態 | 新主機結果 | 舊主機處置 |
|---|---|---|
| 未通過 | 依賴、簽名或上傳仍失敗 | 保留完整環境，不撤銷、不刪除 |
| 部分通過 | 可建置但無法完成正式 Archive 或上傳 | 修正缺口，維持短期並行 |
| 發布通過 | 真實 Archive 與上傳成功 | 先保留回退備份，再停止舊 Runner |
| 斷線恢復通過 | 舊主機離線後仍能重跑關鍵任務 | 清理臨時憑據並安排退租 |
清理前逐項確認：
- 新主機能從乾淨檢出完成建置。
- 新主機能產生與目標分發方式一致的 Archive。
- Apple Distribution 與私鑰能完成簽名。
- Provisioning Profile、API Key 和環境變數均已接管。
- xcarchive、dSYM、xcresult 和發布記錄已在可讀備份中。
- 舊 Runner 已停止接單或按官方流程移除。
- 舊主機的背景服務、排程和登入工作已停止。
- 臨時 Token、過期憑據與共享目錄副本已撤銷或刪除。
- Shell 歷史、CI 日誌和共享資料夾沒有遺留私鑰或 API Key。
任何憑證撤銷、API Key 撤銷、Runner 移除和檔案刪除，都應先寫下影響範圍及回退方法。若沒有可用的私鑰備份，便不要以「新環境看起來正常」作為退租理由。
遷移前的方案取捨：保留舊機、並行驗證，還是直接退租
完整遷移不一定代表必須立即刪除舊主機。根據驗收結果，可採用以下決策：
- 來源碼與工具鏈已通過，但簽名未通過：保留舊機，先完成私鑰和 Profile 接管。
- 簽名已通過，但 Archive 或 dSYM 保存不完整：先補齊產物備份，再做斷線測試。
- 新 Runner 能建置，但正式上傳未驗證：維持舊 Runner 可回退，禁止關閉原任務。
- 真實發布與離線恢復都通過：才進入舊主機清理與退租流程。
如果現有方案是臨時雲端建置，常見缺點是無法直接檢查底層 Keychain、背景服務和長期產物位置；如果是共用或短期主機，還可能遇到環境狀態不透明、Runner 權限難以交接，以及下次發布時才發現私鑰不在手上的問題。對需要 Xcode 27、Apple Distribution 和常駐自動化任務的團隊，改用具備完整權限、固定交付條件的遠端 Mac，通常比在截止日前重新猜測環境更容易驗收。可先查看 SFTPMAC 的遠端 Mac 方案與方案價格頁，再按實際使用週期判斷是否適合。
若目前租用環境即將到期，建議先在新遠端 Mac 完成一次不依賴舊主機的真實發布，再安排退租。需要香港交付條件的團隊，也可核對 SFTPMAC 香港 Mac 方案；但對長期固定重負載、必須持有實體介面，或已有完善本地備援的團隊，自購 Mac 仍可能更合適。