構建併發布 iOS 應用

本指南提供了將 Flutter 應用釋出至 App Store 和 TestFlight 的分步說明。

構建和釋出應用需要 Xcode。您必須使用執行 macOS 的裝置來遵循本指南。

在開始應用釋出流程之前，請確保您的應用符合蘋果的 App 稽核準則。

要將應用釋出到 App Store，您必須首先註冊 Apple Developer Program。您可以閱讀蘋果的選擇會員資格指南，以瞭解更多關於不同會員選項的資訊。

對於更喜歡看影片而不是閱讀文字的使用者，以下影片涵蓋了與本指南相同的內容。

在新標籤頁中觀看 YouTube 影片：“分 7 步釋出由 Flutter 構建的 iOS 應用”

在 App Store Connect（前身為 iTunes Connect）上管理您的應用生命週期。您可以在此定義應用名稱和描述、新增截圖、設定價格，並管理在 App Store 和 TestFlight 上的釋出。

註冊應用包含兩個步驟：註冊唯一的套裝 ID (Bundle ID)，以及在 App Store Connect 上建立應用記錄。

有關 App Store Connect 的詳細概述，請參閱 App Store Connect 指南。

每個 iOS 應用都關聯一個套裝 ID (Bundle ID)，這是一個在蘋果註冊的唯一識別符號。要為您的應用註冊套裝 ID，請按照以下步驟操作

1. 開啟開發者賬戶的 App ID 頁面。
2. 點選 + 號以建立新的套裝 ID。
3. 輸入應用名稱，選擇 Explicit App ID，並輸入一個 ID。
4. 選擇您的應用所使用的服務，然後點選 Continue。
5. 在下一頁上，確認詳細資訊並點選 Register 以註冊您的套裝 ID。

在 App Store Connect 上註冊您的應用

1. 在瀏覽器中開啟 App Store Connect。
2. 在 App Store Connect 著陸頁上，點選 Apps。
3. 點選左上角的 + 號，然後選擇 New App。
4. 在彈出的表單中填寫您的應用詳細資訊。在“平臺 (Platforms)”部分，確保勾選了 iOS。由於 Flutter 目前不支援 tvOS，請勿勾選該選項。點選 Create。
5. 導航到您應用的應用詳情頁面，並從側邊欄選擇 App Information。
6. 在“常規資訊 (General Information)”部分，選擇您在上一步中註冊的套裝 ID。

如需詳細概述，請參閱向您的賬戶新增應用。

本步驟涵蓋了檢查 Xcode 工作區中最關鍵的設定。有關詳細流程和說明，請參閱準備應用分發。

在 Xcode 中導航到您的目標 (Target) 設定

1. 透過在 Flutter 專案目錄的終端視窗中執行 open ios/Runner.xcworkspace，開啟專案中的預設 Xcode 工作區。
2. 要檢視應用的設定，請在 Xcode 導航器中選擇 Runner 目標。

驗證最重要的設定。

在 General 標籤頁的 Identity 部分

顯示名稱 (Display Name)

您應用的顯示名稱。

套裝識別符號 (Bundle Identifier)

您在 App Store Connect 上註冊的 App ID。

在 Signing & Capabilities 標籤頁

自動管理簽名 (Automatically manage signing)

Xcode 是否應自動管理應用簽名和配置檔案。預設設定為 true，這對大多數應用來說已足夠。對於更復雜的場景，請參閱程式碼簽名指南。

團隊 (Team)

選擇與您註冊的 Apple Developer 賬戶關聯的團隊。如果需要，請選擇 Add Account...，然後更新此設定。

在 Build Settings 標籤頁的 Deployment 部分

iOS 部署目標 (iOS Deployment Target)

您的應用支援的最低 iOS 版本。Flutter 支援 iOS 13 及更高版本。如果您的應用或外掛包含使用 iOS 13 以上版本 API 的 Objective-C 或 Swift 程式碼，請將此設定更新為所需的最高版本。

專案設定的 General 標籤頁應與下圖類似

有關應用簽名的詳細概述，請參閱建立、匯出和刪除簽名證書。

當建立新的 Flutter 應用時，會生成佔位圖示集。本步驟涵蓋如何用您自己的應用圖示替換這些佔位圖示。

1. 請查閱 iOS 應用圖示準則，特別是關於建立淺色、深色和著色圖示的建議。
2. 在 Xcode 專案導航器中，選擇 Runner 資料夾中的 Assets.xcassets。用您自己的應用圖示更新佔位圖示。
3. 透過執行 flutter run 啟動應用，驗證圖示是否已替換。

與應用圖示類似，您也可以替換佔位啟動圖。

1. 在 Xcode 專案導航器中，選擇 Runner 資料夾中的 Assets.xcassets。用您自己的啟動圖更新佔位啟動圖。
2. 透過熱重啟 (Hot Restart) 您的應用來驗證新的啟動圖。（請勿使用 hot reload。）

在開發過程中，您一直使用 debug 構建進行構建、除錯和測試。當您準備將應用分發給 App Store 或 TestFlight 上的使用者時，需要準備一個 release 構建。

應用的預設版本號是 1.0.0。要更新它，請導航到 pubspec.yaml 檔案並更新以下行：

version: 1.0.0+1

版本號是三個由點分隔的數字（如上例中的 1.0.0），後跟一個可選的構建編號（如上例中的 1），並以 + 號分隔。

版本號和構建編號都可以在 flutter build ipa 命令中透過分別指定 --build-name 和 --build-number 來覆蓋。

在 iOS 中，build-name 使用 CFBundleShortVersionString，而 build-number 使用 CFBundleVersion。在 Apple 開發者網站的核心基礎鍵 (Core Foundation Keys)部分閱讀更多關於 iOS 版本控制的資訊。

您也可以在 Xcode 中覆蓋 pubspec.yaml 中的構建名稱和編號。

1. 開啟應用 ios 資料夾下的 Runner.xcworkspace。
2. 在 Xcode 專案導航器中選擇 Runner，然後在設定檢視側邊欄中選擇 Runner 目標。
3. 在 Identity 部分，將 Version 更新為您希望釋出的使用者可見版本號。
4. 在 Identity 部分，將 Build 識別符號更新為一個唯一的構建編號，用於在 App Store Connect 上跟蹤此版本。每次上傳都需要一個唯一的構建編號。

執行 flutter build ipa，在專案的 build/ios/archive/ 目錄中生成 Xcode 構建歸檔（.xcarchive 檔案），並在 build/ios/ipa 中生成 App Store 應用套裝（.ipa 檔案）。

考慮新增 --obfuscate 和 --split-debug-info 標誌以混淆您的 Dart 程式碼，從而增加逆向工程的難度。

如果您不釋出到 App Store，可以透過新增 --export-method ad-hoc、--export-method development 或 --export-method enterprise 選項來選擇不同的匯出方法。

一旦應用套裝建立完成，請透過以下任一方式將其上傳至 App Store Connect

1. 安裝並開啟 Apple Transporter macOS 應用。將 build/ios/ipa/*.ipa 應用套裝拖放到該應用中。

2. 或者透過命令列上傳應用套裝：

   bash

   xcrun altool --upload-app --type ios -f build/ios/ipa/*.ipa --apiKey your_api_key --apiIssuer your_issuer_id
   

   content_copy

   執行 man altool 以獲取關於如何使用 App Store Connect API 金鑰進行身份驗證的詳細資訊。

3. 或者在 Xcode 中開啟 build/ios/archive/MyApp.xcarchive。

   點選 Validate App 按鈕。如果報告了任何問題，請解決它們並重新構建。在您上傳歸檔檔案之前，您可以重複使用相同的構建 ID。

   歸檔驗證成功後，點選 Distribute App。

您可以在 App Store Connect 上應用詳情頁面的“活動 (Activities)”標籤頁中跟蹤構建狀態。您應該會在 30 分鐘內收到一封電子郵件，通知您的構建已透過驗證，並可在 TestFlight 上向測試人員釋出。此時，您可以選擇是在 TestFlight 上釋出，還是繼續將應用釋出到 App Store。

更多詳細資訊，請參閱上傳應用至 App Store Connect。

此步驟涵蓋了使用 Flutter 構建命令以及在 Flutter 專案目錄的終端中執行 Codemagic CLI 工具，來建立構建歸檔並上傳至 App Store Connect。這使您能夠在與登入鑰匙串隔離的臨時鑰匙串中，完全控制分發證書並建立構建歸檔。

1. 安裝 Codemagic CLI 工具

   bash

   pip3 install codemagic-cli-tools
   

   content_copy

2. 您需要生成一個具有 App Manager 許可權的 App Store Connect API 金鑰，以自動化 App Store Connect 的操作。為了使後續命令更簡潔，請使用新金鑰設定以下環境變數：issuer id、key id 和 API 金鑰檔案。

   bash

   export APP_STORE_CONNECT_ISSUER_ID=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
   export APP_STORE_CONNECT_KEY_IDENTIFIER=ABC1234567
   export APP_STORE_CONNECT_PRIVATE_KEY=`cat /path/to/api/key/AuthKey_XXXYYYZZZ.p8`
   

   content_copy

3. 您需要匯出或建立 iOS 分發證書來對構建歸檔進行程式碼簽名和打包。

   如果您有現有的證書，可以針對每個證書執行以下命令來匯出私鑰

   bash

   openssl pkcs12 -in <certificate_name>.p12 -nodes -nocerts | openssl rsa -out cert_key
   

   content_copy

   或者，您可以透過執行以下命令建立新的私鑰

   bash

   ssh-keygen -t rsa -b 2048 -m PEM -f cert_key -q -N ""
   

   content_copy

   之後，您可以讓 CLI 工具根據私鑰自動建立新的 iOS 分發證書。

4. 設定一個新的臨時鑰匙串以用於程式碼簽名

   bash

   keychain initialize
   

   content_copy

5. 從 App Store Connect 獲取程式碼簽名檔案

   bash

   app-store-connect fetch-signing-files $(xcode-project detect-bundle-id) \
       --platform IOS \
       --type IOS_APP_STORE \
       --certificate-key=@file:/path/to/cert_key \
       --create
   

   content_copy

   其中 cert_key 是您匯出的 iOS 分發證書私鑰，或是自動生成新證書的新私鑰。如果 App Store Connect 中不存在該證書，將根據私鑰建立證書。

6. 現在將獲取到的證書新增到您的鑰匙串中

   bash

   keychain add-certificates
   

   content_copy

7. 更新 Xcode 專案設定以使用獲取的程式碼簽名配置檔案

   bash

   xcode-project use-profiles
   

   content_copy

8. 安裝 Flutter 依賴項

   bash

   flutter packages pub get
   

   content_copy

9. 安裝 CocoaPods 依賴項

   bash

   find . -name "Podfile" -execdir pod install \;
   

   content_copy

10. 構建 Flutter iOS 專案

    bash

    flutter build ipa --release \
        --export-options-plist=$HOME/export_options.plist
    

    content_copy

    請注意，export_options.plist 是 xcode-project use-profiles 命令的輸出結果。

11. 將應用釋出到 App Store Connect

    bash

    app-store-connect publish \
        --path $(find $(pwd) -name "*.ipa")
    

    content_copy

12. 如前所述，別忘了將您的登入鑰匙串設為預設值，以避免機器上的應用出現身份驗證問題。

    bash

    keychain use-login
    

    content_copy

您應該會在 30 分鐘內收到一封電子郵件，通知您的構建已透過驗證，並可在 TestFlight 上向測試人員釋出。此時，您可以選擇是在 TestFlight 上釋出，還是繼續將應用釋出到 App Store。

TestFlight 允許開發者將應用推送給內部和外部測試人員。此可選步驟涵蓋了在 TestFlight 上釋出您的構建版本。

1. 在 App Store Connect 上導航到您應用詳情頁面的 TestFlight 標籤頁。
2. 在側邊欄中選擇 Internal Testing。
3. 選擇要釋出給測試人員的構建版本，然後點選 Save。
4. 新增內部測試人員的電子郵件地址。您可以在 App Store Connect 的 Users and Roles 頁面中新增額外的內部使用者，該頁面可從頁面頂部的下拉選單中訪問。

更多詳細資訊，請參閱使用 TestFlight 分發應用。

當您準備向全球釋出應用時，請按照以下步驟提交應用進行稽核併發布到 App Store

1. 在 App Store Connect 上應用詳情頁面的側邊欄中選擇 Pricing and Availability，並填寫所需資訊。
2. 從側邊欄選擇狀態。如果這是該應用的首次釋出，其狀態為 1.0 Prepare for Submission。填寫所有必填欄位。
3. 點選 Submit for Review。

當蘋果的 App 稽核流程完成後，他們會通知您。您的應用將按照您在 Version Release 部分中指定的說明進行釋出。

更多詳細資訊，請參閱透過 App Store 分發應用。

分發您的應用指南提供了向 App Store 釋出應用過程的詳細概述。