游戏引擎 / 系统课时
用真机复现编辑器外问题
用真机复现编辑器外问题
游戏在 Cocos Creator 编辑器中正常运行,并不保证它在移动设备上同样正确。屏幕适配、触控、原生资源加载和 GPU 渲染都可能只在特定环境暴露问题。本课建立从编辑器预览到真机原生包的验证顺序,用稳定复现步骤和运行日志区分平台差异与业务逻辑错误。
学习目标
- 区分编辑器预览、桌面模拟器、手机浏览器预览和真机原生运行的验证范围。
- 在 Cocos Creator 3.8 中记录运行环境和可见区域,收集可对照的故障证据。
- 根据跨环境表现缩小故障范围,并验证修复没有引入新问题。
按运行环境逐级缩小问题
不要一发现真机异常就直接修改业务代码。先在不同环境执行相同操作,确认问题究竟从哪个阶段开始出现。
建议采用以下验证顺序:
- 编辑器与桌面浏览器预览:检查基本场景引用、脚本错误、资源加载和主要玩法逻辑。这里反馈速度快,适合排除普遍存在的业务问题。
- Cocos Simulator:在桌面模拟运行环境中检查部分原生行为和运行差异。它不是目标手机,也无法替代真实设备的 GPU、触控和系统限制。
- 手机浏览器预览:让手机与开发电脑处于同一局域网,通过编辑器提供的预览地址或二维码打开项目。重点检查移动端输入、布局、浏览器图形支持和加载表现。
- 真机原生调试包:使用 Android APK 或 iOS 应用在实际设备运行,检查原生图形后端、文件访问、系统生命周期、资源加载和设备兼容性。
这里的 Cocos Simulator 是编辑器提供的桌面模拟运行环境,不等同于 Android Emulator 或 Xcode 的 iOS Simulator。手机浏览器预览也仍然属于 Web 运行环境,不能证明原生应用行为正确。

逐级验证的目的不是要求每种环境都先完全通过,而是记录同一问题在不同运行时中的表现。只有明确了差异出现的位置,后面的排查才有方向。
固定复现条件并记录运行状态
同一个问题如果每次使用不同设备、不同构建参数或不同操作路径,就很难判断修复是否有效。建议先建立可重复的测试条件,并一次只改变一个变量。
需要记录的最小信息包括:Cocos Creator 具体版本、构建任务与 Debug 状态、设备型号、操作系统版本、屏幕方向、网络状态、起始场景,以及从启动到异常出现的操作顺序。
为了对比不同运行环境,可以给启动场景增加一个轻量诊断组件。在 assets/scripts 中创建 DeviceProbe.ts,写入下面的完整组件,并将它挂到启动场景中处于激活状态的节点上。
import { _decorator, Component, log, sys, view } from 'cc';
const { ccclass } = _decorator;
@ccclass('DeviceProbe')
export class DeviceProbe extends Component {
start() {
// 记录运行平台,区分 Web 预览与原生包。
log(`[Probe] os=${sys.os} native=${sys.isNative} mobile=${sys.isMobile}`);
// 记录可见逻辑尺寸,辅助排查屏幕适配问题。
const size = view.getVisibleSize();
log(`[Probe] visible=${Math.round(size.width)}x${Math.round(size.height)}`);
}
}预期输出(动态字段示意):
[Probe] os=<OS> native=<BOOL> mobile=<BOOL>
[Probe] visible=<WIDTH>x<HEIGHT>其中 <OS> 为实际操作系统,<BOOL> 为布尔值,<WIDTH> 和 <HEIGHT> 是当前可见区域的逻辑尺寸,具体数值取决于设备及视图配置。sys.isNative 有助于确认程序是否在原生环境运行,sys.isMobile 则用于区分移动与非移动设备;二者不应混为一谈。
这段组件运行后无需修改原有玩法逻辑。分别在浏览器预览、模拟环境与原生调试包中观察输出,即可建立一组可比较的环境记录。
从真机获取日志与错误证据
当问题只在原生应用中出现时,编辑器控制台未必能得到完整信息。应直接从目标设备收集日志,并让日志与复现步骤对应。
Android 可以通过 Android Studio 的 Logcat 查看目标进程,也可以在连接设备后通过终端持续采集运行日志:
# 先确认 ADB 能识别目标设备
adb devices
# 在另一个终端持续查看设备日志,复现完成后按 Ctrl+C 停止
adb logcat -v time预期结果:
List of devices attached
<ID> device
<TIME> <PROCESS_INFO> <LOG_LEVEL> <TAG>: <MESSAGE>以上为两条命令输出的结构示意,并非固定日志文本。<ID>、<TIME>、进程信息、日志级别、标签及内容均取决于实际设备与运行过程。日志还可能包含其他应用和系统消息,实际排查时应根据应用进程、时间范围或诊断标记过滤。
在 Android Studio 中也可以直接查看构建应用的运行日志。iOS 原生应用则建议通过 Xcode 在连接真机后启动并查看调试控制台。
如果需要定位 TypeScript 源码中的调用位置,可以在构建面板启用 Debug Mode 和 Source Maps,再按 Cocos Creator 3.8 的 原生 JavaScript 调试说明 连接远程调试器。原生远程调试需要满足设备网络可达及对应调试服务已启动等条件。
有效的证据通常至少包含三个部分:异常前最后一个成功执行的步骤、异常出现时的错误或警告、异常发生后的状态。没有错误日志时,也应记录实际画面、输入是否仍然生效,以及应用是否退出或卡住。
根据环境差异判断故障归属
拿到同一组复现步骤在多个环境下的结果后,可以先按现象分类,再验证假设,而不是直接认定某个平台有缺陷。
| 观察到的现象 | 优先排查方向 |
|---|---|
| 编辑器和真机都失败 | 业务条件、空引用、事件顺序、资源标识 |
| 桌面预览正常,移动浏览器失败 | 触摸输入、浏览器能力、视图尺寸、资源请求 |
| 浏览器正常,原生模拟环境失败 | 原生运行时差异、平台接口、资源访问 |
| 只有特定真机的原生包失败 | GPU 图形后端、ABI、系统版本、权限、设备能力 |
| Debug 正常,Release 异常 | 压缩与构建差异、资源遗漏、依赖未声明、仅调试环境存在的行为 |
例如,Android 真机启动后黑屏,而桌面浏览器与模拟环境正常,可以先确认日志中是否有着色器编译错误或资源加载失败。接着检查是否启用了 Vulkan、目标手机是否支持所选图形能力,以及对应资源是否实际进入构建产物。
如果只在 Android 上找不到某个文件,应检查路径大小写。Android 文件系统中的路径匹配通常区分大小写,编辑器所在系统可能没有暴露同样的问题。
如果只有游戏切入后台再恢复后出现异常,则要记录切换前后的场景状态、音频状态、输入状态和资源引用,而不是只检查启动过程。此类问题可能涉及应用生命周期与业务状态恢复的共同作用。
用最小改动完成修复与回归
确定可疑原因之后,先构建最小修复版本,不要同时修改渲染、资源加载、UI 适配和脚本逻辑。每次只改变一个条件,保留前后两次的构建参数和日志,才能判断问题是否真正解决。
建议按下面的顺序完成验证:
- 在原先发生故障的同一台设备上,使用相同步骤确认问题能够稳定复现。
- 修改一个明确的原因,例如修正资源路径大小写,或者将待验证的图形后端切换为 GLES3。
- 重新构建、安装和冷启动,保持其余测试条件不变。
- 按原复现步骤验证,再覆盖场景切换、暂停恢复、前后台切换和连续运行等邻近场景。
- 在另一台具有不同系统版本或 GPU 的目标设备上复测,确认修复没有依赖单一机型。
一次有效的真机排障最终应该得到可复现的操作步骤、明确的设备与构建环境、修复前后的日志证据,以及在原故障设备上的回归结果。编辑器预览负责快速发现通用错误,模拟环境帮助缩小差异,最终仍要由目标真机和实际发布配置确认运行可靠性。