構建併發布 macOS 應用

本指南將分步介紹如何將 Flutter 應用釋出到 App Store。

在開始釋出應用之前，請確保您的應用符合 Apple 的 App Review Guidelines。

要將應用釋出到 App Store，您必須先註冊 Apple Developer Program。您可以在 Apple 的 Choosing a Membership 指南中詳細瞭解各種會員選項。

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

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

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

每個 macOS 應用都與一個 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 登入頁面，點選 My Apps。
3. 在“我的應用”頁面的左上角點選 +，然後選擇 New App。
4. 在出現的表單中填寫您的應用詳細資訊。在 Platforms 部分，確保勾選了 macOS。由於 Flutter 目前不支援 tvOS，請將該複選框留空。點選 Create。
5. 導航到您應用的應用程式詳細資訊，然後從側邊欄選擇 App Information。
6. 在 General Information 部分，選擇您在上一步中註冊的 Bundle ID。

有關詳細概述，請參閱 Add an app to your account。

此步驟涵蓋了檢查 Xcode 工作空間中最重要的設定。有關詳細程式和說明，請參閱 Prepare for app distribution。

導航到 Xcode 中的目標設定

1. 在 Xcode 中，開啟您應用 macos 資料夾中的 Runner.xcworkspace。
2. 要檢視應用的設定，請在 Xcode 專案導航器中選擇 Runner 專案。然後在主檢視側邊欄中，選擇 Runner 目標。
3. 選擇 General 標籤頁。

驗證最重要的設定。

在 Identity 部分

App Category

您的應用將在 Mac App Store 上列出的應用類別。此項不能為空。

Bundle Identifier

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

在 Deployment info 部分

Deployment Target

您的應用支援的最低 macOS 版本。要檢查 Flutter 支援部署到哪些 macOS 版本，請查閱 Flutter 的 Supported deployment platforms。

在 Signing & Capabilities 部分

Automatically manage signing

Xcode 是否自動管理應用簽名和配置。預設設定為 true，這對於大多數應用來說應該足夠了。對於更復雜的情況，請參閱 Code Signing Guide。

Team

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

您的專案設定的 General 標籤頁應如下所示

有關應用簽名的詳細概述，請參閱 Create, export, and delete signing certificates。

產品識別符號的配置集中在 macos/Runner/Configs/AppInfo.xcconfig 檔案中。對於應用名稱，設定 PRODUCT_NAME；對於版權，設定 PRODUCT_COPYRIGHT；最後，為應用的 Bundle ID 設定 PRODUCT_BUNDLE_IDENTIFIER。

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

version: 1.0.0+1

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

透過指定 --build-name 和 --build-number，可以分別覆蓋 Flutter 構建中的版本號和構建號。

在 macOS 中，build-name 使用 CFBundleShortVersionString，而 build-number 使用 CFBundleVersion。有關 iOS 版本控制的更多資訊，請參閱 Apple Developer 網站上的 Core Foundation Keys。

當建立一個新的 Flutter 應用時，會建立一個佔位符圖示集。此步驟涵蓋了用您應用的圖示替換這些佔位符圖示

1. 檢視 macOS App Icon 指南。
2. 在 Xcode 專案導航器中，選擇 Runner 資料夾中的 Assets.xcassets。用您自己的應用圖示更新佔位符圖示。
3. 透過執行 flutter run -d macos 來執行您的應用，驗證圖示是否已替換。

此步驟涵蓋了使用 Xcode 建立構建歸檔並將您的構建上傳到 App Store Connect。

在開發過程中，您一直使用 *debug* 構建進行構建、除錯和測試。當您準備將應用釋出到 App Store 或 TestFlight 時，您需要準備一個 *release* 構建。此時，您可以考慮 混淆您的 Dart 程式碼，以增加反編譯的難度。混淆程式碼需要為您的構建命令新增幾個標誌。

在 Xcode 中配置應用版本和構建

1. 開啟您應用 macos 資料夾中的 Runner.xcworkspace。要從命令列執行此操作，請從應用程式專案的基礎目錄執行以下命令。

   open macos/Runner.xcworkspace

2. 在 Xcode 專案導航器中選擇 Runner，然後在設定檢視側邊欄中選擇 Runner 目標。
3. 在 Identity 部分，將 Version 更新為您要釋出的面向使用者的版本號。
4. 在 Identity 部分，將 Build 識別符號更新為用於在 App Store Connect 上跟蹤此構建的唯一構建號。每次上傳都需要唯一的構建號。

最後，建立構建歸檔並將其上傳到 App Store Connect

1. 建立應用程式的 release Archive。從應用程式專案的基礎目錄執行以下命令。

   flutter build macos

2. 開啟 Xcode，選擇 Product > Archive，開啟上一步建立的歸檔。
3. 點選 Validate App 按鈕。如果報告了任何問題，請解決它們並生成另一個構建。您可以重複使用相同的構建 ID，直到上傳歸檔為止。
4. 成功驗證歸檔後，點選 Distribute App。您可以在 App Store Connect 上應用詳細資訊頁面的 Activities 標籤頁中跟蹤您的構建狀態。

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

有關更多詳細資訊，請參閱 Upload an app to App Store Connect。

此步驟涵蓋了使用 Flutter 構建命令和在 Flutter 專案目錄的終端中執行的 Codemagic CLI Tools 來建立構建歸檔並將您的構建上傳到 App Store Connect。

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 key file。

   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. 您需要匯出或建立 Mac App Distribution 和 Mac Installer 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 ""

   稍後，您可以讓 CLI 工具自動建立一個新的 Mac App Distribution 和 Mac Installer Distribution 證書。您可以對每個新證書使用相同的私鑰。

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

   bash

   app-store-connect fetch-signing-files YOUR.APP.BUNDLE_ID \
       --platform MAC_OS \
       --type MAC_APP_STORE \
       --certificate-key=@file:/path/to/cert_key \
       --create

   其中 cert_key 是您匯出的 Mac App Distribution 證書私鑰，或者是自動生成新證書的新私鑰。

5. 如果您沒有 Mac Installer Distribution 證書，可以透過執行以下命令建立新證書

   bash

   app-store-connect certificates create \
       --type MAC_INSTALLER_DISTRIBUTION \
       --certificate-key=@file:/path/to/cert_key \
       --save

   使用您之前建立的私鑰的 cert_key。

6. 獲取 Mac Installer Distribution 證書

   bash

   app-store-connect certificates list \
       --type MAC_INSTALLER_DISTRIBUTION \
       --certificate-key=@file:/path/to/cert_key \
       --save

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

   bash

   keychain initialize

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

   bash

   keychain add-certificates

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

   bash

   xcode-project use-profiles

10. 安裝 Flutter 依賴項

    bash

    flutter packages pub get

11. 安裝 CocoaPods 依賴項

    bash

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

12. 構建 Flutter macOS 專案

    bash

    flutter build macos --release

13. 打包應用

    bash

    APP_NAME=$(find $(pwd) -name "*.app")
    PACKAGE_NAME=$(basename "$APP_NAME" .app).pkg
    xcrun productbuild --component "$APP_NAME" /Applications/ unsigned.pkg
    
    INSTALLER_CERT_NAME=$(keychain list-certificates \
              | jq '[.[]
                | select(.common_name
                | contains("Mac Developer Installer"))
                | .common_name][0]' \
              | xargs)
    xcrun productsign --sign "$INSTALLER_CERT_NAME" unsigned.pkg "$PACKAGE_NAME"
    rm -f unsigned.pkg

14. 將打包好的應用釋出到 App Store Connect

    bash

    app-store-connect publish \
        --path "$PACKAGE_NAME"

15. 如前所述，不要忘記將您的登入鑰匙串設定為預設值，以避免您的計算機上的應用程式出現身份驗證問題。

    bash

    keychain use-login

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

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

請參閱 distribution guide，為分發到指定的 Mac 計算機準備歸檔。

當您準備好向世界釋出您的應用時，請按照以下步驟將您的應用提交稽核併發布到 App Store

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

Apple 會在應用稽核流程完成後通知您。您的應用將按照您在 Version Release 部分中指定的說明發布。

有關更多詳細資訊，請參閱 Distribute an app through the App Store。

Distribute your app 指南提供了釋出應用到 App Store 過程的詳細概述。

要了解如何使用開源方式打包和分發您的 Flutter 桌面應用，而無需使用付費的 Apple 開發者賬戶，請檢視此分步 macOS packaging guide。