为 macOS 导出

参见

本页面描述的是如何将 Godot 项目导出到 macOS。如果你想要从源码编译编辑器或导出模板二进制文件，请移步《为 macOS 平台编译》。

macOS apps exported with the official export templates are exported as a single "Universal 2" binary .app bundle, a folder with a specific structure which stores the executable, libraries and all the project files. This bundle can be exported as is, packed in a ZIP archive or DMG disk image (only supported when exporting from a computer running macOS). Universal binaries for macOS support both Intel x86_64 and ARM64 (Apple Silicon) architectures.

警告

Due to file system limitations, raw .app bundles exported from Windows lack executable flag and won't run on macOS. To fix it, use the chmod +x {executable_name} command after transferring the exported .app to macOS or Linux. Projects exported as .zip aren't affected by this issue. The main executable located in the Contents/MacOS/ subfolder, as well as optional helper executables in the Contents/Helpers/ subfolder, should have executable permission for the .app bundle to be valid.

需求

• 下载 Godot 导出模板。使用 Godot 菜单：编辑器 > 管理导出模板。

• 应当在导出选项的 应用 部分中设置有效且唯一的 捆绑包标识符。

警告

导出的项目如果没有进行代码签名和公证，那么如果是从未知来源下载到的，就会被“门禁”（Gatekeeper）阻拦。详情请参阅在 macOS 上运行 Godot 应用页面。

代码签名与公证

默认情况下，macOS 只会运行经过签名和公证的应用程序。如果你使用了其他签名配置，替代方案请参阅在 macOS 上运行 Godot 应用。

要公证 App，你必须持有有效的 Apple 开发者 ID 证书。

如果你有 Apple 开发者 ID 证书并且是在 macOS 上导出

安装 Xcode 命令行工具并至少打开一次 Xcode，或者运行命令 sudo xcodebuild -license accept 来接受许可协议。

为导出的应用签名

• 在代码签名 > 代码签名（Code Signing > Codesign） 选项中选择 Xcode codesign 选项。

• 在代码签名 > 身份（Code Signing > Identity）部分中设置有效的 Apple ID 证书身份（证书“通用名称”）。

公证导出的应用程序

• 在公证 > 公证（Notarization > Notarization）选项中选择 Xcode altool。

• 禁用调试（Debugging）授权。

• 在公证（Notarization）部分中设置有效的 Apple ID 登录 / 应用特定的密码或应用商店连接 API UUID / 密钥。

你可以使用 xcrun notarytool history 命令检查公证状态，使用 xcrun notarytool log {ID} 命令下载公证日志。

如果你在公证过程中遇到了问题，请在解决常见的公证问题查看更多信息。

完成公证后，请将票证装订到导出的项目上。

如果你有 Apple 开发者 ID 证书并且是在 Linux 或 Windows 上导出

请安装 PyOxidizer rcodesign 并在编辑器设置 > 导出 > macOS > rcodesign 中配置 rcodesign 的路径。

为导出的应用签名

• 在代码签名 > 代码签名（Code Signing > Codesign）选项中选择 PyOxidizer rcodesign。

• 在代码签名（Code Signing）部分设置有效的 Apple ID PKCS #12 证书和密码。

公证导出的应用程序

• 在公证 > 公证（Notarization > Notarization）选项中选中 PyOxidizer rcodesign。

• 禁用调试（Debugging）授权。

• 在公证（Notarization）部分须设置有效的应用商店连接 API UUID / 密钥。

你可以使用 rcodesign notary-log 命令来检查公证状态。

当公证完成，用 rcodesign staple 命令将票证装订到导出的项目中。

如果你没有 Apple 开发者 ID 证书

• 在代码签名 > 代码签名（Code Signing > Codesign）选项中选择 Built-in (ad-hoc only)。

• 在 公证 > 公证 选项中选择 Disabled。

在这种情况下，Godot 将使用 Ad-hoc 签名，这将使最终用户更容易运行导出的应用程序，详情请见在 macOS 上运行 Godot App 页面。

签名选项

选项	描述
Codesign	代码签名的工具。
Identity	签名主体的“全名”或“通用名”，存储在 macOS 密钥链中。[1]
证书文件	PKCS #12 证书文件。[2]
证书密码	证书文件的密码。[2]
自定义选项	传递给代码签名工具的命令行参数数组。

[1]

这个选项仅在使用 Xcode 的 codesign 进行签名时可见。

[2] (1,2)

这些选项仅在使用 PyOxidizer 的 rcodesign 进行签名时才可见。

公证选项

选项	描述
公证	用于公证的工具。
Apple ID 名称	Apple ID 账户名称（邮箱地址）。[3]
Apple ID 密码	Apple ID 的 App 专用密码。请参阅《使用 App 专用密码》启用双重认证并创建 App 密码。[3]
Apple 团队 ID	团队 ID（“组织单元”），如果你的 Apple ID 属于多个团队（可选）。[3]
API UUID	苹果 App Store Connect API 发行人 UUID。
API 密钥	苹果 App Store Connect API 密钥。

备注

你应该设置 Apple ID 名称/密码或 App Store Connect API UUID/Key。

[3] (1,2,3)

这些选项只会在使用 Xcode altool 进行公证时显示。

详情请参阅分发前对 macOS 软件进行公证。

授权

强化运行时授权

强化运行时授权（Hardened Runtime entitlements）管理的是安全性选项和资源访问策略。详情请参阅强化运行时。

授权	描述
允许执行 JIT 代码 [4]	允许为 JIT 代码创建可写可执行的内存。如果你正在使用动态或能够自我修改原生代码的插件，请根据插件文档启用它们。
允许未签名的可执行内存 [4]	允许创建没有 JIT 限制的可写可执行的内存。如果你正在使用动态或能够自我修改原生代码的插件，请根据插件文档启用它们。
允许 DYLD 环境变量 [4]	允许 App 使用动态链接器环境变量注入代码。如果你正在使用动态或能够自我修改原生代码的插件，请根据插件文档启用它们。
禁用库验证	允许 App 加载任意库和框架。如果你使用 GDExtension 插件或 Ad-hoc 签名，或者想要支持用户提供的外部插件，请启用。
音频输入	请在需要使用麦克风或者其他音频输入源时启用。启用时，你应该还要在 privacy/microphone_usage_description 中提供用途信息。
摄像头	请在需要使用摄像头时启用。启用时，你应该还要在 privacy/camera_usage_description 中提供用途信息。
位置	请在需要使用位置服务时启用。启用时，你应该还要在 privacy/location_usage_description 中提供用途信息。
地址簿	[5] 请在需要访问用户的地址簿时启用。启用时，你应该还要在 privacy/address_book_usage_description 中提供用途信息。
日历	[5] 请在需要访问用户的日历时启用。启用时，你应该还要在 privacy/calendar_usage_description 中提供用途信息。
照片图库	[5] 请在需要访问用户的照片图库时启用。启用时，你应该还要在 privacy/photos_library_usage_description 中提供用途信息。
Apple 事件	[5] 请在需要允许 App 向其他 App 发送 Apple 事件时启用。
调试	[6] 你可以临时启用这个授权来对导出的 App 使用原生调试器（GDB、LLDB）。生产导出中应该禁用这个授权。

[4] (1,2,3)

Allow JIT Code Execution、Allow Unsigned Executable Memory、Allow DYLD Environment Variables 授权在 Godot Mono 导出中始终启用，且在导出选项中不可见。

[5] (1,2,3,4)

Godot 并不支持这些特性的开箱即用，请在使用需要用到它们的插件时启用。

[6]

要对 App 进行公证，你必须禁用 Debugging 授权。

App 沙盒授权

App 沙盒会限制对用户数据、网络、设备的访问。沙盒 App 无法访问文件系统的大部分位置，无法使用自定义文件对话框，也无法执行 .app 捆绑包以外的可执行文件（通过 OS.execute 和 OS.create_process）。详情请参阅 App Sandbox。

备注

要通过 App Store 分发 App，必须启用 App 沙盒。

授权	描述
Enabled	启用 App 沙盒。
Network Server	允许 App 监听入站网络请求。
Network Client	允许 App 监听出站网络请求。
Device USB	允许 App 与 USB 设备交互。使用有线控制器需要这项授权。
Device Bluetooth	允许 App 与蓝牙设备交互。使用无线控制器需要这项授权。
下载文件夹 [7]	允许对用户的“ Downloads”文件夹进行读写。
图片文件夹 [7]	允许对用户的“ Pictures”文件夹进行读写。
音乐文件夹 [7]	允许对用户的“ Music”文件夹进行读写。
影像文件夹 [7]	允许对用户的“ Movies”文件夹进行读写。
由用户选择文件夹 [7]	允许对用户的任意文件夹进行读写。要获取访问权限，必须由用户在原生文件对话框中选中该文件夹。
Helper Executable	要在 App 捆绑包中嵌入的辅助可执行文件列表。沙盒 App 仅限于执行这些可执行文件。

[7] (1,2,3,4,5)

针对不同的文件夹，你还可以通过 privacy/*_folder_usage_description 选项提供用途信息。

备注

选择自定义授权文件即可覆盖默认授权，此时其他所有授权都会被忽略。

环境变量

你可以使用以下环境变量在编辑器外部设置导出选项。在导出过程中，这些值会覆盖你在导出菜单中设置的值。

macOS 导出环境变量

导出选项	环境变量
加密 / 密钥	GODOT_SCRIPT_ENCRYPTION_KEY
选项 / 代码签名 / 证书文件	GODOT_MACOS_CODESIGN_CERTIFICATE_FILE
选项 / 代码签名 / 证书密码	GODOT_MACOS_CODESIGN_CERTIFICATE_PASSWORD
选项 / 代码签名 / 预置描述文件	GODOT_MACOS_CODESIGN_PROVISIONING_PROFILE
选项 / 公证 / API UUID	GODOT_MACOS_NOTARIZATION_API_UUID
选项 / 公证 / API 密钥	GODOT_MACOS_NOTARIZATION_API_KEY
选项 / 公证 / API 密钥 ID	GODOT_MACOS_NOTARIZATION_API_KEY_ID
选项 / 公证 / Apple ID 名称	GODOT_MACOS_NOTARIZATION_APPLE_ID_NAME
选项 / 公证 / Apple ID 密码	GODOT_MACOS_NOTARIZATION_APPLE_ID_PASSWORD