description bug_report

构建和发布为 macOS 应用

预备工作
在 App Store Connect 上注册你的应用程序
- 注册 Bundle ID
- 在 App Store Connect 上创建应用程序记录
检查 Xcode 项目设置
配置应用名称、Bundle ID 和版权信息
更新应用程序的版本号
添加应用程序图标
创建构建存档
使用 Codemagic 命令行工具创建一个构建归档
将你的应用发布到 TestFlight
分发到已注册的设备
将应用程序发布到应用程序商店
故障排除

本教程将指导开发者如何在 App Store 上发布 Flutter 应用程序。

预备工作

在开始发布应用程序之前，请确保它符合苹果的应用程序审查指南。

为了将应用程序发布到 App Store，你必须先注册苹果开发者计划。可以在 Apple 的选择会员资格指南中阅读更多关于各种会员资格的信息。

在 App Store Connect 上注册你的应用程序

在 App Store Connect（以前叫 iTunes Connect）上管理应用程序的生命周期。你可以定义应用程序的名称和描述、添加屏幕截图、设置定价以及管理应用程序商店和 TestFlight 的发布。

注册应用程序包括两个步骤：注册一个唯一的 Bundle ID，以及在 App Store Connect 上创建应用程序记录。

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

注册 Bundle ID

每个 macOS 应用程序都与一个 Bundle ID 关联， Bundle ID 是在 Apple 注册的唯一标识。要为应用程序注册 Bundle ID，请执行以下步骤：

打开开发者帐户的 App IDs 页面。
点击 + 创建一个新的 Bundle ID。
输入应用程序名称，选择 显式 App ID，然后输入 ID。
选择应用程序使用的服务，然后点击 下一步。
在下一页中，确认应用的详细信息，然后点击注册来注册你的 Bundle ID。

在 App Store Connect 上创建应用程序记录

在 App Store Connect 上注册你的应用程序：

在浏览器中打开 App Store Connect。
在 App Store Connect 登录页上，点击 我的应用程序。
点击我的应用程序页面左上角的 +，然后选择 新建应用程序。
在表单中填写应用程序详细信息。在平台部分，请确保选中了 macOS。由于 Flutter 目前不支持 tvOS，所以不要选中该项。点击创建。
从侧边栏中选择 应用程序信息，可以查看应用程序的详细信息。
在常规信息中，选择在上一步中注册的 Bundle ID。

更详细的介绍，请参阅将应用程序添加到你的帐户]

检查 Xcode 项目设置

这一步包括检查 Xcode 工作区中最重要的设置。更详细的过程和说明，请参阅准备应用程序分发。

在 Xcode 中配置目标：

在 Xcode 中，打开应用程序 macos 文件夹中的 Runner.xcworkspace。
要查看应用程序的设置，请在 Xcode 导航栏中选择 Runner 项目。然后，在主视图侧栏中，选择 Runner 目标。
选择 General（常规） 选项。

确认最重要的设置。

在 Identity（标识） 部分：

App Category（应用类别）
你的应用将出现在 Mac App Store 中的哪个类别，此项不能为空。

Bundle Identifier
你在 App Store Connect 注册的应用程序 ID。

在 Deployment info（部署信息） 部分：

Deployment Target（部署目标）
应用程序支持的最低 macOS 版本。Flutter 支持 macOS 10.14 及更高版本。

在 Signing & Capabilities（签名和功能） 部分：

Automatically manage signing（自动管理签名）
Xcode 是否自动管理应用程序签名和配置。默认为 true，这对于大多数应用程序来说应该足够。更复杂的场景，请参阅代码签名指南。

Team（团队）
选择与你注册的 Apple 开发者帐户关联的团队。如果需要，请选择 Add Account…（添加账户…），然后更新此设置。

项目设置的 General（常规） 选项应类似于以下内容：

Xcode Project Settings

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

配置应用名称、Bundle ID 和版权信息

引用标识的配置集中在 macos/Runner/Configs/AppInfo.xcconfig 文件中。想修改应用名称，设置 PRODUCT_NAME；想修改版权信息，设置 PRODUCT_COPYRIGHT；想修改 Bundle ID，设置 PRODUCT_BUNDLE_IDENTIFIER。

更新应用程序的版本号

应用程序的默认版本号为 1.0.0。如需更新版本号，在 pubspec.yaml 文件中更新以下位置：

version: 1.0.0+1

版本号是三个用点分隔的数字，如上面示例中的 1.0.0，后面用 + 分隔的是可选的内部版本号，如上面示例中的 1。

版本号和内部版本号都可以在 Flutter 构建时，通过指定 --build name 和 --build number 进行覆盖。

在 macOS 中，build-name 使用 CFBundleShortVersionString，而 build-number 使用 CFBundleVersion。在苹果开发者的网站上，查看更多关于 iOS 版本的 Core Foundation Keys 。

添加应用程序图标

创建一个新的 Flutter 应用程序时，会创建一个占位图标集。此步骤包含如何用应用程序的图标替换这些占位图标：

查看 macOS 应用程序图标指南。
在 Xcode 项目导航栏的 Runner 文件夹中选择 Assets.xcassets。用你自己的应用程序图标更新占位图标。
使用 flutter run -d macos 运行应用程序，验证图标是否已被替换。

创建构建存档

此步骤包含创建构建存档并将其上传到 App Store Connect。

在开发时，你已经完成了在 debug 模式下的应用构建、调试和测试。当你准备好在 App Store 或 TestFlight 上向用户发布应用时，你需要准备一个 release 版产物。此时，你可以考虑混淆你的 Dart 代码让逆向工程变得更加困难。混淆你的代码需要向构建命令添加两个标志。

在 Xcode 中，配置应用程序版本和内部版本：

打开 macos 文件夹中的 Runner.xcworkspace 工程项目，若要在命令行中这样做就切换到工程的文件夹下运行下面的命令:
```
open macos/Runner.xcworkspace
```
在 Xcode 项目导航栏中选择 Runner，然后在设置侧栏中选择 Runner 目标。
在标识部分，将 Version（版本） 更新为要发布的版本号。
在标识部分，将 Build identifier（构建标识） 更新为在 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 Connect。

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

下面的步骤，我们会介绍在 Flutter 应用的工程目录下执行 Flutter 构建命令和 Codemagic 命令行工具，创建一个构建归档并将其上传至 App Store Connect。

安装 Codemagic 命令行工具：
```
pip3 install codemagic-cli-tools
```
你需要生成一个具有 App Manager 访问权限的 App Store Connect API 密钥，以方便对 App Store Connect 进行自动化操作。为了使后续的命令更简洁，请设置下面的环境变量：发行者 ID、密钥 ID、API 密钥文件：
```
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`
```
你需要导出或者创建 Mac App Distribution 和 Mac Installer Distribution 证书，以便与执行代码签名以及打包构建归档。

对于已有的证书，你可以选择通过下吗的命令来导出私钥：
```
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 ""
```
之后，你可以让命令行工具自动创建新的 Mac App Distribution 和 Mac Installer Distribution 证书，每个新的证书都可以使用相同的私钥。

从 App Store Connect 获取需要代码签名的文件：

app-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 证书，通过执行下面的命令行可以生成一个：

app-store-connect create-certificate \
    --type MAC_INSTALLER_DISTRIBUTION \
    --certificate-key=@file:/path/to/cert_key \
    --save

使用你之前创建的私钥的 cert_key。

获取 Mac 安装程序分发证书：

app-store-connect list-certificates \
    --type MAC_INSTALLER_DISTRIBUTION \
    --certificate-key=@file:/path/to/cert_key \
    --save

设置用于代码签名的新临时钥匙串：
```
keychain initialize
```
恢复登录钥匙串！ 运行 keychain initialize 后，你必须运行以下命令：

keychain use-login

这会将你的登录钥匙串设置为默认值，以避免你机器上的应用程序出现潜在的身份验证问题。
现在将获取的证书添加到你的钥匙串中：
```
keychain add-certificates
```
更新 Xcode 项目设置以使用获取的代码签名配置文件：
```
xcode-project use-profiles
```
安装 Flutter 依赖项：
```
flutter packages pub get
```

安装 CocoaPods 依赖项：

find . -name "Podfile" -execdir pod install \;

构建 Flutter macOS 项目：
```
flutter build macos --release
```

打包应用程序：

APP_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：

app-store-connect publish \
    --path "$PACKAGE_NAME"

如前所述，不要忘记将你的登录钥匙串设置为默认设置，以避免你机器上的应用程序出现身份验证问题：
```
keychain use-login
```

将你的应用发布到 TestFlight

TestFlight 允许开发者将其应用推送给内部和外部的测试人员。以下步骤将指导你如何将你的应用在 TestFlight 分发给测试人员。

在 App Store Connect 中，前往你的应用详情的 TestFlight 标签。
在侧边栏中选择 Internal Testing。
选择需要发布给测试人员的构建版本，点击保存。
添加测试人员的电子邮件。你可以在 Users and Roles 配置测试人员，该选项在页面顶部的下拉菜单中。

分发到已注册的设备

请参阅分发指南，准备一个归档文件，以便分发到指定的 Mac 设备。

将应用程序发布到应用程序商店

当你准备向全世界发布应用程序时，请按照以下步骤提交应用程序以供审阅并发布到应用程序商店：

在 App Store Connect 应用程序详情页的侧栏中选择 定价和可用性，并完善相关信息。
从侧边栏中选择状态。如果这是应用程序的第一个版本，则其状态为 1.0 准备提交。填写所有必填字段。
点击 提交审核。

苹果会在你的应用程序审核完成后通知你。应用程序是按照你在 版本发布 说明中发布的。

更多详细信息，请参阅通过应用程序商店分发应用程序.

故障排除

分发你的应用程序指南详细概述了将应用程序发布到应用商店的过程。