游戏引擎 / 系统课时
建立一套排障记录方法
建立一套排障记录方法
这一课把“游戏偶尔出错”整理成可重复执行的排障闭环。以 Cocos Creator 3.8 中一次拾取被重复计分为例,学习怎样留下环境、步骤与日志证据,再用相同条件判断修复是否真正生效。
学习目标
- 将模糊现象写成包含预期、实际、环境与复现步骤的问题记录。
- 用固定输入和可定位的日志缩小故障范围。
- 按“定位—最小修复—同条件验证”保存可追溯的处理结果。
把现象写成可复现的问题单
不要只记录“金币有时会加两次”。排障记录至少要回答:哪里发生、怎样触发、应该怎样、实际上怎样。同时保存 Cocos Creator 版本、目标平台、场景、构建模式和相关日志,避免不同运行环境的结果混在一起。
| 记录项 | 示例内容 |
|---|---|
| 问题标识 | COIN-DOUBLE(团队自定编号) |
| 环境 | Cocos Creator 3.8、浏览器预览、Main 场景 |
| 预期与实际 | 同一拾取通知计分一次;重复送达时计分两次 |
| 最小复现 | 将金币清零,再连续处理同一个通知标识两次 |
| 证据 | Console 中通知标识、处理次数、修改前后分数 |
复现步骤必须写成别人可以照做的动作,而不是“多试几次”。偶发问题还应记下尝试次数、成功复现次数及触发时机;无法稳定复现时先保留现场,不要急于修改代码。
按证据推进而不是凭感觉改
先用同一份构建和同一组输入确认问题;再沿“输入事件→事件监听→业务更新→HUD 显示”逐层查看。日志要有能够串起同一次动作的标识,这样才能区分事件确实处理两次,还是状态只改一次、界面却刷新两次。

定位时一次只修改一个可疑因素,记录修改前的证据。如果问题只发生在小游戏真机上,应保留设备、系统与基础库信息,在真实目标环境复测;编辑器预览通过不等于发布平台通过。
用固定输入演示修复前后对照
下面的组件在 start() 中模拟“同一拾取通知被传入两次”。第一轮不做保护,第二轮按通知标识去重,并输出验收结果。新建 IssueRecorder.ts,挂到测试场景的一个启用节点后运行即可。
import { _decorator, Component, log } from 'cc';
const { ccclass } = _decorator;
@ccclass('IssueRecorder')
export class IssueRecorder extends Component {
start(): void {
const events = ['pickup-A', 'pickup-A'];
let before = 0;
// 固定输入用于对照修复前后,而不是依赖偶然复现。
for (const eventId of events) {
before += 1;
log(`[before] id=${eventId} coins=${before}`);
}
const handled = new Set<string>();
let after = 0;
for (const eventId of events) {
// 只有相同业务事件允许被重传时,才能按稳定 ID 去重。
if (handled.has(eventId)) {
log(`[after] skipped id=${eventId}`);
continue;
}
handled.add(eventId);
after += 1;
log(`[after] id=${eventId} coins=${after}`);
}
log(`[check] ${after === 1 ? 'PASS' : 'FAIL'}`);
}
}预期输出(仅列组件打印的消息,Console 可能附带引擎日志前缀):
[before] id=pickup-A coins=1
[before] id=pickup-A coins=2
[after] id=pickup-A coins=1
[after] skipped id=pickup-A
[check] PASS这里的 pickup-A 是固定测试标识,并非引擎自动生成的事件 ID。若真实根因是监听重复注册,应在对应生命周期解除多余订阅;单靠去重可能遮住错误。若确实存在消息重传,再考虑由业务层维护已处理标识。
给问题留下可复查的结论
修复后重跑原始步骤,再测正常连续拾取、切换场景后重新进入、节点启停等相邻路径。每一项都要写明测试环境与通过条件,不要只填“已解决”。
最终记录包括根因定位、修改的脚本或提交标识、修复前后关键日志、验证平台与仍未覆盖的条件。只有在原缺陷不再复现、预期行为验证通过、相邻功能无回归时,才把问题状态改为已关闭。