跳到主要内容

可复现证据与游戏故障定位

适用:引擎无关的诊断方法,示例面向 Cocos Creator 3.8.8 + TypeScript。资料核查:2026-11-17。浏览器工具用于共享逻辑诊断,微信与真机问题需对应环境证据。

把“不能玩”改写为一个偏差​

有效故障描述包含预期与实际的差异,以及发生在什么状态。比如“进入第二关加载中返回大厅,约一秒后又进入第二关”,比“场景切换有 bug”更能定位原因。先记录构建标识、前置存档、输入顺序、复现概率和最早异常,暂时把原因假设放在另一栏。症状与推测混在一起,会让后续排查过早锁定错误方向。

游戏同时包含模拟、表现、输入、资源与网络,分层观察能减少猜测。角色不动时,先看输入是否进入,再看模拟位置是否变化,最后看节点投影是否更新。生命值下降但血条没变是表现订阅问题;输入没有进入可能是遮挡或焦点;模拟停止则查局阶段和暂停来源。不要一开始就在所有 update 中增加日志。

为关键流程建立时间线​

加载、登录、入房、结算和广告都应有稳定的流程标识与阶段。记录 started、resourceReady、modelCreated、interactive、finished 等阶段及耗时,异步回调同时记录场景世代或操作标识。日志能说明发生了什么,不应每次输出整个节点或平台响应。大量对象日志不仅昂贵,还可能让控制台保留对象,改变内存观察。

type Diagnostic = {
build: string;
flowId: string;
phase: string;
sceneEpoch: number;
elapsedMs: number;
code?: string;
};
// 仅记录允许字段;令牌、临时 code、密钥和个人资料不进入诊断事件。

客户端与服务端用 operationId、runId 等关联业务结果,必要时在后端链路中使用 trace/span。客户端时间不应直接与服务端墙钟相减当作精确单向耗时;分别记录本地持续时间与服务端处理时长。一个“提交后响应丢失”的案例,只有两端关联起来才能确认已执行,而不是继续在客户端重复提交。

断点适合看状态,日志适合看时序​

在异常抛出、状态转移与资源回调处设置断点,检查调用栈、局部变量和当前所有者。条件断点帮助缩小到某个实体或某个 tick;不应每帧暂停全部世界。断点会改变时间,网络和竞争问题可能因此消失,此时用小体积结构化事件或可控替身复现更合适。

压缩包报错需要与产物匹配的 Source Map,不能拿最新源码映射旧包。先确认构建身份,再还原栈;若只有发布模式失败,比较压缩、资源合并、初始化与动态访问假设。开发模式正常是重要线索,但不是“平台有问题”的证明。原生调试文档中的连接方式也不能直接套用到微信。

最小复现保留导致失败的条件​

从实际缺陷逐步移除无关内容,而不是重写一个看似相同的例子。黑屏可先保留入口、目标资源和最小脚本;碰撞问题保留速度、步长、碰撞体和接触顺序;异步问题保留完成顺序和退出时点。每移除一项都确认故障仍存在,最后得到能稳定触发的最小工程或纯数据案例。

复现需要初始状态。随机种子、存档版本、设备画质、冷缓存与账号权限都会改变结果。不要只发一段录像让别人猜存档。缺陷附件包含必要数据,但移除密钥与个人信息;对无法公开的服务端条件,用受控替身表示行为,并注明替身与真实环境的差异。

用二分与对照缩小范围​

近期回归可以比较最后正常与首次异常的版本,再按变更范围缩小。只有资源变更也可能影响性能、碰撞与加载,所以不能只检查 TypeScript diff。两个相似场景中一个正常、一个异常时,比较组件启用、层、材质、锚点与资源引用。先确认数据差异,再考虑引擎缺陷。

一个常见案例是对象池子弹重新出现后追踪旧敌人。证据应包括取出时的目标标识、归还时清理、重新绑定顺序,以及敌人是否已复用。修复不是加一个“如果目标无效就 return”,而是让池对象在归还和取出时满足完整状态契约。回归测试重复复用同一对象,才能说明根因已覆盖。

排除替代解释,再写修复结论​

某次改动后问题消失,可能是重新构建清缓存、改变时序或碰巧没有触发。写出根因链:什么输入或状态违反了什么假设,如何导致可观察症状,修复在哪个边界阻止它。再用原复现步骤和相邻边界验证,例如返回后迟到结果被忽略,同时正常等待结果仍能进入场景。

不要以吞掉异常作为默认修复。捕获后至少明确该操作失败、清理进行中状态并提供恢复;否则错误只是从控制台转成永久加载。日志采样与去重要保护可用性,但保留第一次关键错误及流程标识。玩家反馈入口可以显示脱敏诊断码,便于客服关联具体运行。

保存最早错误与后续症状的关系​

资源加载失败后可能紧接着出现空引用、界面未初始化和持续重试;真正根因只有第一处,后面是状态已经损坏的结果。日志按流程关联后,先找到首次不满足契约的阶段。修复根因时也应让后续阶段在前置失败后停止,避免同一错误放大成大量无关异常,使下一次诊断更困难。

还要保留一个反例:同一构建在正常条件下怎样成功。将成功与失败时间线对齐,找出第一处分叉,比逐行阅读整套项目更快。对偶发问题记录发生率与尝试次数;一次未复现不能写成已修复。复测需要覆盖原条件,并解释为何修复会阻断已确认的因果链。

交给 AI 的任务与验收​

可复制任务:“现象:加载第二关时返回大厅,旧请求完成后仍切入关卡。请先列三条原因假设及所需证据,增加最小阶段日志,用可手动完成的加载替身复现。修复后验证正常进入、返回、再次进入和旧请求最后完成四种顺序。不要同时重构其他系统。”

验收先能稳定触发故障,再看到原步骤通过;日志证明旧回调因世代过期被拒绝;正常流程不受影响;无敏感数据;最终说明根因、修改边界与验证环境。若只在设备上偶发,明确尚未排除的条件,不能用推测写成确定结论。

官方来源​