打包 iOS 应用 | Flet中文文档

打包 iOS 应用 (Packaging app for iOS)

本指南介绍了将 Flet 应用打包为 Xcode 归档文件（Archive）以及导出适用于分发的 .ipa 文件所需的详细步骤。

提示

本指南提供了专门针对 iOS 平台的详细信息。更通用和互补的打包信息，请参阅发布 Flet 应用。

前提条件 (Prerequisites)

Rosetta 2

部分 Flutter 工具链和依赖包仍作为 Intel 二进制文件运行。如果是 Apple Silicon 芯片的 Mac 且 Flutter 或 CocoaPods 提示需要，请在终端中运行以下命令安装 Rosetta 2：

bash

sudo softwareupdate --install-rosetta --agree-to-license

Xcode

你需要安装 Xcode 15 或更高版本以编译原生 Swift 或 Objective-C 代码。安装后至少打开一次 Xcode 以接受许可协议并自动安装附加组件。

CocoaPods

编译和启用 Flutter 插件需要 CocoaPods 1.16 或更高版本。

适用于 iOS 的 Python 二进制轮子包 (wheels)

二进制 Python 包（与仅用 Python 编写的“纯” Python 包不同）是部分使用 C、Rust 或其他语言编写的，会生成原生平台代码的包（例如 numpy、cryptography 或 pydantic-core）。

请确保你的 Flet 应用中所使用的所有非纯（二进制）依赖包，都具有预编译的适用于 iOS 的 wheel 分发包。

flet build ipa

提示

此命令只能在 macOS 上运行。

构建 iOS 应用归档文件（.xcarchive），并在配置了数字签名后，自动导出用于测试或分发的 .ipa 安装包。

为了生成用于在实体设备上测试或上传到 App Store Connect 进行分发的 .ipa 包，你需要具备以下条件：

能够访问 App Store Connect 的 Apple 开发者计划（Apple Developer Program）订阅账户
应用程序标识符（App ID）
在你的 Flet 项目中配置的 Bundle ID（必须与注册的 App ID 保持一致）
签名证书（Signing Certificate）
描述文件（Provisioning Profile）

flet build ios-simulator

提示

此命令只能在 macOS 上运行。

构建（未签名的）iOS 模拟器专用 .app 包。此包仅适用于在 iOS 模拟器上运行测试，无需配置签名证书、描述文件或设置 Apple 开发者计划。

配置选项 (Configuration options)

应用程序标识符 (App ID)

在 Apple 生态系统中唯一标识你的应用程序的字符串。它是对 iOS 应用进行签名和分发所必需的，也用于诸如推送通知、应用组（App Groups）、iCloud 和应用内购买（In-App Purchases）等各种服务。

它由两部分组成：

Team ID: 由 Apple 分配给你的开发者账户的唯一的 10 字符字符串。
Bundle ID: 采用反向域名风格的应用程序标识符（例如 com.example.myapp）。

例如：App ID: ABCDEFE234.com.example.myapp（其中 Team ID 为 ABCDEFE234，Bundle ID 为 com.example.myapp）。

你在 Flet 配置中填写的 Bundle ID 必须与在 Apple 开发者网站上注册的 App ID 中的 Bundle ID 保持精确匹配。

注册新的 App ID

访问 Apple 开发者中心。
登录你的 Apple 开发者账号。
点击 "+" 按钮来添加一个新的标识符（Identifier）。
选择 "App IDs" 并点击 Continue。
输入 Description —— 仅作为备注（例如 "MyApp Identifier"）。
选择 App ID 类型：对于标准的 iOS/macOS 应用，选择 "App"。
填写 Bundle ID，推荐选择：Explicit Bundle ID (例如 com.example.myapp)。
勾选应用需要的服务功能（如推送通知、Sign in with Apple 等）。
点击 Continue，然后点击 Register。

你现在就拥有了用于唯一识别你应用的 Bundle ID 和 Team ID。

开发团队 ID (Team ID)

要在导出选项中包含的开发团队 ID。

解析优先级

--ios-team-id
[tool.flet.ios].team_id
[tool.flet.ios.export_methods."EXPORT_METHOD"].team_id

示例命令行构建或 pyproject.toml 配置：

bash

flet build ipa --ios-team-id ABCDEFE234

签名证书 (Signing Certificate)

用于对 iOS 应用包进行签名的证书名称、SHA-1 哈希或自动选择器。自动选择器允许 Xcode 自动挑选已安装的特定类型中最新的证书。

可用的自动选择器包括：

"Apple Development"
"Apple Distribution"
"Developer ID Application"
"iOS Developer"
"iOS Distribution"
"Mac App Distribution"
"Mac Developer"

生成证书签名请求 (CSR)

在创建开发或发布证书之前，你需要先生成一个 CSR（证书签名请求）文件：

在 Mac 上打开“钥匙串访问”（Keychain Access）应用（使用快捷键 Command + Space 搜索“钥匙串访问”）。
在顶部菜单栏中，依次选择：钥匙串访问 → 证书助理 → 从证书颁发机构请求证书…
填写以下信息：
- 用户电子邮件地址: 你的 Apple 开发者邮箱。
- 常用名称: 描述性名称（例如 "My App Distribution"）。
- CA 电子邮件地址: 留空。
- 请求是: 选择“保存到磁盘”。
点击“继续”，选择保存 .certSigningRequest 文件的位置，点击“存储”。

在 Apple 开发者中心创建证书

转到 Apple 开发者中心证书页面。
点击 "+" 按钮创建新证书。
选择 "Apple Distribution"（用于 App Store 和 Ad Hoc 发布）或 "Apple Development"（用于开发调试），然后点击 Continue。
上传你刚才生成的 CSR 文件，点击 Continue。
Apple 将为你生成数字证书，点击 Download 下载 .cer 文件。
双击下载好的 .cer 文件，系统会将其自动安装到 Mac 的“钥匙串访问”中（确保安装在“登录”钥匙串下）。开发证书名称通常以 "Apple Development:" 开头，发布证书通常以 "Apple Distribution:" 开头。

解析优先级

--ios-signing-certificate
[tool.flet.ios].signing_certificate
[tool.flet.ios.export_methods."EXPORT_METHOD"].signing_certificate

示例命令行构建或 pyproject.toml 配置：

bash

flet build ipa --ios-signing-certificate "Apple Distribution"

描述文件 (Provisioning Profile)

描述文件是允许 iOS 应用在真机上运行并进行分发的文件，它将你的 App ID、开发/发布证书和注册的测试设备关联在一起。

描述文件包含以下几种类型：

Development Profile (开发描述文件) —— 用于在实体测试真机上进行开发调试。
Ad Hoc Profile (Ad Hoc 分发描述文件) —— 用于在 App Store 之外向特定的注册测试设备分发应用。
App Store Profile (App Store 描述文件) —— 用于将应用提交上架到 App Store。
Enterprise Profile (企业版描述文件) —— 用于在企业组织内部进行内部分发。

创建新的描述文件

登录 Apple 开发者中心；
点击 "+" 按钮来添加一个新的描述文件；
选择描述文件类型（如 iOS App Development 或 App Store）；
选择与你的应用匹配的 App ID，点击 Continue；
选择对应的证书（例如开发证书或发布证书），点击 Continue；
选择要包含的已注册测试设备（对于开发/Ad Hoc 描述文件是必须的），点击 Continue；
输入 Profile Name（例如 MyApp Development Profile），点击 Generate 确认生成；
点击 Download 下载 .mobileprovision 描述文件。

安装描述文件

iOS 描述文件统一存放在 Mac 本地的 ~/Library/MobileDevice/Provisioning Profiles 目录下。

要安装下载好的描述文件，只需将其以其 {UUID}.mobileprovision 文件名复制到该目录下即可。

在终端中运行以下命令来获取该描述文件的 UUID：

bash

profile_uuid=$(security cms -D -i ~/Downloads/{profile-name}.mobileprovision | xmllint --xpath "string(//key[.='UUID']/following-sibling::string[1])" -)
echo $profile_uuid

然后运行以下命令，使用其 {UUID}.mobileprovision 名称将其复制到指定目录中：

bash

cp ~/Downloads/{profile-name}.mobileprovision ~/Library/MobileDevice/Provisioning\ Profiles/${profile_uuid}.mobileprovision

注意

如果复制后的描述文件在目录中被意外自动删除，请确保没有在后台运行 Xcode 进程。

你可以通过运行以下命令来列出本地已安装的所有描述文件及其别名与 UUID：

bash

for profile in ~/Library/MobileDevice/Provisioning\ Profiles/*.mobileprovision; do security cms -D -i "$profile" | grep -E -A1 '<key>(Name|UUID)</key>' | sed -n 's/.*<string>\(.*\)<\/string>/\1/p' | paste -d ' | ' - -; done

解析优先级

--ios-provisioning-profile
[tool.flet.ios].provisioning_profile
[tool.flet.ios.export_methods."EXPORT_METHOD"].provisioning_profile

所选取的描述文件必须与你的 Bundle ID 保持一致。

示例命令行构建或 pyproject.toml 配置：

bash

flet build ipa --ios-provisioning-profile "release-testing com.mycompany.example-app"

导出配置 (Export configuration)

导出选项 (Export options)

需要包含在构建模板自动生成的 exportOptions.plist 文件中的其他 Key 键值对。

若要查看完整支持的 Key 和 Value 列表，可以在终端运行：

bash

xcodebuild -help

并找到名为 "Available keys for -exportOptionsPlist" 的小节。

解析优先级

[tool.flet.ios].export_options（如果设置了此项，特定导出方法的独立选项将被忽略）
[tool.flet.ios.export_methods."EXPORT_METHOD"].export_options
默认不携带任何额外 Key（{}）

支持的传参形式 在 pyproject.toml 中支持包括基本和复杂结构的嵌套：

字符串
布尔值
字典（嵌套的键值对对象）
字符串数组
布尔值数组
字典数组（包括包含数组的字典）
注：目前暂不支持纯数字。

示例pyproject.toml 中的写法：

toml

[tool.flet.ios.export_options]
uploadSymbols = false
compileBitcode = false
thinning = "<none>"

[tool.flet.ios.export_options.manifest]
appURL = "https://example.com/app.ipa"
displayImageURL = "https://example.com/icon57.png"
fullSizeImageURL = "https://example.com/icon512.png"

导出方式 (Export method)

定义在导出 .ipa 文件时如何对应用进行打包。

可以取以下值之一：

debugging（或废弃的 development）：用于在开发注册设备上进行调试和测试。
release-testing（或废弃的 ad-hoc）：用于在 App Store 之外向特定的注册测试设备分发应用。
app-store-connect（或废弃的 app-store）：用于向 App Store 提交应用。
enterprise：用于在组织内部进行企业内部分发（需要企业级开发者账户）。

解析优先级

--ios-export-method
[tool.flet.ios].export_method
默认值为 "debugging"

示例命令行构建或 pyproject.toml 配置：

bash

flet build ipa --ios-export-method debugging

导出方法配置 (Export methods)

你可以为不同的导出方式分别单独配置不同的签名设置。

仅当对应的顶级 [tool.flet.ios] 配置未被设置时，才会使用特定方法的设置。方法的 Key 必须与 export_method 的值保持精确匹配。

支持的 Key（与顶级设置一致）：

provisioning_profile
signing_certificate
export_options
team_id

示例pyproject.toml 中的写法：

toml

[tool.flet.ios.export_methods."debugging"]
provisioning_profile = "debugging com.mycompany.example-app"
signing_certificate = "Apple Development"

[tool.flet.ios.export_methods."release-testing"]
provisioning_profile = "release-testing com.mycompany.example-app"
team_id = "ABCDEFE234"
signing_certificate = "Apple Distribution"
export_options = { uploadSymbols = false }

[tool.flet.ios.export_methods."app-store-connect"]
provisioning_profile = "app-store-connect com.mycompany.example-app"
team_id = "ABCDEFE234"
signing_certificate = "Apple Distribution"
export_options = { uploadSymbols = true }

权限 (Permissions)

iOS 权限通过 Info.plist 中的隐私使用说明字符串（Privacy usage strings）进行声明。你还可以使用跨平台权限包注入常用的权限项，然后使用特定于平台的配置进行覆盖或扩展。

Info.plist 属性设置

为 iOS 构建添加或覆盖 Info.plist 的属性项。这些值将被写入到构建项目的 ios/Runner/Info.plist 文件中。

解析优先级

--info-plist
[tool.flet.ios.info]
跨平台权限包所注入的值（如有）。

支持的传参形式 接受重复的 <key>=<value> 键值对参数，<value> 可以是以下格式之一：

true 或 false（不区分大小写）表示布尔值。
整数或实数，例如 32 或 0.5。
TOML 数组字面量，例如 ["myapp", "myapp-beta"]。
TOML 内联表字面量，例如 { NSAllowsArbitraryLoads = false }。
其他任何类型的值都会被视为字符串。

示例命令行构建或 pyproject.toml 配置：

bash

flet build ipa \
  --info-plist NSCameraUsageDescription="This app needs camera access." \
  --info-plist UIFileSharingEnabled=true \
  --info-plist ExampleInteger=32 \
  --info-plist ExampleReal=0.5 \
  --info-plist 'LSApplicationQueriesSchemes=["myapp", "myapp-beta"]' \
  --info-plist 'FeatureFlags=[true, false]' \
  --info-plist 'RetryDelays=[1, 2, 3]' \
  --info-plist 'OpacitySteps=[0.25, 0.5, 0.75]' \
  --info-plist 'NSAppTransportSecurity={ NSAllowsArbitraryLoads = false }' \
  --info-plist 'CFBundleURLTypes=[{ CFBundleTypeRole = "Editor", CFBundleURLName = "example.com", CFBundleURLSchemes = ["myapp"] }, { CFBundleTypeRole = "Viewer", CFBundleURLName = "example.org", CFBundleURLSchemes = ["myapp-beta"] }]'

部署应用到 Apple 设备进行真机测试 (Deploying an App to an Apple Device for Testing)

你可以在 macOS 上直接将生成的 .ipa 文件部署到 iPhone 或 iPad 上 —— 这是不需要发布到 App Store 即可进行内部测试的最佳方式。

第一步：安装并启动 Apple Configurator

从 Mac App Store 安装 Apple Configurator；
在你的应用程序文件夹中打开它。

第二步：连接你的 iOS 设备

使用 USB 连接线将你的 iOS 设备（iPhone 或 iPad）连接到 Mac；
在设备上解锁它，并在弹出提示时点击“信任此电脑”；
等待设备显示在 Apple Configurator 界面中。

第三步：添加 .ipa 安装包

你可以直接将 .ipa 文件拖拽到 Apple Configurator 中连接的设备图标上；
或者点击顶部菜单栏中的 “添加 (Add)” → “应用 (Apps)”，然后从 Mac 中选择对应的 .ipa 文件。

第四步：安装应用

点击“准备 (Prepare)”或“安装 (Install)”开始部署；
Apple Configurator 会将应用自动安装到连接的测试真机上。

第五步：信任开发者（仅针对 Ad Hoc 或企业版证书签名的应用）

如果你的应用是使用 Ad Hoc 或 Enterprise 描述文件签名的，在设备上打开应用前，你需要手动信任该开发者证书：

在 iOS 设备上转到设置 → 通用 → VPN 与设备管理；
在“开发者 App”分类下，点击对应的开发者描述文件；
点击“信任 [您的开发者姓名]”，然后在弹窗中确认信任。

上传应用到 App Store Connect 进行分发 (Uploading app to App Store Connect)

第一步：安装并登录 Transporter

从 Mac App Store 下载安装 Transporter 应用程序并打开它。
使用你的 Apple Developer 账号凭据（必须与 App Store Connect 账号一致）登录 Transporter。

第二步：准备好你的 .ipa 文件

使用 app-store-connect 导出方法构建你的应用并导出 .ipa 文件。（注意：release-testing 用于 Ad Hoc 分发，不能上传到 App Store Connect。）

第三步：在 Transporter 中上传 .ipa 文件

直接将 .ipa 文件拖放到 Transporter 窗口中，或者点击 "Add App" 从 Mac 中选择它。
点击 "Deliver" 按钮旁的 "..." 按钮并选择 "Verify" 进行校验。
等待 Transporter 完成上传校验。
校验无误后，点击 "Deliver" 按钮即可将 .ipa 文件上传部署到 App Store Connect 中。

第四步：检查上传状态

上传完成后，Transporter 会显示上传成功消息。
如果中途报错，请仔细检查错误详情并修复相应问题，然后重试。

第五步：在 App Store Connect 中确认

登录 App Store Connect 网站。
转到你的应用详情页面，查看 TestFlight 或 App Store Version 板块。
你刚才上传的版本会首先出现在“正在处理”（Processing）状态下（处理通常需要几分钟到一小时不等）。
处理完成后，该构建版本即可用于内测分发或提交上架审核。

托管

托管

打包 iOS 应用 (Packaging app for iOS) ​

前提条件 (Prerequisites) ​

Rosetta 2 ​

Xcode ​

CocoaPods ​

适用于 iOS 的 Python 二进制轮子包 (wheels) ​

flet build ipa ​

flet build ios-simulator ​

配置选项 (Configuration options) ​

应用程序标识符 (App ID) ​

注册新的 App ID ​

开发团队 ID (Team ID) ​

签名证书 (Signing Certificate) ​

生成证书签名请求 (CSR) ​

在 Apple 开发者中心创建证书 ​

描述文件 (Provisioning Profile) ​

创建新的描述文件 ​

安装描述文件 ​

导出配置 (Export configuration) ​

导出选项 (Export options) ​

导出方式 (Export method) ​

导出方法配置 (Export methods) ​

权限 (Permissions) ​

Info.plist 属性设置 ​

部署应用到 Apple 设备进行真机测试 (Deploying an App to an Apple Device for Testing) ​

第一步：安装并启动 Apple Configurator ​

第二步：连接你的 iOS 设备 ​

第三步：添加 .ipa 安装包 ​

第四步：安装应用 ​

第五步：信任开发者（仅针对 Ad Hoc 或企业版证书签名的应用） ​

上传应用到 App Store Connect 进行分发 (Uploading app to App Store Connect) ​

第一步：安装并登录 Transporter ​

第二步：准备好你的 .ipa 文件 ​

第三步：在 Transporter 中上传 .ipa 文件 ​

第四步：检查上传状态 ​

第五步：在 App Store Connect 中确认 ​

关注我，学习大模型、大数据、Python等热门技术。

打包 iOS 应用 (Packaging app for iOS)

前提条件 (Prerequisites)

Rosetta 2

Xcode

CocoaPods

适用于 iOS 的 Python 二进制轮子包 (wheels)

flet build ipa

flet build ios-simulator

配置选项 (Configuration options)

应用程序标识符 (App ID)

注册新的 App ID

开发团队 ID (Team ID)

签名证书 (Signing Certificate)

生成证书签名请求 (CSR)

在 Apple 开发者中心创建证书

描述文件 (Provisioning Profile)

创建新的描述文件

安装描述文件

导出配置 (Export configuration)

导出选项 (Export options)

导出方式 (Export method)

导出方法配置 (Export methods)

权限 (Permissions)

Info.plist 属性设置

部署应用到 Apple 设备进行真机测试 (Deploying an App to an Apple Device for Testing)

第一步：安装并启动 Apple Configurator

第二步：连接你的 iOS 设备

第三步：添加 .ipa 安装包

第四步：安装应用

第五步：信任开发者（仅针对 Ad Hoc 或企业版证书签名的应用）

上传应用到 App Store Connect 进行分发 (Uploading app to App Store Connect)

第一步：安装并登录 Transporter

第二步：准备好你的 .ipa 文件

第三步：在 Transporter 中上传 .ipa 文件

第四步：检查上传状态

第五步：在 App Store Connect 中确认