构建和发布为 iOS 应用

这个教程将为你提供关于如何将 Flutter App 发布到 App StoreTestFlight 的说明。

预先准备

构建和发布一个 macOS 应用需要使用 Xcode,你必须要有一个运行着 macOS 系统的设备来学习本指南文档。

在开始发布你的 app 的进程之前,确保你已经看过了 Apple 的 App Store 审核指南

想要发布你的 app 到 App Store,你需要注册 Apple Developer Program。你可以在苹果的 选择会员资格(开发者类型) 中查看到关于多种不同会员类型的选择。

在 App Store Connect 上注册你的 App

App Store Connect (曾经的 iTunes Connet)是你将会管理应用生命周期的地方。你将会定义应用的名称和描述以及截图,设置价格,并管理发布到 App Store 和 Testflight。

注册你的 app 需要两步:登记唯一的套装 ID(Bundle ID),并在你的 App Store Connect 中创建一个 app。

关于更多 App Store Connect 的细节,查看 App Store Connect 指南。

登记套装 ID

每一个 iOS 应用都与一个在 Apple 登记的唯一的套装 ID 关联。要为你的应用登记一个套装 ID,请参考下面的步骤:

  1. 在你的开发者账号页面打开 App IDs 页面。

  2. 点击 + 来创建一个新的套装 ID。

  3. 输入一个 App 名称,选择 Explicit App ID,然后输入一个 ID。

  4. 选择你的 App 将要使用的服务,然后点击 继续

  5. 在下一页,确认细节并点击 注册 来注册你的 Bundle ID。

在 App Store Connect 创建一个应用记录

在 App Store Connect 中注册你的应用:

接下来,你需要在 App Store Connect 注册你的应用:

  1. 在你的浏览器里打开 App Store Connect

  2. 在 App Store Connect 的落地页,点击 My Apps

  3. 在我的 app 页面的顶部左侧,点击 + ,然后选择 New App

  4. 在出现的表单中填写你的 app 细节。在平台部分,确保 iOS 被选中。由于 Flutter 暂时不支持 tvOS,保持该选项为未选。点击 Create

  5. 跳转到你的应用详情,然后从侧边栏选择 App Information

  6. 在基础信息部分,选择你在前一步注册的套装 ID。

想要获取更多信息,可以看这个帮助页面 添加 App 至您的帐户

检查 Xcode 项目设置

在这一步,你需要在 Xcode 工作空间检查绝大多数重要设置。关于更多的步骤和描述,查看 为 App 分发做准备

在 Xcode 中跳转到你的目标设置:

  1. 在 Flutter 工程目录下运行命令 open ios/Runner.xcworkspace 打开默认的 Xcode workspace。

  2. 想要看你的 app 设置,在 Xcode 的项目导航栏中选择 Runner

接下来,你需要验证最重要的配置:

选择 General 标签页,在 Identity 部分:

Display Name
应用的名字。

Bundle Identifier
在 App Store Connect 注册的 App ID。

Signing & Capabilities 部分:

Automatically manage signing
是否需要 Xcode 自动管理 app 签名和设置。这个默认被设置为 true ,对于绝大多数 App 来说都是适用的。对于更复杂的场景,查看 代码签名指南

Team
选择关联到你注册的 Apple 开发者账户的团队。如果需要,选择 Add Account…, 然后更新选项。

Build Settings 标签页的 Deployment 部分:

iOS Deployment Target
设定你的应用可以支持到的最低的 iOS 版本。 Flutter 支持 iOS 11 及其之后的版本,如果你的应用包含了 iOS 11 不支持的 Objective-C 或 Swift 代码,请将这里一并设置为相应所需的最高版本。

你项目的 General 标签页应该看起来像是这样的:

Xcode Project Settings

更多关于 App 签名新的介绍,查看文档 创建, 导出, 和删除签名证书

更新应用的开发版本

如果你在 Xcode 工程里更改了 Deployment Target,你需要打开 Flutter app 的 ios/Flutter/AppframeworkInfo.plist 文件并修改 MinimumOSVersion 值与之匹配。

添加应用图标

当你创建一个新的 Flutter 应用时,则会创建一个默认的图标。在这一步,你将使用你自己的图标替换占位图标:

  1. 回顾 iOS 的 App Icon 指南。

  2. 在 Xcode 项目导航栏,选择 Runner 目录中的 Assets.xcassets,更新占位图标为你自己的 app 的图标。

  3. 通过执行 flutter run 来验证你的图标是否已经被替换。

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

在开发过程中,你将会使用 debug 模式来完成构建、调试并测试。当你准备好通过 App Store 或 TestFlight 交付你的 app 给用户时,你需要准备一个 release 构建。

更新应用的构建编号和版本号

默认应用的版本号是 1.0.0,如果需要更新这个版本号,到 pubspec.yaml 文件中更新下面这一行:

version: 1.0.0+1

版本号是由三个数字并用半角句号 (点) 隔开的,比如上面显示的 1.0.0。后面是一个可选的构建编号,比如这个例子中使用 + 隔开的数字 1

构建名称和构建编号都可以通过在执行命令 flutter build ipa 的时候通过 --build-name--build-number 覆盖设定。

在 iOS 中,build-name 对应 CFBundleShortVersionStringbuild-number 对应着 CFBundleVersion。了解更多关于 iOS 中的版本信息,请在 Apple 开发者文档网站查看 Core Foundation Keys 文档。

在 Xcode 中这样设定,也可以覆盖 pubspec.yaml 中的构建名称和构建编号:

  1. ios 文件夹中打开 Runner.xcworkspace

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

  3. 在 Identity 部分,更新 Version 为你想要发布的用户可见的版本号。

  4. 在 Identity 部分,更新 Build 标示为一个唯一的 Build 数字,用来在 App Store Connect 上追踪,每一个上传都需要一个独立的 Build 数字。

创建一个应用套装 (app bundle)

运行命令行 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. 安装并打开 Transporter macOS 应用,将 build/ios/ipa/*.ipa 下的应用套装拖入 Transporter 应用中。

  2. 也可以在命令行执行下面的命令将应用套装上传:

    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

    点击 Validate App 按钮。如果报告了任何问题,记录下他们并重新开始一个新的构建。在你上传一个归档前,可以一直使用同一个 Build ID。

    当这个归档校验成功以后,点击 Distribute App

你可以在 App Store Connect 中应用详情页面的 Activities 标签页查看你的构建状态。

当你的构建已经通过了校验,可以将你的构建通过 TestFlight 发布给你的测试人员或直接将其发布到 App Store 的时候,你会在 30 分钟内收到一封信来提醒你。

更多内容可参考 上传 App 到 App Store Connect

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

该步骤包含了在 Flutter 项目的目录下,通过终端使用 Flutter 构建命令和 Codemagic 命令行工具,构建归档并上传至 App Store 的教程。该操作可以让你完全控制分发证书和临时钥匙串,将它们与登录的进行隔离。

  1. 安装 Codemagic 命令行工具:

    pip3 install codemagic-cli-tools
    
  2. 你需要使用包含 App 管理权限的 App Store Connect 账号,生成一个 App Store Connect API Key。为了使后续的命令更加简洁,你可以在环境变量中配置这些内容: issuer id、key id 以及 API key 文件。

    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 分发证书,用来签名及归档构建。

    如果你已经有可用的 证书,你可以使用以下命令导出私钥:

    openssl pkcs12 -in <certificate_name>.p12 -nodes -nocerts | openssl rsa -out cert_key
    

    你也可以使用以下命令创建新的私钥:

    ssh-keygen -t rsa -b 2048 -m PEM -f cert_key -q -N ""
    

    之后你便可以用命令行工具基于这个私钥创建新的 iOS 分发构建了。

  4. 配置一个用于签名的临时钥匙串:

    keychain initialize
    
  5. 从 App Store Connect 上获取签名文件:

    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. 将获取到的证书添加到你的钥匙串中:

    keychain add-certificates
    
  7. 更新 Xcode 项目设定,使用获取到的签名配置:

    xcode-project use-profiles
    
  8. 获取 Flutter 依赖:

    flutter packages pub get
    
  9. 获取 CocoaPods 依赖:

    find . -name "Podfile" -execdir pod install \;
    
  10. 构建 Flutter 的 iOS 项目:

    flutter build ipa --release \
        --export-options-plist=$HOME/export_options.plist
    

    注意 export_options.plist 路径来源于 xcode-project use-profiles 命令的输出。

  11. 将应用发布到 App Store Connect:

    app-store-connect publish \
        --path $(find $(pwd) -name "*.ipa")
    
  12. 如前文所示,记得将你的登录钥匙串设置为默认,避免设备出现认证问题:

    keychain use-login
    

在 30 分钟内,你会收到一封邮件,提醒你构建已验证,可以在 TestFlight 上发布。这时你可以选择在 TestFlight 上发布,或是直接在 App Store 上发布。

在 TestFlight 发布你的应用

TestFlight allows developers to push their apps to internal and external testers. This optional step covers releasing your build on TestFlight.

  1. App Store Connect中,你的应用的详情页面跳转到 TestFlight Tab。

  2. 在侧边栏选择 Internal Testing

  3. 选择要发布给测试人员的构建,然后点击 保存

  4. 为每一个内部测试人员添加邮件。你可以在 App Store Connect 的 用户与角色 页面添加额外的内部用户,他们将会出现在页面顶部的下拉菜单中。

关于更多信息,请查看 使用 TestFlight 分发应用 (Distribute an app using TestFlight (iOS, tvOS, watchOS))

在 App Store 发布你的应用

当你准备发布你的 app 到这个世界时,跟随下面的步骤,来提交你的 App 去审核,并将其发布到 App Store。

  1. 从你的 app 在 App Store Connect 的页面中的侧边栏中选择 Pricing and Availability,然后完善所有的必填信息。

  2. 从侧边栏选择状态。如果这是第一次发布这个 App,这个状态将会是 1.0 Prepare for Submission,填写所有需要填写的区域。

  3. 点击 提交审核

Apple 将会在他们的审核过程结束后提醒你。你的 app 将会根据 Version Release 部分的介绍进行发布。

关于更多细节,查看 通过 App Store 分发一个 App.

故障排除

分发你的应用 指南,提供了详细的发布应用到 App Store 过程的内容。