构建并发布 macOS 应用
本指南详细介绍了将 Flutter 应用发布到 App Store 的分步过程。
准备工作
#在开始发布应用之前,请确保您的应用符合 Apple 的 App Store 审核指南。
为了将您的应用发布到 App Store,您必须首先加入 Apple Developer Program。您可以在 Apple 的“选择会员资格”指南中了解有关各种会员选项的更多信息。
在 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,请按照以下步骤操作:
- 打开开发者帐户的应用 ID 页面。
- 点击 + 以创建新的 Bundle ID。
- 输入应用名称,选择 Explicit App ID(显式应用 ID),然后输入 ID。
- 选择您的应用使用的服务,然后点击 Continue(继续)。
- 在下一页上,确认详细信息,然后点击 Register(注册)以注册您的 Bundle ID。
在 App Store Connect 上创建应用记录
#在 App Store Connect 上注册您的应用
- 在浏览器中打开 App Store Connect。
- 在 App Store Connect 登录页面上,点击 My Apps(我的应用)。
- 点击“我的应用”页面左上角的 +,然后选择 New App(新建应用)。
- 在出现的表单中填写您的应用详细信息。在“平台”部分,确保选中 macOS。由于 Flutter 目前不支持 tvOS,请取消选中该复选框。点击 Create(创建)。
- 导航到您的应用的应用详细信息,然后从侧边栏中选择 App Information(应用信息)。
- 在“通用信息”部分,选择您在上一步中注册的 Bundle ID。
有关详细概述,请参阅“将应用添加到您的帐户”。
检查 Xcode 项目设置
#此步骤涵盖了检查 Xcode 工作区中最重要的设置。有关详细的步骤和说明,请参阅“准备应用分发”。
在 Xcode 中导航到目标设置
- 在 Xcode 中,打开应用
macos
文件夹中的Runner.xcworkspace
。 - 要查看应用设置,请在 Xcode 项目导航器中选择 Runner 项目。然后,在主视图侧边栏中,选择 Runner 目标。
- 选择 General(通用)选项卡。
验证最重要的设置。
在 Identity(标识)部分
应用类别
- 您的应用将在 Mac App Store 上列出的应用类别。此项不能为空。
Bundle 标识符
- 您在 App Store Connect 上注册的应用 ID。
在 Deployment info(部署信息)部分
部署目标
- 您的应用支持的最低 macOS 版本。要查看 Flutter 支持部署到哪些 macOS 版本,请查阅 Flutter 的支持的部署平台。
在 Signing & Capabilities(签名与功能)部分
自动管理签名
- Xcode 是否应自动管理应用签名和配置。此项默认设置为
true
,这对于大多数应用来说应该足够了。对于更复杂的场景,请参阅代码签名指南。 团队
- 选择与您注册的 Apple Developer 帐户关联的团队。如果需要,请选择 Add Account...(添加帐户...),然后更新此设置。
您的项目设置的 General(通用)选项卡应如下所示:
有关应用签名的详细概述,请参阅“创建、导出和删除签名证书”。
配置应用名称、Bundle 标识符和版权
#产品标识符的配置集中在 macos/Runner/Configs/AppInfo.xcconfig
中。对于应用名称,设置 PRODUCT_NAME
;对于版权,设置 PRODUCT_COPYRIGHT
;最后,对于应用的 Bundle 标识符,设置 PRODUCT_BUNDLE_IDENTIFIER
。
更新应用版本号
#应用的默认版本号是 1.0.0
。要更新它,请导航到 pubspec.yaml
文件并更新以下行:
版本: 1.0.0+1
版本号由三个用点分隔的数字组成,例如上述示例中的 1.0.0
,后跟一个可选的构建号(例如上述示例中的 1
),由 +
分隔。
版本号和构建号都可以在 Flutter 构建中通过分别指定 --build-name
和 --build-number
来覆盖。
在 macOS 中,build-name
使用 CFBundleShortVersionString
,而 build-number
使用 CFBundleVersion
。有关 iOS 版本控制的更多信息,请参阅 Apple 开发者网站上的“核心基础键”。
添加应用图标
#创建新的 Flutter 应用时,会生成一套占位符图标。此步骤介绍了如何用您应用的图标替换这些占位符图标:
- 查阅macOS 应用图标指南。
- 在 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 目标。
- 在“标识”部分,将 Version(版本)更新为您希望发布的面向用户的版本号。
- 在“标识”部分,将 Build(构建)标识符更新为用于在 App Store Connect 上跟踪此构建的唯一构建号。每次上传都需要一个唯一的构建号。
最后,创建一个构建归档并将其上传到 App Store Connect
- 创建您的应用的发布归档。在应用项目的根目录中,运行以下命令。
flutter build macos
- 打开 Xcode,选择 Product > Archive(产品 > 归档)以打开上一步中创建的归档。
- 点击 Validate App(验证应用)按钮。如果报告了任何问题,请解决它们并生成另一个构建。在您上传归档之前,可以重复使用相同的构建 ID。
- 归档成功验证后,点击 Distribute App(分发应用)。您可以在 App Store Connect 上应用详情页面的“活动”选项卡中跟踪构建状态。
您应该在 30 分钟内收到一封电子邮件,通知您构建已通过验证,并可在 TestFlight 上发布给测试人员。此时,您可以选择是在 TestFlight 上发布,还是直接将您的应用发布到 App Store。
有关更多详细信息,请参阅“将应用上传到 App Store Connect”。
使用 Codemagic CLI 工具创建构建归档
#此步骤介绍了如何使用 Flutter 构建命令和在 Flutter 项目目录终端中执行的 Codemagic CLI 工具来创建构建归档并将其上传到 App Store Connect。
安装 Codemagic CLI 工具
bashpip3 install codemagic-cli-tools
您需要生成一个具有 App Manager 访问权限的 App Store Connect API 密钥,以实现与 App Store Connect 的自动化操作。为了使后续命令更简洁,请从新密钥设置以下环境变量:颁发者 ID、密钥 ID 和 API 密钥文件。
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 应用分发证书和 Mac 安装程序分发证书,以执行代码签名和打包构建归档。
如果您有现有的证书,可以通过为每个证书执行以下命令来导出私钥:
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 应用分发证书和 Mac 安装程序分发证书。您可以对每个新证书使用相同的私钥。
从 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 应用分发证书私钥,或一个会自动生成新证书的新私钥。如果您没有 Mac 安装程序分发证书,可以通过执行以下命令创建新证书:
bashapp-store-connect certificates create \ --type MAC_INSTALLER_DISTRIBUTION \ --certificate-key=@file:/path/to/cert_key \ --save
使用您之前创建的私钥的
cert_key
。获取 Mac 安装程序分发证书
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(用户与职能)页面中添加其他内部用户,该页面可从页面顶部的下拉菜单中获取。
分发到已注册设备
#请参阅分发指南,以准备归档文件,用于分发到指定的 Mac 电脑。
将您的应用发布到 App Store
#当您准备好向全球发布应用时,请按照以下步骤提交应用以供审核并发布到 App Store:
- 在 App Store Connect 上,从您的应用详细信息页面的侧边栏中选择 Pricing and Availability(价格与销售范围),并填写所需信息。
- 从侧边栏中选择状态。如果这是此应用的首次发布,其状态为 1.0 Prepare for Submission(1.0 准备提交)。填写所有必填字段。
- 点击 Submit for Review(提交以供审核)。
Apple 会在应用审核过程完成后通知您。您的应用将根据您在 Version Release(版本发布)部分中指定的说明发布。
有关更多详细信息,请参阅“通过 App Store 分发应用”。
故障排除
#“分发您的应用”指南详细介绍了将应用发布到 App Store 的过程。
额外资源
#要了解如何以开源方式打包和分发您的 Flutter macOS 桌面应用,而无需使用付费的 Apple 开发者帐户,请查阅分步macOS 打包指南。