fastlane 自動打包：2026 遠端 Mac 上架教學

Apple 的 App Store Connect 上傳規則已說明，2026 年起上傳至少需要 Xcode 14；但「能上傳」不等於「能穩定發布」。因此，你應先在遠端 Mac 建立可重複執行的 fastlane 自動打包流程，依序驗收建置、簽名、上傳與憑據復原，確認 TestFlight 穩定可見後，才開啟自動提交審核。(Apple App Store Connect 上傳建置規則)

本週建議動作：先完成一次「拉取程式碼 → Archive → 上傳 TestFlight」的人工觸發流程，保存完整日誌；不要第一天就把自動審核、版本資訊和二進位檔上傳綁成一個不可拆解的命令。

這篇適合沒有本地 Mac、使用 Windows 或 Linux 開發的 iOS 獨立開發者，也適合已能手動上架、卻經常被憑證或 Provisioning Profile 卡住的開發者。若你想把遠端 Mac 變成長時間運作的 iOS 打包伺服器，下面的時間軸可以直接作為部署基準。

先把「成功上架」拆成四個可驗收狀態

很多 fastlane 教學只展示安裝指令，卻沒有處理「建置完成但簽名失敗」或「上傳成功但 App Store Connect 尚未顯示」的情況。實際部署時，至少要分辨以下四個狀態：

App Store Connect 會使用 App Bundle 內的 Bundle ID、版本號與 Build String 對應應用程式及版本記錄；首次上傳後，Apple 仍需處理建置，完成後才會在後台顯示。不要把命令列回傳成功，直接等同於 TestFlight 已可測試。

這也是為什麼本文建議先打通 TestFlight，再處理自動提交審核。提交審核涉及版本資訊、出口合規、截圖與商店中繼資料，和二進位檔是否成功上傳是不同問題。

動手前先固定遠端 Mac 的工具鏈與權限

遠端 Mac 的價值不只是能開啟 Xcode，而是讓每次建置都使用可追蹤的 macOS、Xcode、SDK、Ruby 與專案依賴。Apple 的 Xcode 系統要求與 SDK 對照表會隨正式版與測試版更新；截至 2026 年 8 月 12 日，穩定版本為 Xcode 26.6，測試版本則以官方頁面當時列出的版本為準。部署前應以官方表格核對，而不是只看機器名稱。

你需要先確認：

• 遠端 Mac 的 macOS 能支援專案所需的 Xcode。
• Xcode 的 SDK、Simulator 與目標部署版本符合專案要求。
• 專案已有唯一 Bundle ID，且 App Store Connect 已建立對應 App 記錄。
• Git 儲存庫能完整還原 Gemfile、Gemfile.lock、Fastfile、Appfile 與專案原始碼。
• 執行帳號能透過 SSH 操作命令列，圖形控制台則用於 Xcode 登入、Keychain 或簽名問題排查。
• root 權限只用於安裝系統工具、處理服務權限或磁碟配置，不要讓發布腳本長期以 root 執行。

若你使用遠端 Mac，SSH 適合拉取程式碼、執行 Lane 和擷取日誌；圖形控制台適合第一次登入 Apple 開發者帳號或檢查 Xcode 的 Signing 設定。兩者用途不同，不能因為有 root 權限，就把所有憑據直接放在共用目錄。

第一小時固定 fastlane 與專案依賴

fastlane 官方文件提供 RubyGems、Homebrew 及 fastlane init 等安裝方式；對持續整合環境而言，更重要的是把版本交給 Bundler 管理，而不是每次直接安裝目前最新版。可先在遠端 Mac 執行：

xcode-select --install
bundle init

接著在 Gemfile 內加入 fastlane，然後執行：

bundle install
bundle exec fastlane init

把下列檔案提交到 Git：

Gemfile
Gemfile.lock
fastlane/Appfile
fastlane/Fastfile

初始化時要核對三件事：你使用的是 .xcworkspace 還是 .xcodeproj、要建置的 scheme 名稱是否可供命令列使用，以及 Release 設定是否連到正確的 Bundle ID。fastlane 官方的 iOS App Store 部署文件也以 build_app 和 upload_to_app_store 組成基本流程。

第一條 Lane 不要上傳，先只做建置：

default_platform(:ios)

platform :ios do
  lane :build_only do
    build_app(
      workspace: "Example.xcworkspace",
      scheme: "Example",
      configuration: "Release",
      clean: true,
      export_method: "app-store"
    )
  end
end

執行：

bundle exec fastlane build_only

把這次完整輸出保存為基線。build_app 會產生 IPA，並可透過 DEVELOPER_DIR 指定 Xcode；原始 xcodebuild 日誌通常可在 ~/Library/Logs/gym 找到。你應同時記錄產物路徑、Bundle ID、版本號、Build String 和簽名模式，否則後續只看到一行「成功」時，很難判斷到底成功了哪一層。

沒有本地 Mac，也可以完成 iOS 打包嗎？

可以，但遠端 Mac 必須具備可用的 macOS、Xcode、Apple 開發者帳號與簽名資產。你可以在 Windows 或 Linux 上編輯程式碼、推送 Git、觸發 SSH 命令；真正的 Xcode Archive、簽名與 App Store Connect 上傳，仍在遠端 Mac 執行。

常見的隱性成本有三項。第一是環境漂移：Xcode 被升級、Command Line Tools 指向改變，可能令原本成功的 Lane 失效。第二是磁碟與暫存檔：Archive、DerivedData、Simulator 資料和日誌會持續累積。第三是連線與權限：SSH 可以通，但 Keychain 鎖定、圖形登入過期或 API Key 權限不足，仍會讓無人值守流程中斷。

因此，遠端 Mac 不是把本地電腦「搬到雲端」，而是需要像伺服器一樣管理版本、權限、日誌與恢復方式。若你要評估 VPSMAC 的遠端 Mac 方案，可先查看遠端 Mac 服務與使用方式，再依你的發版頻率確認是否需要持續在線的環境。

Xcode 自動簽名與 match 的取捨

單人專案且環境變化少時，Xcode 自動簽名通常較快；但在遠端 Mac 或持續整合環境，若每次建置都允許 Xcode 自行建立或修改簽名資產，失敗原因會變得難以追蹤。

這個評分是本文按可追蹤性、恢復性和維護成本作出的決策分數，不是 Apple 或 fastlane 的官方評級。fastlane 的 match 文件說明，它可以為多個 Bundle ID 同步憑證與 Provisioning Profile；在 CI 環境中，建議以只讀方式取得既有資產，避免自動建立、撤銷或覆寫簽名資料。

如果你選擇 match，不要把解密密碼、憑證儲存庫存取權杖或 .p8 私鑰提交到應用程式原始碼。多環境專案應先確認 Debug、Ad Hoc、App Store 等用途是否各自有清楚的簽名策略，再把簽名同步放進建置前階段。

注意：建置成功只代表 Xcode 產生了產物，不代表產物一定能通過簽名、上傳或 TestFlight 處理。每一階段都應保留可獨立重跑的命令與日誌。

使用 App Store Connect API Key 隔離上傳憑據

自動上傳建議使用 App Store Connect API Key，而不是把個人 Apple ID 密碼放在遠端 Mac。Apple 文件說明，API Key 由 Key ID、Issuer ID 與只能下載一次的私有金鑰組成；私有金鑰一旦遺失或疑似外洩，應立即撤銷。角色權限會決定 API 可執行的範圍。(App Store Connect API Key 說明)

你的保存方式應符合以下原則：

1. 在 App Store Connect 的 Users and Access／Integrations 建立適合的 API Key。
2. 只選擇完成上傳所需的最低角色，不要為方便而使用過高權限。
3. 將 .p8 私鑰放在遠端 Mac 的受限目錄，設定檔只保存路徑或由環境變數注入。
4. 將私鑰加入 .gitignore，並在部署檢查中確認它沒有出現在 Git 歷史。
5. 以占位符撰寫 api_key.json，例如：

{
  "key_id": "YOUR_KEY_ID",
  "issuer_id": "YOUR_ISSUER_ID",
  "key_filepath": "/secure/path/AuthKey_YOUR_KEY_ID.p8",
  "in_house": false
}

1. 先用非生產 App 或 TestFlight 流程驗證權限，再把相同方法套用到正式 App。

Apple 也區分 Team API Key 與 Individual API Key；前者可按角色套用至團隊 App，後者與個別使用者權限相關，不能把兩者當成完全相同的部署憑據。

首次上傳先停在 TestFlight，不要立即提交審核

建立上傳 Lane 時，先將建置與上傳分開：

platform :ios do
  lane :beta do
    sync_code_signing(
      type: "appstore",
      readonly: true
    )

    increment_build_number(
      build_number: app_store_build_number + 1
    )

    build_app(
      workspace: "Example.xcworkspace",
      scheme: "Example",
      configuration: "Release",
      export_method: "app-store"
    )

    upload_to_app_store(
      api_key_path: "fastlane/api_key.json",
      skip_waiting_for_build_processing: true,
      submit_for_review: false
    )
  end
end

上面的檔案只使用示意識別符，不能直接複製成正式憑據。執行前要確認 app_store_build_number 對應目前 App Store Connect 的版本記錄，否則可能遇到版本號、Build String 或版本記錄不匹配。

排查上傳問題時，先看三個位置：

• fastlane 是否回傳傳輸或驗證錯誤。
• App Store Connect 是否已接收檔案但仍在處理。
• 建置是否出現在正確 App、版本和 TestFlight 位置。

fastlane 的 App Store 上傳 action 文件列出 api_key_path、Build Number 與上傳相關參數。若 fastlane 顯示成功，但 App Store Connect 沒有立即看見建置，先等待 Apple 完成處理並檢查後台狀態；不要因為畫面尚未更新，就立刻重複上傳相同 Build String。

第一週把一次命令改成可恢復的常駐流程

首次 TestFlight 上傳成功後，再逐步加入長期運作所需的檢查。建議順序如下：

1. 從固定分支拉取程式碼，並記錄 commit SHA。
2. 執行 bundle install，確認 Gemfile.lock 沒有被意外改寫。
3. 檢查 xcode-select -p、可用磁碟空間、Keychain 狀態與簽名憑證有效性。
4. 以 match(readonly: true) 或既定手動 Profile 取得簽名資產。
5. 先執行測試，再執行 build_app 產生 Archive 與 IPA。
6. 上傳至 TestFlight，保存 fastlane、gym 和 Apple 回應日誌。
7. 失敗時以非零退出碼結束，通知內容附上 commit、Lane、版本號和日誌路徑。

可安全重試的通常是程式碼拉取、依賴安裝和尚未產生遠端副作用的建置；上傳後則要先查詢 App Store Connect 狀態，再決定是否重跑，避免重複建立版本記錄或誤判 Build String。

建議每次工作完成後清理 DerivedData、過期 Archive 和無限增長的日誌，但不要在失敗處理尚未完成前刪除唯一的診斷檔案。若需要固定的遠端節點、存取方式與支援範圍，可先閱讀 VPSMAC 技術支援說明，再把這套驗收流程套用到實際環境。

用一次真實發布任務完成驗收

不要只用空專案測試。選一個即將發布的真實 App，從 Git 拉取開始，依序記錄：

• 使用的 commit SHA 與 scheme。
• Xcode 路徑及簽名模式。
• Archive 是否產生。
• IPA 的 Bundle ID、版本號與 Build String。
• fastlane 上傳回應。
• App Store Connect 顯示為處理中、可測試或失敗的最終狀態。
• 若中斷，恢復時從哪一個階段重新開始。

完成後，你才知道這台遠端 Mac 是否真的能作為 iOS 打包伺服器，而不是只在互動式 Xcode 視窗中偶爾成功一次。發版頻率低的個人開發者，可以先手動觸發 Lane；每週都有版本的團隊，再加入排程；每次 Git 推送都要建置，則應額外加入分支保護、併發控制與失敗通知。

如果你目前使用的是本地 Windows/Linux 加上臨時借用 Mac 的方式，常見缺點是工具鏈不固定、簽名憑據分散、遠端連線中斷後難以恢復，而且沒有穩定的歷史日誌可供比對。對需要持續 TestFlight 發布的小型團隊而言，先租用一台具備完整權限、固定環境和可保留日誌能力的遠端 Mac，通常比把每次上架都重新排障更容易控制；你可以查看 VPSMAC 的 M4 租用方案，再用本文的四階段驗收表跑通一次真實發布。

完成首次 TestFlight 上傳後，再按你的發版頻率決定是否長期租用：偶爾發布可維持手動 Lane，固定週期發布適合常駐遠端 Mac，而長期高負載建置則應比較自購硬體與租用成本、維護責任及實體裝置需求。先驗收，再擴大自動化，會比一開始追求「一鍵上架」更少留下無法定位的故障。