构建和发布为 macOS 应用

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

预备工作

#

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

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

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

#

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

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

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

注册 Bundle ID

#

每个 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 上创建应用程序记录

#

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

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

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

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

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

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

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

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

检查 Xcode 项目设置

#

这一步包括检查 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 (Mojave) 及更高版本。

Signing & Capabilities(签名和功能) 部分:

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

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

项目设置的 General(常规) 选项应类似于以下内容:

Xcode Project Settings

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

#

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

使用 Codemagic 命令行工具创建一个构建归档

#

下面的步骤,我们会介绍在 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 certificates create \
        --type MAC_INSTALLER_DISTRIBUTION \
        --certificate-key=@file:/path/to/cert_key \
        --save

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

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

    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 允许开发者将其应用推送给内部和外部的测试人员。以下步骤将指导你如何将你的应用在 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 桌面应用。