建置與發布 iOS 應用程式

本指南將逐步說明如何將 Flutter 應用程式發布到 App Store 和 TestFlight。

建置與發布您的應用程式需要使用 Xcode。 您必須在執行 macOS 的裝置上操作，才能依照本指南進行。

在開始發布應用程式之前，請確保您的應用程式符合 Apple 的 App Review Guidelines（App 審查指引）。

若要將應用程式發布到 App Store，您必須先加入 Apple Developer Program（Apple 開發者計畫）。 您可以在 Apple 的 Choosing a Membership 指南中，瞭解各種會員方案的詳細資訊。

如果您偏好觀看影片而非閱讀文字，下方影片涵蓋了與本指南相同的內容。

透過 App Store Connect (formerly iTunes Connect) 管理您的應用程式生命週期。 您可以在此定義應用程式名稱與描述、加入螢幕截圖、設定價格，並管理 App Store 與 TestFlight 的發布。

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

如需 App Store Connect 的詳細介紹，請參閱 App Store Connect 指南。

每個 iOS 應用程式都會對應一個 Bundle ID，這是向 Apple 註冊的唯一識別碼。 要為您的應用程式註冊 Bundle ID，請依照下列步驟操作：

1. 開啟開發者帳戶的 App IDs 頁面。
2. 點選 + 以建立新的 Bundle ID。
3. 輸入應用程式名稱，選擇 Explicit App ID，並輸入一個 ID。
4. 選擇您的應用程式所需的服務，然後點選 Continue。
5. 在下一頁確認細節後，點選 Register 完成 Bundle 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 區段，選擇您在前一步註冊的 Bundle ID。

如需詳細說明，請參閱 Add an app to your account。

本步驟將帶您檢查 Xcode 工作區中最重要的設定。 如需詳細步驟與說明，請參閱 Prepare for app distribution。

在 Xcode 中前往目標設定：

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，大多數應用程式使用此設定即可。如需更進階的情境，請參閱 Code Signing Guide。

Team

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

在 Build Settings 分頁的 Deployment 區段：

iOS Deployment Target

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

您的專案設定的 General 分頁應類似下圖：

如需應用程式簽署的詳細說明，請參閱 Create, export, and delete signing certificates。

如果您在 Xcode 專案中變更了 Deployment Target，請開啟 Flutter 應用程式中的 ios/Flutter/AppframeworkInfo.plist，並將 MinimumOSVersion 的值更新為一致。

當建立新的 Flutter 應用程式時，系統會產生一組預設的佔位圖示。此步驟將說明如何將這些佔位圖示替換為您自己的應用程式圖示：

1. 請參閱 iOS App Icon 指南，特別是關於 建立淺色、深色與色彩變化 圖示的建議。
2. 在 Xcode 專案導覽器中，選擇 Assets.xcassets（位於 Runner 資料夾內）。將預設圖示替換為您自己的應用程式圖示。
3. 透過執行 flutter run 來驗證圖示已成功替換。

與應用程式圖示類似，您也可以替換預設的啟動畫面圖片：

1. 在 Xcode 專案導覽器中，選擇 Assets.xcassets（位於 Runner 資料夾內）。將預設啟動畫面圖片替換為您自己的圖片。
2. 透過熱重啟（hot restart）您的應用程式來驗證新的啟動畫面圖片。（請勿使用 hot reload。）

在開發過程中，您一直使用 debug 模式進行建置、除錯與測試。當您準備好將應用程式發布到 App Store 或 TestFlight 給使用者時，需準備 release 模式的建置版本。

應用程式的預設版本號為 1.0.0。 若要更新版本號，請前往 pubspec.yaml 檔案，並更新下列這一行：

version: 1.0.0+1

版本號由三個以點分隔的數字組成， 例如上方範例中的 1.0.0，後面可選擇性加上一個 建置號（build number），如上方範例中的 1，兩者之間以 + 分隔。

你可以在 flutter build ipa 中分別透過指定 --build-name 和 --build-number 來覆寫版本號與建置號。

在 iOS 中，build-name 會使用 CFBundleShortVersionString， 而 build-number 則會使用 CFBundleVersion。 你可以在 Apple Developer 網站上的 Core Foundation Keys 閱讀更多關於 iOS 版本管理的資訊。

你也可以在 Xcode 中覆寫 pubspec.yaml 的建置名稱與號碼：

1. 在你的應用程式 ios 資料夾中開啟 Runner.xcworkspace。
2. 在 Xcode 專案導覽區選取 Runner，然後在設定檢視側邊欄選擇 Runner target。
3. 在 Identity 區段，將 Version 更新為你想要發布給使用者看到的 版本號。
4. 在 Identity 區段，將 Build 識別碼更新為一個用於在 App Store Connect 追蹤此建置的唯一建置號。 每次上傳都需要一個唯一的建置號。

執行 flutter build ipa，即可在你的專案 build/ios/archive/ 目錄中產生一個 Xcode 建置封存檔（.xcarchive 檔案）， 並在 build/ios/ipa 產生一個 App Store app bundle（.ipa 檔案）。

你可以考慮加入 --obfuscate 與 --split-debug-info 旗標來 混淆你的 Dart 程式碼，讓逆向工程變得更加困難。

如果你不是要發佈到 App Store，也可以選擇不同的 export method， 只需加上 --export-method ad-hoc、 --export-method development 或 --export-method enterprise 選項。

建立好 app bundle 後，可以透過以下方式 上傳至 App Store Connect：

1. 安裝並開啟 Apple Transport macOS app。 將 build/ios/ipa/*.ipa app bundle 拖曳到該應用程式中。

2. 或是在命令列執行下列指令來上傳 app bundle：

   bash

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

   執行 man altool 以取得如何使用 App Store Connect API 金鑰進行驗證的詳細說明。

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

   點擊 Validate App 按鈕。如果有任何問題被回報，請修正後重新產生一次 build。在你上傳封存檔（archive）之前，可以重複使用同一個 build ID。

   當封存檔成功驗證後，請點擊 Distribute App。

你可以在 App Store Connect 上你的應用程式詳細頁面的 Activities 分頁中，追蹤 build 的狀態。 你應該會在 30 分鐘內收到一封電子郵件，通知你的 build 已通過驗證，並可在 TestFlight 上釋出給測試者。 此時，你可以選擇是否在 TestFlight 上釋出，或直接將你的應用程式發佈到 App Store。

欲了解更多詳情，請參閱 Upload an app to App Store Connect。

本步驟說明如何使用 Flutter build 指令及 Codemagic CLI Tools，在 Flutter 專案目錄的終端機中建立 build 封存檔並上傳到 App Store Connect。這讓你可以在與登入鑰匙圈（login keychain）隔離的暫存鑰匙圈中，完全掌控發佈憑證，建立 build 封存檔。

1. 安裝 Codemagic CLI 工具：

   bash

   pip3 install codemagic-cli-tools

2. 你需要產生一組具有 App Manager 存取權限的 App Store Connect API Key，以便自動化與 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`

3. 你需要匯出或建立一個 iOS 發行（Distribution）憑證，才能進行程式簽署並封裝建置歸檔檔案。

   如果你已有現有的 憑證，可以針對每個憑證執行以下指令來匯出私密金鑰：

   bash

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

   或者，你也可以執行以下指令來建立新的私密金鑰：

   bash

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

   之後，你可以讓命令列介面 (Command Line Interface, CLI) 工具根據私鑰自動建立新的 iOS 發佈憑證（iOS Distribution）。

4. 設定一個新的暫時性鑰匙圈（keychain），用於程式碼簽署（code signing）：

   bash

   keychain initialize

5. 從 App Store Connect 取得簽署檔案（code signing files）：

   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

   其中 cert_key 可以是你匯出的 iOS 發行（Distribution）憑證私鑰，或是一組新的私鑰（此時會自動產生新的憑證）。如果 App Store Connect 中尚未存在該憑證，系統會根據私鑰建立憑證。

6. 現在，請將取得的憑證加入你的鑰匙圈（keychain）：

   bash

   keychain add-certificates

7. 更新 Xcode 專案設定以使用擷取到的簽章設定檔：

   bash

   xcode-project use-profiles

8. 安裝 Flutter 相依套件：

   bash

   flutter packages pub get

9. 安裝 CocoaPods 相依套件：

   bash

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

10. 建置 Flutter 的 iOS 專案：

    bash

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

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

11. 將應用程式發佈到 App Store Connect：

    bash

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

12. 如前所述，請不要忘記將您的登入鑰匙圈（login keychain）設為預設，以避免您的機器上應用程式發生驗證問題：

    bash

    keychain use-login

你應該會在 30 分鐘內收到一封電子郵件，通知你建置已通過驗證，並可在 TestFlight 上釋出給測試者。此時，你可以選擇是否要在 TestFlight 上釋出，或是直接將你的應用程式發佈到 App Store。

TestFlight 讓開發者可以將應用程式推送給內部與外部測試者。這個選擇性步驟說明如何在 TestFlight 上釋出你的建置版本。

1. 前往 App Store Connect 中你應用程式的詳細資料頁面的 TestFlight 分頁。
2. 在側邊欄選擇 Internal Testing（內部測試）。
3. 選擇要釋出給測試者的建置版本，然後點擊 Save（儲存）。
4. 新增任何內部測試者的電子郵件地址。你可以在 App Store Connect 頁面頂部下拉選單中的 Users and Roles（使用者與角色）頁面新增更多內部使用者。

如需詳細資訊，請參閱 Distribute an app using TestFlight。

當你準備好將應用程式發佈給全球用戶時，請依照以下步驟提交應用程式審查並發佈到 App Store：

1. 在 App Store Connect 中你應用程式的詳細資料頁面側邊欄，選擇 Pricing and Availability（價格與可用性），並完成所需資訊。
2. 在側邊欄選擇狀態。如果這是此應用程式的首次發佈，其狀態會是 1.0 Prepare for Submission（1.0 準備提交）。請填寫所有必填欄位。
3. 點擊 Submit for Review（提交審查）。

Apple 會在應用程式審查流程完成時通知你。你的應用程式將依照你在 Version Release（版本釋出）區段中指定的指示進行發佈。

如需詳細資訊，請參閱 Distribute an app through the App Store。

Distribute your app 指南提供了將應用程式發佈到 App Store 流程的詳細說明。