构建并发布 macOS 应用
本指南将分步介绍如何将 Flutter 应用发布到 App Store。
准备工作
#在开始发布应用之前,请确保您的应用符合 Apple 的 App Review Guidelines。
要将应用发布到 App Store,您必须先注册 Apple Developer Program。您可以在 Apple 的 Choosing a Membership 指南中详细了解各种会员选项。
在 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 相关联,这是一个在 Apple 注册的唯一标识符。要为您的应用注册 Bundle ID,请按照以下步骤操作
- 打开开发者账户的 App IDs 页面。
- 点击 + 以创建新的 Bundle ID。
- 输入应用名称,选择 Explicit App ID,然后输入 ID。
- 选择您的应用使用的服务,然后点击 Continue。
- 在下一页,确认详细信息,然后点击 Register 注册您的 Bundle ID。
在 App Store Connect 上创建应用记录
#在 App Store Connect 上注册您的应用
- 在浏览器中打开 App Store Connect。
- 在 App Store Connect 登录页面,点击 My Apps。
- 在“我的应用”页面的左上角点击 +,然后选择 New App。
- 在出现的表单中填写您的应用详细信息。在 Platforms 部分,确保勾选了 macOS。由于 Flutter 目前不支持 tvOS,请将该复选框留空。点击 Create。
- 导航到您应用的应用程序详细信息,然后从侧边栏选择 App Information。
- 在 General Information 部分,选择您在上一步中注册的 Bundle ID。
有关详细概述,请参阅 Add an app to your account。
检查 Xcode 项目设置
#此步骤涵盖了检查 Xcode 工作空间中最重要的设置。有关详细程序和说明,请参阅 Prepare for app distribution。
导航到 Xcode 中的目标设置
- 在 Xcode 中,打开您应用
macos
文件夹中的Runner.xcworkspace
。 - 要查看应用的设置,请在 Xcode 项目导航器中选择 Runner 项目。然后在主视图侧边栏中,选择 Runner 目标。
- 选择 General 标签页。
验证最重要的设置。
在 Identity 部分
App Category
- 您的应用将在 Mac App Store 上列出的应用类别。此项不能为空。
Bundle Identifier
- 您在 App Store Connect 上注册的 App ID。
在 Deployment info 部分
Deployment Target
- 您的应用支持的最低 macOS 版本。要检查 Flutter 支持部署到哪些 macOS 版本,请查阅 Flutter 的 Supported deployment platforms。
在 Signing & Capabilities 部分
Automatically manage signing
- Xcode 是否自动管理应用签名和配置。默认设置为
true
,这对于大多数应用来说应该足够了。对于更复杂的情况,请参阅 Code Signing Guide。 Team
- 选择与您注册的 Apple Developer 账户相关联的团队。如果需要,选择 Add Account...,然后更新此设置。
您的项目设置的 General 标签页应如下所示
有关应用签名的详细概述,请参阅 Create, export, and delete signing certificates。
配置应用的名称、Bundle ID 和版权信息
#产品标识符的配置集中在 macos/Runner/Configs/AppInfo.xcconfig
文件中。对于应用名称,设置 PRODUCT_NAME
;对于版权,设置 PRODUCT_COPYRIGHT
;最后,为应用的 Bundle ID 设置 PRODUCT_BUNDLE_IDENTIFIER
。
更新应用的 SwiftUI 版本号
#应用的默认版本号是 1.0.0
。要更新它,请导航到 pubspec.yaml
文件并更新以下行:
version: 1.0.0+1
版本号是由点分隔的三个数字,例如上面示例中的 1.0.0
,后面可以跟一个可选的构建号,例如上面示例中的 1
,用 +
分隔。
通过指定 --build-name
和 --build-number
,可以分别覆盖 Flutter 构建中的版本号和构建号。
在 macOS 中,build-name
使用 CFBundleShortVersionString
,而 build-number
使用 CFBundleVersion
。有关 iOS 版本控制的更多信息,请参阅 Apple Developer 网站上的 Core Foundation Keys。
添加应用图标
#当创建一个新的 Flutter 应用时,会创建一个占位符图标集。此步骤涵盖了用您应用的图标替换这些占位符图标
- 查看 macOS App Icon 指南。
- 在 Xcode 项目导航器中,选择
Runner
文件夹中的Assets.xcassets
。用您自己的应用图标更新占位符图标。 - 通过运行
flutter run -d macos
来运行您的应用,验证图标是否已替换。
使用 Xcode 创建构建归档
#此步骤涵盖了使用 Xcode 创建构建归档并将您的构建上传到 App Store Connect。
在开发过程中,您一直使用 *debug* 构建进行构建、调试和测试。当您准备将应用发布到 App Store 或 TestFlight 时,您需要准备一个 *release* 构建。此时,您可以考虑 混淆您的 Dart 代码,以增加反编译的难度。混淆代码需要为您的构建命令添加几个标志。
在 Xcode 中配置应用版本和构建
- 打开您应用
macos
文件夹中的Runner.xcworkspace
。要从命令行执行此操作,请从应用程序项目的基础目录运行以下命令。open macos/Runner.xcworkspace
- 在 Xcode 项目导航器中选择 Runner,然后在设置视图侧边栏中选择 Runner 目标。
- 在 Identity 部分,将 Version 更新为您要发布的面向用户的版本号。
- 在 Identity 部分,将 Build 标识符更新为用于在 App Store Connect 上跟踪此构建的唯一构建号。每次上传都需要唯一的构建号。
最后,创建构建归档并将其上传到 App Store Connect
- 创建应用程序的 release Archive。从应用程序项目的基础目录运行以下命令。
flutter build macos
- 打开 Xcode,选择 Product > Archive,打开上一步创建的归档。
- 点击 Validate App 按钮。如果报告了任何问题,请解决它们并生成另一个构建。您可以重复使用相同的构建 ID,直到上传归档为止。
- 成功验证归档后,点击 Distribute App。您可以在 App Store Connect 上应用详细信息页面的 Activities 标签页中跟踪您的构建状态。
您应该会在 30 分钟内收到一封电子邮件,通知您您的构建已验证,并且可以在 TestFlight 上发布给测试人员。此时,您可以选择是在 TestFlight 上发布,还是直接发布到 App Store。
有关更多详细信息,请参阅 Upload an app to App Store Connect。
使用 Codemagic CLI 工具创建构建归档
#此步骤涵盖了使用 Flutter 构建命令和在 Flutter 项目目录的终端中执行的 Codemagic CLI Tools 来创建构建归档并将您的构建上传到 App Store Connect。
安装 Codemagic CLI 工具
bashpip3 install codemagic-cli-tools
您需要生成一个具有 App Manager 访问权限的 App Store Connect API Key,以便与 App Store Connect 自动执行操作。为了使后续命令更简洁,请从新密钥设置以下环境变量:issuer id、key id 和 API key file。
bashexport 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`
您需要导出或创建 Mac App Distribution 和 Mac Installer Distribution 证书才能执行代码签名和打包构建归档。
如果您有现有的 证书,可以通过为每个证书执行以下命令来导出私钥
bashopenssl pkcs12 -in <certificate_name>.p12 -nodes -nocerts | openssl rsa -out cert_key
或者,您可以执行以下命令创建一个新的私钥
bashssh-keygen -t rsa -b 2048 -m PEM -f cert_key -q -N ""
稍后,您可以让 CLI 工具自动创建一个新的 Mac App Distribution 和 Mac Installer Distribution 证书。您可以对每个新证书使用相同的私钥。
从 App Store Connect 获取代码签名文件
bashapp-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 证书私钥,或者是自动生成新证书的新私钥。如果您没有 Mac Installer Distribution 证书,可以通过执行以下命令创建新证书
bashapp-store-connect certificates create \ --type MAC_INSTALLER_DISTRIBUTION \ --certificate-key=@file:/path/to/cert_key \ --save
使用您之前创建的私钥的
cert_key
。获取 Mac Installer Distribution 证书
bashapp-store-connect certificates list \ --type MAC_INSTALLER_DISTRIBUTION \ --certificate-key=@file:/path/to/cert_key \ --save
设置一个新的临时钥匙串用于代码签名
bashkeychain initialize
现在将获取的证书添加到您的钥匙串
bashkeychain add-certificates
更新 Xcode 项目设置以使用获取的代码签名配置文件
bashxcode-project use-profiles
安装 Flutter 依赖项
bashflutter packages pub get
安装 CocoaPods 依赖项
bashfind . -name "Podfile" -execdir pod install \;
构建 Flutter macOS 项目
bashflutter build macos --release
打包应用
bashAPP_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
将打包好的应用发布到 App Store Connect
bashapp-store-connect publish \ --path "$PACKAGE_NAME"
如前所述,不要忘记将您的登录钥匙串设置为默认值,以避免您的计算机上的应用程序出现身份验证问题。
bashkeychain use-login
在 TestFlight 上发布您的应用
#TestFlight 允许开发者将他们的应用推送到内部和外部测试人员。此可选步骤涵盖了在 TestFlight 上发布您的构建。
- 在 App Store Connect 上,导航到您应用应用程序详细信息页面的 TestFlight 标签页。
- 在侧边栏中选择 Internal Testing。
- 选择要发布给测试人员的构建,然后点击 Save。
- 添加任何内部测试人员的电子邮件地址。您可以在 App Store Connect 的 Users and Roles 页面添加其他内部用户,该页面可从页面顶部的下拉菜单中找到。
分发给注册设备
#请参阅 distribution guide,为分发到指定的 Mac 计算机准备归档。
在 App Store 上发布您的应用
#当您准备好向世界发布您的应用时,请按照以下步骤将您的应用提交审核并发布到 App Store
- 在 App Store Connect 上,从您应用应用程序详细信息页面的侧边栏中选择 Pricing and Availability,并填写必填信息。
- 从侧边栏选择状态。如果这是该应用的首次发布,则其状态为 1.0 Prepare for Submission。完成所有必填字段。
- 点击 Submit for Review。
Apple 会在应用审核流程完成后通知您。您的应用将按照您在 Version Release 部分中指定的说明发布。
有关更多详细信息,请参阅 Distribute an app through the App Store。
故障排除
#Distribute your app 指南提供了发布应用到 App Store 过程的详细概述。
额外资源
#要了解如何使用开源方式打包和分发您的 Flutter 桌面应用,而无需使用付费的 Apple 开发者账户,请查看此分步 macOS packaging guide。