游戏引擎 / 系统课时

为移动平台设置构建参数

为移动平台设置构建参数

同一个 3D 游戏在编辑器里运行正常,打包到手机后却可能出现安装失败、启动黑屏、资源缺失或屏幕方向错误。本课以 Cocos Creator 3.8 为例,从目标设备和发布渠道反推构建参数,完成一轮可安装、可运行、可重复验证的移动端构建。

学习目标

  • 根据 Android、iOS 设备和发布渠道选择正确的构建参数。
  • 配置启动场景、参与构建的资源、图形后端和签名方式。
  • 完成构建、编译与设备运行,并定位首次打包的常见失败原因。

构建前先确认目标设备与环境

构建参数首先取决于目标设备,而不是编辑器当前能够运行什么。需要确认设备系统版本、CPU 架构、屏幕方向、图形能力,以及最终采用开发安装包还是应用商店发布包。

Android 原生构建需要安装 Android Studio、JDK、Android SDK 和 NDK。Cocos Creator 3.8 官方文档建议使用 JDK 17,并配置与引擎兼容的 SDK、NDK 工具链。相关路径可在编辑器的 Preferences(偏好设置)中找到 External Program(外部程序)页面进行配置。

iOS 原生构建需要 macOS、Xcode 和相应的签名环境。Windows 可以制作 Android 构建,但不能直接替代 Xcode 完成 iOS 原生编译和真机签名。

对于 Android,连接已开启 USB 调试并完成授权的手机后,可以先确认设备与 CPU 架构:

bash
# 确认设备已连接,再读取设备的主要 CPU ABI
adb devices
adb shell getprop ro.product.cpu.abi

预期输出(以 ARM64 手机为例):

text
List of devices attached
<ID> device
arm64-v8a

<ID> 是实际设备序列号,不同设备会有所变化。最后一行是当前设备的主要 ABI;如果显示 arm64-v8a,说明构建时至少应包含对应架构。模拟器可能使用 x86_64,不要直接用模拟器的架构替代真实手机需求。

配置启动场景与资源范围

打开 Cocos Creator 3.8,在顶部菜单选择「项目 → 构建」,创建构建任务并选择目标平台。先完成通用配置,再展开平台专属选项。

  1. 在 Build Path 中选择构建输出目录,建议使用不含空格、中文和特殊字符的项目路径。
  2. 在 Included Scenes 中确认参与构建的场景,并将实际入口场景设为 Start Scene。例如游戏需要先进入 Boot,再由脚本跳转到 Lobby 或 Battle,就应以 Boot 作为启动场景。
  3. 检查 Bundles 选项,确认发布时需要的 Asset Bundle 已参与构建。动态加载的资源必须能够从内置资源或正确部署的远程 Bundle 中获得。
  4. 首次验证建议启用 Debug Mode,并按需启用 Source Maps,便于定位脚本问题。最终发布包再关闭调试配置并进行独立验证。

Cocos Creator 3.8 移动端构建参数的位置

Start Scene 与 Included Scenes 不能混淆:前者决定应用启动后首先进入哪里,后者决定哪些场景参与构建。编辑器能够打开某个场景,并不代表它已经进入发布包。

为 Android 选择专属参数

Android 构建最容易出错的部分是包标识、CPU 架构、图形后端和签名。建议按照以下顺序配置。

  • Game Package Name:填写稳定且唯一的应用包名,例如 com.example.cocosdemo。后续更新应保持相同包名,并符合应用商店的标识规则。
  • APP ABI:根据目标设备选择 arm64-v8a、armeabi-v7a 等架构。若需要在 x86 系列模拟器上安装,还应检查对应 ABI 支持情况。
  • Render Backend:普通移动端项目可以先以 GLES3 作为兼容性验证基线。Vulkan 应在目标设备完成渲染与性能测试后再决定是否启用;Cocos Creator 3.8 不允许单独选择 GLES2 而不选择 GLES3。
  • Target API Level:根据当前 SDK、应用功能及目标商店要求设置。它不是手机 CPU 架构,也不能简单等同于应用支持的最低 Android 版本。
  • Orientation:与游戏设计方向一致。例如横屏游戏选择对应的 Landscape 方向,并检查 UI、摄像机和安全区域适配。
  • Use Debug Keystore:开发测试可以使用默认调试签名;正式发布必须按渠道要求配置发布签名,并妥善备份密钥。

如果需要向 Google Play 提交 Android App Bundle,可以启用 Generate App Bundle。该选项决定发布产物格式,不代表应用已经完成商店审核或上线。

还要留意 ABI 切换后的原生编译缓存。Android Studio 在未清理的情况下切换 ABI,可能让旧架构的原生库继续进入构建产物;遇到体积异常或架构混杂时,应先执行 Clean Project,再重新编译。

为 iOS 检查签名与目标系统

iOS 与 Android 共用场景和脚本资源,但原生参数不能直接照搬。选择 iOS 平台后,重点检查以下项目:

  • Bundle Identifier:使用符合 Apple 标识规则的唯一标识,并与签名配置对应。
  • Developer Team:选择实际用于签名的开发团队;真机安装还需要满足对应的签名与设备授权要求。
  • OS Target:真机测试选择 iPhone OS,模拟器测试选择 iOS Simulator。两者生成和运行的目标不同。
  • Target iOS Version:结合引擎支持范围、依赖 SDK 与目标用户设备确定,不要仅因为编译成功就认定所有旧系统都兼容。
  • Render Backend:Cocos Creator 3.8 的 iOS 图形后端为 Metal,需要在真实目标设备检查材质、阴影和后处理效果。

如果项目中集成了原生 SDK,还要确认重新构建时 Xcode 工程配置是否会被更新覆盖。涉及原生二次开发的修改应放在可维护的构建模板或工程配置流程中,而不是只修改一次临时生成目录。

完成构建、运行与首次验收

Cocos Creator 3.8 的原生构建流程分为三个主要操作:Build 生成平台项目及资源,Make 编译平台工程,Run 在对应环境中启动应用。Build 成功不等于已经得到可以在手机上安装运行的最终应用。

首次打包可以按下面的顺序执行:

  1. 保存所有场景和脚本,在构建面板检查平台、启动场景、资源范围和签名配置。
  2. 点击 Build,确认任务完成并检查构建日志。
  3. 点击 Make。Android 首次编译如需安装 Gradle 组件,可先用 Android Studio 打开生成的原生工程完成工具链配置。
  4. Android 连接开启 USB 调试的真机后运行;iOS 建议通过 Xcode 选择真实设备,完成签名并启动。
  5. 从桌面图标冷启动应用,验证首屏、场景切换、触控输入、音频、横竖屏和动态资源加载。

如果 Build 失败,优先检查场景保存状态、资源引用和构建日志;如果 Make 失败,优先检查 JDK、SDK、NDK、Gradle 或 Xcode 工具链;如果安装失败,检查签名、设备 ABI 和系统兼容性;如果安装成功却黑屏,则回到 Start Scene、资源打包范围及运行时日志。

最终至少保留一份能在目标真机上完整启动和进入核心玩法的构建版本。开发包验证功能,发布包验证资源压缩、签名和真实渠道条件,两者都通过才算完成移动端构建准备。具体选项可对照 Cocos Creator 3.8 通用构建文档 和 Android 构建选项。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

为移动平台设置构建参数

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通