跳到主内容

构建并发布 macOS 应用

如何将 Flutter 应用发布到 macOS App Store。

本指南提供了将 Flutter 应用发布到 App Store 的分步操作说明。

准备工作

#

在开始应用发布流程之前，请确保应用符合苹果的 App 审核指南。

要将应用发布到 App Store，必须首先注册加入 Apple Developer Program。您可以阅读苹果的 选择会员资格 指南，了解有关不同会员选项的更多信息。

在 App Store Connect 上注册应用

#

通过 App Store Connect（前身为 iTunes Connect）管理应用的生命周期。您可以在此处定义应用名称和描述、添加屏幕截图、设置价格，以及管理发布到 App Store 和 TestFlight 的版本。

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

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

注册 Bundle ID

#

每个 macOS 应用都关联一个 Bundle ID，这是在苹果注册的唯一标识符。要为应用注册 Bundle ID，请按照以下步骤操作：

  1. 打开开发者帐户的 App IDs 页面。
  2. 点击 + 以创建新的 Bundle ID。
  3. 输入应用名称，选择 Explicit App ID，然后输入一个 ID。
  4. 选择应用使用的服务，然后点击 Continue。
  5. 在下一页上，确认详细信息并点击 Register 以注册 Bundle ID。

在 App Store Connect 上创建应用记录

#

在 App Store Connect 上注册应用

  1. 在浏览器中打开 App Store Connect。
  2. 在 App Store Connect 登录页面上，点击 My Apps。
  3. 点击“My Apps”页面左上角的 +，然后选择 New App。
  4. 在出现的表单中填写应用详细信息。在“Platforms”部分，确保选中 macOS。由于 Flutter 目前不支持 tvOS，请取消勾选该项。点击 Create。
  5. 导航至应用的详细信息页面，并从侧边栏中选择 App Information。
  6. 在“General Information”部分，选择您在上一步中注册的 Bundle ID。

有关详细概述，请参阅 将应用添加到您的帐户。

检查 Xcode 项目设置

#

此步骤涵盖检查 Xcode 工作区中最重要的设置。有关详细流程和说明，请参阅 准备应用分发。

在 Xcode 中导航至您的目标设置 (Target settings)

  1. 在 Xcode 中，打开应用 macos 文件夹下的 Runner.xcworkspace。
  2. 要查看应用设置，请在 Xcode 项目导航器中选择 Runner 项目。然后，在主视图侧边栏中，选择 Runner target。
  3. 选择 General 选项卡。

验证最重要的设置。

在 Identity 部分

App Category (应用类别)

您的应用在 Mac App Store 中展示的所属类别。不能设为“无”。

Bundle Identifier

您在 App Store Connect 上注册的 App ID。

在 Deployment info 部分

Deployment Target (部署目标)

您的应用支持的最低 macOS 版本。要检查 Flutter 支持部署的 macOS 版本，请查看 Flutter 的 支持的部署平台。

在 Signing & Capabilities 部分

Automatically manage signing (自动管理签名)

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

Team

选择与您已注册的 Apple Developer 帐户关联的团队。如有必要，选择 Add Account...，然后更新此设置。

项目设置的 General 选项卡应如下所示：

Xcode Project Settings

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

#

产品标识符的配置集中在 macos/Runner/Configs/AppInfo.xcconfig 中。对于应用名称，设置 PRODUCT_NAME；对于版权，设置 PRODUCT_COPYRIGHT；最后，设置 PRODUCT_BUNDLE_IDENTIFIER 以指定应用的 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。在苹果开发者网站的 Core Foundation Keys 中阅读更多关于 iOS 版本控制的信息。

添加应用图标

#

创建新的 Flutter 应用时，会生成一套占位符图标。此步骤涵盖如何使用您自己的应用图标替换这些占位符图标。

  1. 请查阅 macOS 应用图标 指南。
  2. 在 Xcode 项目导航器中，选择 Runner 文件夹下的 Assets.xcassets。使用您自己的应用图标更新占位符图标。
  3. 通过运行 flutter run -d macos 来运行您的应用，以验证图标是否已成功替换。

使用 Xcode 创建构建归档 (Build Archive)

#

此步骤涵盖使用 Xcode 创建构建归档并上传到 App Store Connect。

在开发过程中，您一直使用 debug 构建进行构建、调试和测试。当您准备好将应用分发给 App Store 或 TestFlight 上的用户时，需要准备一个 release 构建。此时，您可以考虑 混淆您的 Dart 代码，以增加反向工程的难度。混淆代码需要在构建命令中添加几个标志。

在 Xcode 中配置应用版本和构建号

  1. 打开应用 macos 文件夹下的 Runner.xcworkspace。要通过命令行执行此操作，请在应用项目的根目录下运行以下命令。
    open macos/Runner.xcworkspace
  • 在 Xcode 项目导航器中选择 Runner，然后在设置视图侧边栏中选择 Runner target。
  • 在“Identity”部分，将 Version 更新为您希望发布的面向用户的版本号。
  • 在“Identity”部分，将 Build 标识符更新为用于在 App Store Connect 上跟踪此构建的唯一构建号。每次上传都需要一个唯一的构建号。

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

    1. 创建应用程序的发布归档 (Archive)。在应用项目的根目录下，运行以下命令。
      flutter build macos
  • 打开 Xcode 并选择 Product > Archive 以打开上一步创建的归档。
  • 点击 Validate App 按钮。如果报告了任何问题，请解决它们并重新构建。在上传归档之前，您可以重复使用相同的构建 ID。
  • 归档验证成功后，点击 Distribute App。您可以在 App Store Connect 上应用详情页的“Activities”选项卡中跟踪构建状态。

    您应该会在 30 分钟内收到一封电子邮件，通知您构建已通过验证，并可在 TestFlight 上向测试人员发布。此时，您可以选择是在 TestFlight 上发布，还是直接将应用发布到 App Store。

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

    使用 Codemagic CLI 工具创建构建归档

    #

    此步骤涵盖使用 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 文件。

      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. 设置一个新的临时钥匙串 (keychain) 以用于代码签名

      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. 选择要发布给测试人员的构建版本，然后点击 Save。
    4. 添加任何内部测试人员的电子邮件地址。您可以在 App Store Connect 的 Users and Roles 页面中添加更多内部用户，该页面可从页面顶部的下拉菜单中访问。

    分发到已注册的设备

    #

    请参阅 分发指南 以准备用于分发到指定 Mac 计算机的归档。

    将应用发布到 App Store

    #

    当您准备好将应用发布给全世界时，请按照以下步骤提交应用以供审核并发布到 App Store：

    1. 在 App Store Connect 上应用详情页的侧边栏中选择 Pricing and Availability，并填写所需信息。
    2. 从侧边栏中选择状态。如果是该应用的首次发布，其状态为 1.0 Prepare for Submission。填写所有必填字段。
    3. 点击 Submit for Review。

    苹果会在其应用审核流程完成后通知您。您的应用将按照您在 Version Release 部分中指定的说明进行发布。

    有关更多详细信息，请参阅 通过 App Store 分发应用。

    故障排除

    #

    分发您的应用 指南提供了将应用发布到 App Store 过程的详细概览。

    额外资源

    #

    要了解如何以开源方式打包和分发 Flutter 桌面应用到 macOS（无需支付 Apple 开发者帐户费用），请查看此分步 macOS 打包指南。

    除非另有说明，本网站上的文档反映了 Flutter 3.41.5 版本。页面最后更新于 2026-05-05。 查看源代码 或 报告问题。