description bug_report

构建和发布为 macOS 应用

本教程将指导开发者如何在 App Store 上发布 Flutter 应用程序。

在开始发布应用程序之前，请确保它符合苹果的 应用程序审查指南。

为了将应用程序发布到 App Store，你必须先注册 苹果开发者计划。可以在 Apple 的 选择会员资格 指南中阅读更多关于各种会员资格的信息。

在 App Store Connect（以前叫 iTunes Connect）上管理应用程序的生命周期。你可以定义应用程序的名称和描述、添加屏幕截图、设置定价以及管理应用程序商店和 TestFlight 的发布。

注册应用程序包括两个步骤：注册一个唯一的 Bundle ID，以及在 App Store Connect 上创建应用程序记录。

有关 App Store Connect 的详细概述，请参阅 App Store Connect 指南。

每个 macOS 应用程序都与一个 Bundle ID 关联， Bundle ID 是在 Apple 注册的唯一标识。要为应用程序注册 Bundle ID，请执行以下步骤：

1. 打开开发者帐户的 App IDs 页面。

2. 点击 + 创建一个新的 Bundle ID。

3. 输入应用程序名称，选择 显式 App ID，然后输入 ID。

4. 选择应用程序使用的服务，然后点击 下一步。

5. 在下一页中，确认应用的详细信息，然后点击 注册 来注册你的 Bundle ID。

在 App Store Connect 上注册你的应用程序：

1. 在浏览器中打开 App Store Connect。

2. 在 App Store Connect 登录页上，点击 我的应用程序。

3. 点击我的应用程序页面左上角的 +，然后选择 新建应用程序。

4. 在表单中填写应用程序详细信息。在平台部分，请确保选中了 macOS。由于 Flutter 目前不支持 tvOS，所以不要选中该项。点击 创建。

5. 从侧边栏中选择 应用程序信息，可以查看应用程序的详细信息。

6. 在常规信息中，选择在上一步中注册的 Bundle ID。

更详细的介绍，请参阅 将应用程序添加到你的帐户]

这一步包括检查 Xcode 工作区中最重要的设置。更详细的过程和说明，请参阅 准备应用程序分发。

在 Xcode 中配置目标：

1. 在 Xcode 中，打开应用程序 macos 文件夹中的 Runner.xcworkspace。

2. 要查看应用程序的设置，请在 Xcode 导航栏中选择 Runner 项目。然后，在主视图侧栏中，选择 Runner 目标。

3. 选择 General（常规） 选项。

确认最重要的设置。

在 Identity（标识） 部分：

App Category（应用类别）
你的应用将出现在 Mac App Store 中的哪个类别，此项不能为空。

Bundle Identifier
你在 App Store Connect 注册的应用程序 ID。

在 Deployment info（部署信息） 部分：

Deployment Target（部署目标）
应用程序支持的最低 macOS 版本。Flutter 支持 macOS 10.14 及更高版本。

在 Signing & Capabilities（签名和功能） 部分：

Automatically manage signing（自动管理签名）
Xcode 是否自动管理应用程序签名和配置。默认为 true，这对于大多数应用程序来说应该足够。更复杂的场景，请参阅 代码签名指南。

Team（团队）
选择与你注册的 Apple 开发者帐户关联的团队。如果需要，请选择 Add Account...（添加账户...），然后更新此设置。

项目设置的 General（常规） 选项应类似于以下内容：

有关应用程序签名的详细概述，请参阅 创建、导出和删除签名证书。

引用标识的配置集中在 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。

版本号和内部版本号都可以在 Flutter 构建时，通过指定 --build name 和 --build number 进行覆盖。

在 macOS 中，build-name 使用 CFBundleShortVersionString，而 build-number 使用 CFBundleVersion。在苹果开发者的网站上，查看更多关于 iOS 版本的 Core Foundation Keys 。

创建一个新的 Flutter 应用程序时，会创建一个占位图标集。此步骤包含如何用应用程序的图标替换这些占位图标：

1. 查看 macOS 应用程序图标 指南。

2. 在 Xcode 项目导航栏的 Runner 文件夹中选择 Assets.xcassets。用你自己的应用程序图标更新占位图标。

3. 使用 flutter run -d macos 运行应用程序，验证图标是否已被替换。

此步骤包含创建构建存档并将其上传到 App Store Connect。

在开发时，你已经完成了在 debug 模式下的应用构建、调试和测试。当你准备好在 App Store 或 TestFlight 上向用户发布应用时，你需要准备一个 release 版产物。此时，你可以考虑 混淆你的 Dart 代码 让逆向工程变得更加困难。混淆你的代码需要向构建命令添加两个标志。

在 Xcode 中，配置应用程序版本和内部版本：

1. 打开 macos 文件夹中的 Runner.xcworkspace 工程项目，若要在命令行中这样做就切换到工程的文件夹下运行下面的命令:

   open macos/Runner.xcworkspace

2. 在 Xcode 项目导航栏中选择 Runner，然后在设置侧栏中选择 Runner 目标。

3. 在标识部分，将 Version（版本） 更新为要发布的版本号。

4. 在标识部分，将 Build identifier（构建标识） 更新为在 App Store Connect 上可以跟踪此生成的唯一生成串。每次上传都需要一个唯一的构建标识。

最后，创建一个构建归档并将其上传到 App Store Connect：

1. 为你的应用创建一个发布归档，命令行切换到你的工程目录，运行下面的命令：

   flutter build macos

2. 打开 Xcode 并选择 Product > Archive，打开上个步骤生成的归档文件；

3. 点击 Validate App 按钮。如果报告了任何问题，请尝试解决并再次构建。在上传归档之前，可以重用相同的构建 ID。

4. 成功验证归档后，点击 Distribute App。你可以在 App Store Connect 上的应用程序详细信息页的活动标签下查看构建状态。

你应该会在 30 分钟内收到一封邮件。告知你的构建已经过验证，可以在 TestFlight 上发布给测试人员。此时，你可以选择在 TestFlight 上发布，或者继续将应用程序发布到应用程序商店。

更多详细信息，请参阅 将应用程序上传到 App Store Connect。

下面的步骤，我们会介绍在 Flutter 应用的工程目录下执行 Flutter 构建命令和 Codemagic 命令行工具，创建一个构建归档并将其上传至 App Store Connect。

1. 安装 Codemagic 命令行工具：

   bash

   pip3 install codemagic-cli-tools

2. 你需要生成一个具有 App Manager 访问权限的 App Store Connect API 密钥，以方便对 App Store Connect 进行自动化操作。为了使后续的命令更简洁，请设置下面的环境变量：发行者 ID、密钥 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. 你需要导出或者创建 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 ""

   之后，你可以让命令行工具自动创建新的 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 create-certificate \
       --type MAC_INSTALLER_DISTRIBUTION \
       --certificate-key=@file:/path/to/cert_key \
       --save

   使用你之前创建的私钥的 cert_key。

6. 获取 Mac 安装程序分发证书：

   bash

   app-store-connect list-certificates \
       --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. 选择需要发布给测试人员的构建版本，点击 保存。

4. 添加测试人员的电子邮件。你可以在 Users and Roles 配置测试人员，该选项在页面顶部的下拉菜单中。

请参阅 分发指南，准备一个归档文件，以便分发到指定的 Mac 设备。

当你准备向全世界发布应用程序时，请按照以下步骤提交应用程序以供审阅并发布到应用程序商店：

1. 在 App Store Connect 应用程序详情页的侧栏中选择 定价和可用性，并完善相关信息。

2. 从侧边栏中选择状态。如果这是应用程序的第一个版本，则其状态为 1.0 准备提交。填写所有必填字段。

3. 点击 提交审核。

苹果会在你的应用程序审核完成后通知你。应用程序是按照你在 版本发布 说明中发布的。

更多详细信息，请参阅 通过应用程序商店分发应用程序.

分发你的应用程序 指南详细概述了将应用程序发布到应用商店的过程。

请查看按步骤实施的 macOS 打包指南 来了解如何在不使用 Apple 付费开发者账户的情况下，以开源的方式打包和发布适用于 macOS 的 Flutter 桌面应用。