构建和发布为 iOS 应用

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

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

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

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

如果你想观看视频而非文字介绍，以下这个视频会指导你如何进行准备工作。

用 Flutter 发布 iOS 应用程序，只需 7 个步骤

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

注册你的 app 需要两步：登记唯一的套装 ID（Bundle ID），并在你的 App Store Connect 中创建一个 app。

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

每一个 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 注册你的应用：

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 工作空间检查绝大多数重要设置。关于更多的步骤和描述，查看 为 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 12 及其之后的版本，如果你的应用包含了 iOS 12 不支持的 Objective-C 或 Swift 代码，请将这里一并设置为相应所需的最高版本。

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

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

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

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

1. 回顾 iOS 的 App Icon 指南，尤其是为 App 创建浅色、深色以及着色 (Tinted) icon 的建议。

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

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

与应用图标类似，你可以通过下面的方法替换占位的启动图:

1. 在 Xcode 的工程导航中选择 Runner 文件夹下的 Assets.xcassets，然后将自己的启动图替换掉占位启动图即可。

2. 重新启动你的应用来验证是否替换成功，不要使用热重载。

在开发过程中，你将会使用 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 对应 CFBundleShortVersionString、 build-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 数字。

运行命令行 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：

1. 安装并打开 Transporter macOS 应用，将 build/ios/ipa/*.ipa 下的应用套装拖入 Transporter 应用中。

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。

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

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

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

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

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

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

1. 安装 Codemagic 命令行工具：

   bash

   pip3 install codemagic-cli-tools

2. 你需要使用包含 App 管理权限的 App Store Connect 账号，生成一个 App Store Connect API Key。为了使后续的命令更加简洁，你可以在环境变量中配置这些内容： 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. 你需要导出或者创建一个 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 ""

   之后你便可以用命令行工具基于这个私钥创建新的 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.plist 路径来源于 xcode-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 上发布应用。

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

2. 在侧边栏选择 Internal Testing。

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

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

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

当你准备发布你的 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 过程的内容。

除非另有说明，本文档之所提及适用于 Flutter 的最新稳定版本，本页面最后更新时间: 2024-12-02。 查看文档源码 或者 为本页面内容提出建议。