Manuals
Manuals




This translation is community contributed and may not be up to date. We only maintain the English version of the documentation. Read this manual in English

iOS 开发

为 iOS 打包游戏仅适用于 Mac 版本的 Defold 编辑器。

iOS 要求 所有 你想要在手机或平板电脑上运行的应用 必须 使用 Apple 颁发的证书和配置文件进行签名。本手册解释了为 iOS 打包游戏所涉及的步骤。在开发过程中,通过 开发应用 运行游戏通常是首选,因为它允许你直接将内容和代码热重载到你的设备上。

Apple 的代码签名过程

与 iOS 应用相关的安全性由多个组件组成。你可以通过注册 Apple 的 iOS 开发者计划 获得所需工具的访问权限。注册后,请前往 Apple 开发者会员中心。

Apple Member Center

证书、标识符和配置文件 部分包含了你需要的所有工具。从这里你可以创建、删除和编辑:

证书
Apple 颁发的加密证书,用于标识你作为开发者的身份。你可以创建开发或生产证书。开发者证书允许你在沙盒测试环境中测试某些功能,例如应用内购买机制。生产证书用于对最终应用进行签名以便上传到 App Store。在将应用放到设备上进行测试之前,你需要使用证书对应用进行签名。
标识符
用于各种用途的标识符。可以注册通配符标识符(即 some.prefix.*),这些标识符可以用于多个应用。应用 ID 可以包含应用服务信息,例如应用是否启用 Passbook 集成、Game Center 等。此类应用 ID 不能是通配符标识符。为了使应用服务正常工作,你的应用的 包标识符 必须与应用 ID 标识符匹配。
设备
每个开发设备都需要使用其 UDID(唯一设备标识符,见下文)进行注册。
配置文件
配置文件将证书与应用 ID 和设备列表相关联。它们指明哪个开发者的哪个应用被允许在哪些设备上运行。

在 Defold 中为游戏和应用签名时,你需要有效的证书和有效的配置文件。

你可以在会员中心主页上执行的一些操作也可以在 Xcode 开发环境中执行—前提是你已安装了 Xcode。

设备标识符 (UDID)
iOS 设备的 UDID 可以通过 wifi 或线缆将设备连接到计算机来找到。打开 Xcode 并选择 Window ▸ Devices and Simulators。当你选择设备时,会显示序列号和标识符。

xcode devices

如果你没有安装 Xcode,你可以在 iTunes 中找到标识符。点击设备符号并选择你的设备。

itunes devices

  1. 在 摘要 页面上,找到 序列号。
  2. 点击 序列号 一次,使该字段变为 UDID。如果你反复点击,将会显示设备的几条信息。继续点击直到显示 UDID。
  3. 右键点击长 UDID 字符串并选择 复制 将标识符复制到剪贴板,这样你就可以在 Apple 开发者会员中心注册设备时轻松地将其粘贴到 UDID 字段中。

使用免费的 Apple 开发者账户进行开发

从 Xcode 7 开始,任何人都可以安装 Xcode 并免费进行设备开发。你不必注册 iOS 开发者计划。相反,Xcode 会自动为你作为开发者颁发一个证书(有效期1年)和针对你的应用的配置文件(在你的特定设备上有效一周)。

  1. 连接你的设备。
  2. 安装 Xcode。
  3. 向 Xcode 添加新账户并使用你的 Apple ID 登录。
  4. 创建一个新项目。最简单的Single View App即可。
  5. 选择你的Team(为你自动创建)并为应用提供一个包标识符。

记下包标识符,因为你必须在你的 Defold 项目中使用相同的包标识符。

  1. 确保 Xcode 已为应用创建了 配置文件 和 签名证书。

  2. 在你的设备上构建应用。第一次,Xcode 会要求你启用开发者模式,并会用调试器支持准备设备。这可能需要一段时间。
  3. 当你验证应用可以正常工作后,在磁盘上找到它。你可以在Report Navigator的构建报告中查看构建位置。

  4. 找到应用,右键单击它并选择 显示包内容。

  5. 将embedded.mobileprovision文件复制到你驱动器上你将找到它的某个位置。

此配置文件可以与你的代码签名身份一起使用,在 Defold 中为应用签名,有效期为一周。

当配置文件过期时,你需要在 Xcode 中再次构建应用并获取新的临时配置文件,如上所述。

创建 iOS 应用包

当你拥有代码签名身份和配置文件后,你就可以从编辑器中为你的游戏创建独立的应用包。只需从菜单中选择 Project ▸ Bundle... ▸ iOS Application...。

Signing iOS bundle

选择你的代码签名身份并浏览移动配置文件,同时选择变体(Debug 或 Release)。你可以取消选中 Sign application 复选框以跳过签名过程,稍后再手动签名。勾选 Simulator 可以创建用于 iOS 模拟器的 arm64_sim-ios 包,而不是设备包。

模拟器包只能在 Apple Silicon Mac 上的 iOS 模拟器中运行。它们始终使用 ad-hoc 签名,因此勾选 Simulator 后,签名、安装和启动选项将被禁用。请按照下文说明使用 xcrun simctl 安装该包。

按创建包,然后系统会提示你指定包将在你的计算机上的哪个位置创建。

ipa iOS application bundle

你在 game.project 项目设置文件的 iOS 部分 中指定要使用的图标、启动屏幕故事板等。

Home Indicator 行为

可以在 game.project 的 iOS 部分选择 Home Indicator Mode。默认值 Deferred 会保护所有屏幕边缘,返回主屏幕需要滑动两次。选择 System 则使用正常系统手势,包括一次滑动返回主屏幕。

选择 Auto Hide 可使用正常系统手势,同时请求自动隐藏 Home Indicator。可以直接在 game.project 中设置此模式:

[ios]
home_indicator_mode = auto_hide

重新打包并在有 Home Indicator 的设备上测试。iOS 决定指示条何时显示;选择 Auto Hide 不保证它一直隐藏。在 iOS 26 及更高版本上,系统可能在 System 和 Auto Hide 两种模式下都隐藏它。全部取值及其手势行为请参阅 Home Indicator Mode。

保留区域与旋转

在 iOS 27.1 及更高版本上,window.get_reserved_areas() 报告摄像头缺口和灵动岛区域,包括 UIKit 的交互边距。iOS 方向切换也会发送 window.WINDOW_EVENT_RESIZED,包括窗口尺寸和安全区边距未改变的旋转。每次收到调整大小回调时,都应刷新根据这些区域确定的 UI 位置。坐标、限制和刷新示例请参阅屏幕保留区域。

自定义 Info.plist 和本地目标发现

内置 iOS Info.plist 包含非 Release 构建自动发现编辑器目标所需的 Bonjour 服务和本地网络使用说明。自定义 Info.plist 会替换该内置基础清单。如果 Debug 构建使用自定义清单,并且需要通过本地网络进行目标发现、性能分析、热重载或日志流传输,请包含以下条目:

{{^variant_release}}
<key>NSBonjourServices</key>
<array>
    <string>_defold._tcp</string>
</array>
<key>NSLocalNetworkUsageDescription</key>
<string>Discover Defold targets on the local network.</string>
{{/variant_release}}

Mustache 条件会将发现相关条目排除在 Release bundle 之外。iOS 会向用户显示使用说明字符串,可按需调整或本地化。只有当 Release 应用本身使用相同的 Bonjour 服务和本地网络功能时,才应移除此条件。

构建变体

当您打包游戏时,需要选择希望使用的引擎类型。您有三个基本选项:

  • Debug
  • Release
  • Headless

这些不同版本也被称为 Build variants(构建变体)

当您选择 Project ▸ Build 时,您将始终获得调试版本。

Debug

这种类型的可执行文件通常在游戏开发过程中使用,因为它包含几个有用的调试功能:

  • 分析器 - 用于收集性能和使用计数器。了解如何使用分析器,请参阅分析器手册。
  • 日志记录 - 启用日志记录时,引擎将记录系统信息、警告和错误。引擎还将输出来自 Lua print() 函数的日志,以及使用 dmLogInfo()、dmLogError() 等的原生扩展日志记录。了解如何阅读这些日志,请参阅游戏和系统日志手册。
  • 热重载 - 热重载是一个强大的功能,它允许开发者在游戏运行时重新加载资源。了解如何使用此功能,请参阅热重载手册。
  • 引擎服务 - 可以通过多个不同的开放 TCP 端口和服务连接到游戏调试版本并与之交互。这些服务包括热重载功能、远程日志访问和上述分析器,还包括其他远程与引擎交互的服务。在开发者文档中了解有关引擎服务的更多信息。

Release

此变体禁用了调试功能。当游戏准备发布到应用商店或以其他方式与玩家共享时,应选择此选项。出于多种原因,不建议发布启用了调试功能的游戏:

  • 调试功能在二进制文件中占用一些空间,而尽量保持发布游戏的二进制文件大小尽可能小是一种最佳实践。
  • 调试功能也会占用一些 CPU 时间。如果用户使用低端硬件,这可能会影响游戏性能。在手机上,增加的 CPU 使用量还会导致发热和电池消耗。
  • 调试功能可能会暴露游戏中不应让玩家看到的信息,无论从安全、作弊还是欺诈的角度来看。

Headless

此可执行文件在没有图形和声音的情况下运行。这意味着您可以在 CI 服务器上运行游戏的单元/冒烟测试,甚至可以将其作为云中的游戏服务器使用。

在已连接的 iPhone 上安装和启动包

你可以使用编辑器的打包对话框中的Install on connected device和Launch installed app复选框来安装和启动构建的包:

Install and launch iOS bundle

你需要安装 ios-deploy 命令行工具才能使此功能工作。安装它的最简单方法是使用 Homebrew:

$ brew install ios-deploy

如果编辑器无法检测到 ios-deploy 工具的安装位置,你需要在 首选项 中指定它。

创建故事板

你使用 Xcode 创建故事板文件。启动 Xcode 并创建一个新项目。选择 iOS 和单视图应用:

Create project

点击 Next 并继续配置你的项目。输入产品名称:

Project settings

点击 Create 完成该过程。你的项目现已创建,我们可以继续创建故事板:

The project view

拖放图像以将其导入项目。接下来选择 Assets.xcassets 并将图像拖放到 Assets.xcassets:

Add image

打开 LaunchScreen.storyboard 并点击加号按钮(+)。在对话框中输入imageview以查找 ImageView 组件。

Add image view

将图像视图组件拖放到故事板上:

Add to storyboard

从图像下拉列表中选择你之前添加到 Assets.xcassets 的图像:

定位图像并进行所需的其他调整,例如添加 Label 或其他 UI 元素。完成后,将活动 scheme 设置为 Any iOS Device (arm64)(或 Generic iOS Device),然后选择 Product ▸ Build。Defold 支持 iOS 15.0 及更高版本的 64 位设备,因此请将部署目标保持在 15.0 或更高版本。等待构建过程完成。

如果你在故事板中使用图像,它们不会自动包含在你的 LaunchScreen.storyboardc 中。使用 game.project 中的 Bundle Resources 字段来包含资源。 例如,在 Defold 项目中创建 LaunchScreen 文件夹,并在其中创建 ios 文件夹(ios 文件夹仅用于包含这些文件到 ios 包中),然后将你的文件放入 LaunchScreen/ios/。在 Bundle Resources 中添加此路径。

最后一步是将编译的 LaunchScreen.storyboardc 文件复制到你的 Defold 项目。在 Finder 中打开以下位置并将 LaunchScreen.storyboardc 文件复制到你的 Defold 项目:

/Library/Developer/Xcode/DerivedData/YOUR-PRODUCT-NAME-cbqnwzfisotwygbybxohrhambkjy/Build/Intermediates.noindex/YOUR-PRODUCT-NAME.build/Debug-iphonesimulator/YOUR-PRODUCT-NAME.build/Base.lproj/LaunchScreen.storyboardc

论坛用户 Sergey Lerg 已经整理了展示此过程的视频教程。

一旦你有了故事板文件,就可以从 game.project 中引用它。

创建图标资源目录

使用资源目录是 Apple 管理应用图标的首选方式。实际上,这是提供 App Store 列表中使用的图标的唯一方法。你以与故事板相同的方式创建资源目录,使用 Xcode。启动 Xcode 并创建一个新项目。选择 iOS 和单视图应用:

Create project

点击 Next 并继续配置你的项目。输入产品名称:

Project settings

点击 Create 完成该过程。你的项目现已创建,我们可以继续创建资源目录:

The project view

将图像拖放到代表不同支持图标大小的空框中:

Add icons

不要为通知、设置或 Spotlight 添加任何图标。

完成后,将活动方案设置为Build -> Any iOS Device (arm64)(或Generic iOS Device)并选择 Product -> Build。等待构建过程完成。

确保你为Any iOS Device (arm64)或Generic iOS Device构建,否则在上传构建时你会得到 ERROR ITMS-90704 错误。

Build project

最后一步是将编译的 Assets.car 文件复制到你的 Defold 项目。在 Finder 中打开以下位置并将 Assets.car 文件复制到你的 Defold 项目:

/Library/Developer/Xcode/DerivedData/YOUR-PRODUCT-NAME-cbqnwzfisotwygbybxohrhambkjy/Build/Products/Debug-iphoneos/Icons.app/Assets.car

一旦你有了资源目录文件,就可以从 game.project 中引用它和图标:

Add icon and asset catalog to game.project

App Store 图标不必从 game.project 中引用。上传到 iTunes Connect 时,它会自动从 Assets.car 文件中提取。

安装 iOS 应用包

编辑器会写入一个 .ipa 文件,这是一个 iOS 应用包。要在你的设备上安装该文件,你可以使用以下工具之一:

你还可以使用 xcrun simctl 命令行工具与通过 Xcode 提供的 iOS 模拟器一起工作:

# show a list of available devices
xcrun simctl list

# boot an iPhone X simulator
xcrun simctl boot "iPhone X"

# install your.app to a booted simulator
xcrun simctl install booted your.app

# launch the simulator
open /Applications/Xcode.app/Contents/Developer/Applications/Simulator.app

Apple 隐私清单

隐私清单是一个属性列表,用于记录您的应用程序或第三方 SDK 收集的数据类型,以及您的应用程序或第三方 SDK 使用的必需原因 API。对于您的应用程序或第三方 SDK 收集的每种数据类型以及使用的必需原因 API 类别,应用程序或第三方 SDK 需要在其捆绑的隐私清单文件中记录这些原因。

Defold 通过 game.project 文件中的隐私清单字段提供了一个默认的隐私清单。创建应用程序包时,隐私清单将与项目依赖项中的任何隐私清单合并,并包含在应用程序包中。

有关隐私清单的更多信息,请参阅 Apple 的官方文档。

出口合规信息

当你将游戏提交到 App Store 时,你将被要求提供有关游戏中使用加密的出口合规信息。Apple 解释了为什么这是必需的:

“当你将应用提交到 TestFlight 或 App Store 时,你将应用上传到美国的服务器。如果你在美国或加拿大之外分发你的应用,无论你的法律实体位于何处,你的应用都受美国出口法律的约束。如果你的应用使用、访问、包含、实现或合并加密,这被视为加密软件的出口,这意味着你的应用必须符合美国的出口合规要求,以及你分发应用所在国家的进口合规要求。”

Defold 游戏引擎将加密用于以下目的:

  • 通过安全通道进行调用(即 HTTPS 和 SSL)
  • Lua 代码的版权保护(以防止复制)

Defold 引擎中这些加密的使用在美国和欧盟法律下免于出口合规文件要求。大多数 Defold 项目将保持豁免,但添加其他加密方法可能会改变此状态。你有责任确保你的项目符合这些法律和 App Store 规则的要求。有关更多信息,请参阅 Apple 的出口合规概述。

如果您认为项目属于豁免范围,请在项目的 Info.plist 中将 ITSAppUsesNonExemptEncryption 键设为 False,更多信息请参阅应用清单。

常见问题

Q: 我无法使用免费的 Apple Developer 账户安装我的 Defold 游戏。

A: 请确保您在 Defold 项目中使用的 bundle identifier 与您在生成移动设备配置文件时在 Xcode 项目中使用的 bundle identifier 相同。

Q: 如何检查捆绑应用程序的权限?

A: 来自 检查构建应用程序的权限:

codesign -d --ent :- /path/to/the.app

Q: 如何检查配置文件的权限?

A: 来自 检查配置文件的权限:

security cms -D -i /path/to/iOSTeamProfile.mobileprovision