本指南分步讲解了如何将 Flutter 应用发布到 App StoreTestFlight

准备工作

#

构建和发布你的应用需要 Xcode。你需要使用运行 macOS 的设备来遵循本指南。

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

要将你的应用发布到 App Store,你必须首先注册Apple Developer Program。你可以在 Apple 的选择会员资格指南中了解更多关于各种会员选项的信息。

视频概览

#

对于喜欢视频而非文本的用户,以下视频涵盖了本指南中的相同内容。

在新标签页中观看 YouTube 视频:“7 步发布用 Flutter 构建的 iOS 应用”

在 App Store Connect 上注册应用

#

App Store Connect(以前称为 iTunes Connect)上管理你的应用生命周期。你可以在这里定义应用名称和描述、添加截图、设置价格以及管理向 App Store 和 TestFlight 的发布。

注册你的应用涉及两个步骤:注册一个唯一的 Bundle ID,并在 App Store Connect 上创建一个应用记录。

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

注册 Bundle ID

#

每个 iOS 应用都关联一个 Bundle ID,这是一个在 Apple 注册的唯一标识符。要为你的应用注册 Bundle ID,请遵循以下步骤:

  1. 打开你的开发者账户的App ID页面。
  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 登录页面上,点击 我的应用
  3. 在“我的应用”页面左上角点击 +,然后选择 新应用
  4. 填写出现的表单中的应用详细信息。在“平台”部分,确保选中“iOS”。由于 Flutter 目前不支持 tvOS,请不要勾选该复选框。点击 创建
  5. 导航到你的应用的应用程序详细信息页面,并从侧边栏中选择 应用信息
  6. 在“通用信息”部分,选择你在上一步中注册的 Bundle ID。

有关详细概述,请参阅将应用添加到你的账户

审查 Xcode 项目设置

#

此步骤涵盖审查 Xcode 工作区中最重要的设置。有关详细过程和描述,请参阅准备应用分发

导航到 Xcode 中目标设置

  1. 从你的 Flutter 项目目录中的终端窗口运行 open ios/Runner.xcworkspace,打开项目中的默认 Xcode 工作区。
  2. 要查看你的应用设置,请在 Xcode 导航器中选择 Runner 目标。

验证最重要的设置。

通用 选项卡的 Identity(身份)部分

显示名称
你的应用的显示名称。
Bundle 标识符
你在 App Store Connect 上注册的 App ID。

签名与能力 选项卡中

自动管理签名
Xcode 是否应自动管理应用签名和配置。此项默认设置为 true,这对于大多数应用来说已经足够。对于更复杂的场景,请参阅代码签名指南
团队
选择与你注册的 Apple 开发者账户关联的团队。如果需要,选择 添加账户…,然后更新此设置。

构建设置 选项卡的 部署 部分

iOS 部署目标
你的应用支持的最低 iOS 版本。Flutter 支持 iOS 12 及更高版本。如果你的应用或插件包含使用 iOS 12 更新的 API 的 Objective-C 或 Swift 代码,请将此设置更新为所需的最高版本。

你的项目设置的 通用 选项卡应类似于下图

Xcode Project Settings

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

更新应用的部署版本

#

如果你在 Xcode 项目中更改了 Deployment Target,请在 Flutter 应用中打开 ios/Flutter/AppframeworkInfo.plist 并更新 MinimumOSVersion 值以匹配。

添加应用图标

#

创建新的 Flutter 应用时,会创建一个占位图标集。此步骤涵盖将这些占位图标替换为你的应用图标:

  1. 查阅iOS 应用图标指南,特别是关于为你的应用创建浅色、深色和着色图标的建议。
  2. 在 Xcode 项目导航器中,选择 Runner 文件夹中的 Assets.xcassets。将占位图标替换为你的应用图标。
  3. 通过运行 flutter run 验证图标是否已替换。

添加启动画面

#

与应用图标类似,你也可以替换占位启动画面:

  1. 在 Xcode 项目导航器中,选择 Runner 文件夹中的 Assets.xcassets。将占位启动画面替换为你的启动画面。
  2. 通过热重启你的应用来验证新的启动画面。(不要使用 热重载。)

创建构建归档并上传到 App Store Connect

#

在开发过程中,你一直在使用 调试 构建进行构建、调试和测试。当你准备好将应用发布给 App Store 或 TestFlight 上的用户时,你需要准备一个 发布 构建。

更新应用的构建和版本号

#

应用的默认版本号是 1.0.0。要更新它,请导航到 pubspec.yaml 文件并更新以下行:

yaml
version: 1.0.0+1

版本号由三个数字组成,由点分隔,例如上面示例中的 1.0.0,后面跟着一个可选的构建号,例如上面示例中的 1,由 + 分隔。

版本和构建号都可以通过在 flutter build ipa 中分别指定 --build-name--build-number 来覆盖。

在 iOS 中,build-name 使用 CFBundleShortVersionString,而 build-number 使用 CFBundleVersion。有关 iOS 版本控制的更多信息,请参阅 Apple Developer 网站上的Core Foundation Keys

你也可以在 Xcode 中覆盖 pubspec.yaml 的构建名称和构建号:

  1. 打开应用 ios 文件夹中的 Runner.xcworkspace
  2. 在 Xcode 项目导航器中选择 Runner,然后在设置视图侧边栏中选择 Runner 目标。
  3. 在“Identity”(身份)部分,将 版本 更新为你希望发布的面向用户的版本号。
  4. 在“Identity”(身份)部分,将 构建 标识符更新为用于在 App Store Connect 上跟踪此构建的唯一构建号。每次上传都需要一个唯一的构建号。

创建应用包

#

运行 flutter build ipa 会在项目的 build/ios/archive/ 目录中生成一个 Xcode 构建归档(.xcarchive 文件),并在 build/ios/ipa 中生成一个 App Store 应用包(.ipa 文件)。

考虑添加 --obfuscate--split-debug-info 标志来混淆你的 Dart 代码,使其更难以逆向工程。

如果你不分发到 App Store,你可以选择通过添加 --export-method ad-hoc--export-method development--export-method enterprise 选项来选择不同的导出方法

将应用包上传到 App Store Connect

#

创建应用包后,可以通过以下任一方式将其上传到App Store Connect

  1. 安装并打开Apple Transporter macOS 应用。将 build/ios/ipa/*.ipa 应用包拖放到应用中。

  2. 或者通过命令行运行以下命令上传应用包:

    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

    点击 验证应用 按钮。如果报告了任何问题,请解决它们并生成另一个构建。在上传归档之前,你可以重用相同的构建 ID。

    归档成功验证后,点击 分发应用

你可以在App Store Connect上你的应用详情页面的“活动”选项卡中跟踪构建状态。你将在 30 分钟内收到一封电子邮件,通知你构建已验证,并可发布给 TestFlight 上的测试人员。此时你可以选择是在 TestFlight 上发布,还是直接将应用发布到 App Store。

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

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

#

此步骤涵盖了如何使用 Flutter 构建命令和在 Flutter 项目目录的终端中执行的Codemagic CLI 工具来创建构建存档并将其上传到 App Store Connect。这允许你在一个与你的登录钥匙串隔离的临时钥匙串中,以完全控制分发证书的方式创建构建存档。

  1. 安装 Codemagic CLI 工具

    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. 你需要导出或创建 iOS 分发证书以对构建归档进行代码签名和打包。

    如果你有现有证书,可以通过为每个证书执行以下命令来导出私钥:

    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 工具自动从私钥创建新的 iOS 分发证书。

  4. 设置一个新的临时钥匙串用于代码签名

    bash
    keychain initialize
  5. 从 App Store Connect 获取代码签名文件

    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 分发证书私钥,或会自动生成新证书的新私钥。如果 App Store Connect 中不存在该证书,则会从私钥创建该证书。

  6. 现在将获取到的证书添加到你的钥匙串中

    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.plistxcode-project use-profiles 命令的输出。

  11. 将应用发布到 App Store Connect

    bash
    app-store-connect publish \
        --path $(find $(pwd) -name "*.ipa")
  12. 如前所述,别忘了将你的登录钥匙串设置为默认,以避免与你机器上的应用发生认证问题。

    bash
    keychain use-login

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

在 TestFlight 上发布应用

#

TestFlight 允许开发者将他们的应用推送到内部和外部测试人员。这个可选步骤涵盖了在 TestFlight 上发布你的构建。

  1. 导航到App Store Connect上你的应用详情页面的“TestFlight”选项卡。
  2. 在侧边栏中选择 内部测试
  3. 选择要发布给测试人员的构建,然后点击 保存
  4. 添加任何内部测试人员的电子邮件地址。你可以在 App Store Connect 的 用户和角色 页面(从页面顶部的下拉菜单中可访问)添加其他内部用户。

有关更多详细信息,请参阅使用 TestFlight 分发应用

将应用发布到 App Store

#

当你准备好向全球发布你的应用时,请按照以下步骤提交你的应用进行审核并发布到 App Store:

  1. App Store Connect上你的应用详情页面侧边栏中选择 价格与供货情况,并填写所需信息。
  2. 从侧边栏中选择状态。如果这是此应用的首次发布,其状态为 1.0 准备提交。填写所有必填字段。
  3. 点击 提交以供审核

Apple 会在应用审核流程完成后通知你。你的应用将根据你在 版本发布 部分中指定的指示进行发布。

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

故障排除

#

分发你的应用指南详细概述了发布应用到 App Store 的过程。