打包 macOS 应用 (Packaging app for macOS)

---

本指南介绍了将 Flet 应用打包为 macOS 应用程序包的详细步骤。

提示

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

前提条件 (Prerequisites)

Rosetta 2

用于打包的 Flutter 在 Apple Silicon 芯片的 Mac 上运行时需要 Rosetta 2：

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

Xcode

编译原生的 Swift 或 Objective-C 代码需要安装 Xcode 15 或更高版本。

CocoaPods

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

---

flet build macos

提示

此命令只能在 macOS 上运行。

从你的 Flet 应用构建 macOS 应用程序包。

目标架构 (Target architecture)

默认情况下，flet build macos 会创建一个通用应用包（Universal Bundle），可以同时在 Apple Silicon 和 Intel 架构的 Mac 上运行。打包时会同时下载适用于 arm64 和 x86_64 架构的 Python wheel 包。

要限制打包到特定的架构，请参阅目标架构。这会影响打包的 Python wheels 依赖，反过来也决定了应用可以在哪些 CPU 架构上运行。随后你将需要向用户提供适用于其 Mac 的正确构建版本。

---

权限 (Permissions)

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

Info.plist 属性设置

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

解析优先级

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

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

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

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

flet build macos \
  --info-plist LSApplicationCategoryType="public.app-category.utilities" \
  --info-plist NSSupportsSuddenTermination=true \
  --info-plist ExampleInteger=32 \
  --info-plist ExampleReal=0.5 \
  --info-plist 'SupportedModes=["basic", "advanced"]' \
  --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 'CFBundleDocumentTypes=[{ CFBundleTypeName = "Data File", CFBundleTypeExtensions = ["dat"] }, { CFBundleTypeName = "JSON File", CFBundleTypeExtensions = ["json"] }]'

---

权利声明 (Entitlements)

权利声明（Entitlements）是属性列表的键值对，用于向可执行文件授予使用某项服务或技术的特殊权限。支持的值类型取决于 Apple 官方权利参考文档中所定义的内容。

权利声明在构建模板中将被写入到 macos/Runner/DebugProfile.entitlements 和 macos/Runner/Release.entitlements 文件中。

解析优先级

1. --macos-entitlements
2. [tool.flet.macos.entitlement]
3. 跨平台权限包所注入的值（如有）。

默认值

[tool.flet.macos.entitlement]
"com.apple.security.app-sandbox" = false
"com.apple.security.cs.allow-jit" = true
"com.apple.security.network.client" = true
"com.apple.security.network.server" = true
"com.apple.security.files.user-selected.read-write" = true

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

• true 或 false（不区分大小写）表示布尔值。
• 整数或实数，例如 32 或 0.5。
• TOML 数组字面量，例如 ["group.example.one", "group.example.two"]。
• TOML 内联表字面量，例如 { "com.apple.mail" = ["compose"] }。
• 其他任何类型的值都会被视为字符串。

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

flet build macos \
  --macos-entitlements com.apple.security.network.client=true \
  --macos-entitlements com.apple.developer.ubiquity-kvstore-identifier=ABCDE12345.dev.example.myapp \
  --macos-entitlements ExampleInteger=32 \
  --macos-entitlements ExampleReal=0.5 \
  --macos-entitlements 'com.apple.security.application-groups=["group.dev.example.myapp", "group.dev.example.shared"]' \
  --macos-entitlements 'ExampleBooleanArray=[true, false]' \
  --macos-entitlements 'com.apple.security.scripting-targets={ "com.apple.mail" = ["compose", "send"] }' \
  --macos-entitlements 'ExampleArrayOfDictionaries=[{ Name = "alpha", Enabled = true }, { Name = "beta", Enabled = false }]'