Phaser 输入录制器：复现玩家操作、回放 Bug 和调试确定性

为什么要先做底层系统

线上玩家反馈“刚才闪避键按了但角色没动”，录屏里只能看到角色被击中，没人知道输入到底有没有进来。一个输入录制器可以把最近 30 秒的键盘、触屏、手柄和场景状态摘要保存下来，让团队用同一组输入复现问题。

输入录制不是简单记录 keydown。它要处理时间基准、场景切换、触屏 pointerId、手柄轴值、随机种子、暂停恢复和隐私边界。Phaser 层负责接收事件，录制器要把它们变成可回放的意图流。 这类系统通常不直接出现在宣传截图里，却决定项目进入内容生产后是否还能稳定迭代。本文从数据、状态、调试和验证四个角度拆解，不把问题停留在 API 调用层。

核心架构

flowchart TD
  N1["RawInput"] --> N2["InputNormalizer"]
  N2["InputNormalizer"] --> N3["FrameClock"]
  N3["FrameClock"] --> N4["InputTape"]
  N4["InputTape"] --> N5["ReplayRunner"]
  N5["ReplayRunner"] --> N6["StateSnapshot"]
  N6["StateSnapshot"] --> N7["DebugPanel"]

架构图里的 RawInput、InputNormalizer、FrameClock、InputTape、ReplayRunner、StateSnapshot、DebugPanel 要保持单向依赖。Phaser Scene 可以触发输入、播放动画和展示 UI，但不应该保存唯一规则事实。只要核心模型可以在没有 Canvas 的环境下运行，就能写测试、做批量验证，也能在玩家反馈问题时复现。

事件要先归一化

键盘、鼠标、触摸和手柄的事件形状完全不同。录制前先把它们转成 action、value、pointer、device、time 这样的统一结构。这样回放器不需要知道真实设备，只要按时间把动作重新送进输入路由。归一化还可以过滤浏览器差异，例如手柄轴的微小漂移和触屏 move 的高频噪声。

落地时建议先做最小可视化：把关键范围、状态、队列、版本或数值画出来，再接正式美术。很多系统的风险并不在第一版能不能跑，而在后续没人能解释它为什么这样跑。

时间基准要独立

不要用 Date.now 作为唯一时间源。回放要跟随游戏 tick，因此需要 FrameClock 记录逻辑帧、delta 和累计时间。暂停期间是否记录输入，要按项目规则决定。若暂停菜单也需要回放，就记录菜单输入；若只复现战斗，就在暂停期间冻结玩法时间。

落地时建议先做最小可视化：把关键范围、状态、队列、版本或数值画出来，再接正式美术。很多系统的风险并不在第一版能不能跑，而在后续没人能解释它为什么这样跑。

录制的是意图不是 DOM

直接保存浏览器事件会带来隐私和兼容问题。更好的做法是在 InputRouter 之后记录意图：moveLeft、dash、attack、aimAt。这样玩家换键位后，回放仍然表达当时的玩法操作，而不是某个物理按键。若要排查改键系统，再额外保存设备事件摘要。

落地时建议先做最小可视化：把关键范围、状态、队列、版本或数值画出来，再接正式美术。很多系统的风险并不在第一版能不能跑，而在后续没人能解释它为什么这样跑。

回放必须隔离外部状态

回放时要固定随机种子、初始场景、角色属性、关卡版本和配置版本。否则同一条输入在不同环境下结果不同，调试价值会下降。StateSnapshot 不必保存完整世界，但至少要保存复现所需的关键状态。

落地时建议先做最小可视化：把关键范围、状态、队列、版本或数值画出来，再接正式美术。很多系统的风险并不在第一版能不能跑，而在后续没人能解释它为什么这样跑。

压缩要保留语义

输入流通常很小，但触屏 move 和手柄轴会很多。可以对连续相同 action 做 run-length 压缩，对轴值按阈值采样。不要为了压缩丢掉按下和抬起边界，很多 bug 就发生在短按、连点和松手瞬间。

落地时建议先做最小可视化：把关键范围、状态、队列、版本或数值画出来，再接正式美术。很多系统的风险并不在第一版能不能跑，而在后续没人能解释它为什么这样跑。

线上导出要有边界

输入录制可能包含玩家行为习惯。导出时只保留最近短窗口，去掉聊天文本和账号信息。让玩家主动点击“发送调试记录”比默认上传更稳妥。内部测试包可以开自动保存，正式包要谨慎。

落地时建议先做最小可视化：把关键范围、状态、队列、版本或数值画出来，再接正式美术。很多系统的风险并不在第一版能不能跑，而在后续没人能解释它为什么这样跑。

调试面板要能逐帧播放

ReplayRunner 支持暂停、单帧、倍速、跳到关键事件。面板显示当前帧输入、角色状态、随机种子和最近状态差异。没有逐帧能力，回放只能看热闹；有逐帧能力，才能定位输入到底在哪一层丢失。

落地时建议先做最小可视化：把关键范围、状态、队列、版本或数值画出来，再接正式美术。很多系统的风险并不在第一版能不能跑，而在后续没人能解释它为什么这样跑。

TypeScript 实现骨架

interface RecordedInput { frame: number; action: string; value: number; device: string }
class InputTape {
  private rows: RecordedInput[] = [];
  record(frame: number, action: string, value: number, device = "keyboard") {
    this.rows.push({ frame, action, value, device });
  }
  eventsAt(frame: number) { return this.rows.filter(row => row.frame === frame); }
  serialize() { return JSON.stringify({ version: 1, rows: this.rows }); }
}
class ReplayRunner {
  frame = 0;
  constructor(private tape: InputTape, private dispatch: (action: string, value: number) => void) {}
  step() {
    for (const event of this.tape.eventsAt(this.frame)) this.dispatch(event.action, event.value);
    this.frame += 1;
  }
}

代码骨架只表达核心边界。真实项目里还需要配置 schema、错误码、日志字段、调试开关和测试样例。重点是把不稳定的浏览器事件、动画状态和资源加载结果转换成可记录的业务状态。

落地步骤

1. 先写纯数据模型和两组固定样例，不启动 Phaser 也能跑通。
2. 接入 Phaser 输入或加载流程，但只提交意图，不直接改深层状态。
3. 增加开发面板，显示当前状态、最近事件、失败原因和配置版本。
4. 准备边界测试，包括暂停、切后台、重复点击、读档、低端机降级。
5. 给内容团队留校验入口，让错误配置在发布前暴露。

边界测试

边界测试要覆盖三类情况：第一类是玩家快速操作，例如连点、跳过动画、重复进入场景；第二类是环境变化，例如断网、切后台、设备降频、WebGL 上下文丢失；第三类是内容错误，例如缺失资源、非法 id、过长文本、不可达路径。每个失败都应该返回可读原因，而不是让 Scene 静默停住。

调试与观测

建议记录录制窗口长度、输入事件数量、压缩比例、回放是否分叉、分叉发生帧和场景版本。若回放经常分叉，优先检查随机数、物理 delta 和外部配置。 如果这些指标只能靠人工观察，就很难在内容扩张后保持质量。建议至少在开发包中支持一键导出最近事件，让 QA 的反馈从“这里怪怪的”变成一份可复现记录。

工程化扩展

输入录制器 做到能用之后，下一步要把它变成团队能长期依赖的工具。首先是配置版本化：任何影响规则的字段都要有 schemaVersion，旧配置进入系统前先迁移或拒绝。其次是错误码标准化：不要只抛出 Error，而是返回能被 UI、日志和测试同时使用的 reason。第三是调试入口固定化：开发包里应该有一个稳定按钮或快捷键打开面板，而不是临时在 Scene 里写几行 console。最后是文档化，把字段含义、默认值、边界行为写在内容团队能看到的位置。底层系统一旦没有文档，就会被误用；被误用后再追查，成本远高于一开始写清楚。

验收场景

验收时建议至少覆盖这些场景：键盘短按、触屏拖拽、手柄轴漂移、暂停菜单输入、场景切换后的第一帧输入。每个场景都要记录 录制窗口、帧号、归一化 action、随机种子和状态摘要。如果测试失败，报告里应能看出失败发生在输入层、规则层、资源层还是表现层。移动端还要额外检查切后台、恢复音频、低电量降频和触摸误差。桌面端则要检查窗口缩放、键鼠和手柄切换。验收标准不是“没有报错”，而是系统在异常路径上仍能给出稳定、可解释、可恢复的结果。

发布前检查

发布前确认：front matter 与路由一致，配置版本可识别，关键状态可存档恢复，动画跳过不影响结算，低画质不改变规则，调试入口能关闭。若系统涉及奖励、排行榜或玩家资产，还要检查幂等 id 和重复提交保护。

团队协作方式

输入录制器 不是某一个 Scene 的私有逻辑，最好从第一天就明确负责人和数据边界。程序负责 玩家操作、输入路由、随机种子、场景状态 的结构和校验，策划或内容团队负责具体配置，QA 负责边界用例和回归记录。每次字段变更都要能回答三个问题：旧内容怎么迁移，错误配置在哪里报出，玩家存档是否受影响。若答案不清楚，就不要把字段直接塞进线上配置。实际项目里，许多事故不是算法不会写，而是字段含义没人维护，某个活动临时复制旧配置后触发了隐藏分支。

协作时还要准备一份最小样例库。样例库不追求覆盖所有玩法，而是保留最能说明规则的几个状态：一个正常状态、一个边界状态、一个故意错误状态。开发调系统时用它，QA 回归时用它，内容团队学习配置时也用它。这样讨论会从“我觉得这里不对”变成“样例 B 的第三步发生了变化”。对底层系统来说，这种共同语言比任何口头约定都可靠。

回归策略

输入录制器 每次改动后都应该至少跑一次轻量回归。回归不一定是完整自动化，但必须可重复：固定输入、固定配置、固定期望输出。重点检查 回放分叉 是否再次出现。若系统参与奖励、存档、热更新、设备适配或输入路由，还要额外检查重复提交、读档恢复、切后台恢复和低端机降级。很多 Phaser 项目的问题并不是首次实现失败，而是后续某次“顺手优化”改变了隐含行为。把这些隐含行为写成回归清单，才能让系统长期稳定。

回归结果最好能留下短摘要，例如用 JSON 记录通过用例、失败原因、配置版本和客户端版本。摘要不需要复杂平台，放在开发日志或 QA 附件里就能发挥作用。等项目进入高频内容生产阶段，这些摘要会成为判断问题归属的证据：是这次配置错了，是引擎层变了，还是某个设备档位才会失败。没有证据时，团队往往会把时间花在互相复现上。

上线风险与降级

输入录制器 上线前要准备降级策略。降级不是承认系统不可靠，而是承认真实环境会比测试环境复杂。可以禁用某个高级表现、回退到旧配置、缩短录制窗口、降低资源档位、关闭某个活动入口，或者把待确认奖励标记为 pending。关键是降级后规则仍然一致，玩家不会丢进度，也不会获得重复收益。降级开关应集中管理，并写入日志；否则临时开关越多，后续越难知道线上到底运行在哪种状态。

最后要给客服或运营留一段能读懂的状态描述。玩家不会说“manifest hash mismatch”或“gesture capture owner error”，他们只会说打不开、没反应、奖励没到。系统内部的错误码需要映射成可沟通的解释，例如资源更新失败、输入被弹窗拦截、奖励等待联网确认。这个映射越早设计，线上问题越容易被正确分流。

常见误区

不要把工具系统写成一次性调试代码。越底层的系统越会被长期依赖，命名、日志和错误码都要认真。也不要为了短期省事绕过统一入口，例如某个 Scene 直接 Math.random、某个按钮直接发奖励、某个资源直接从远程 URL 加载。这些捷径都会在回放、热更新或低端机适配时变成维护成本。

结语

输入录制器：复现玩家操作、回放 Bug 和调试确定性 的目标不是让代码显得复杂，而是让复杂问题可解释、可复现、可回滚。Phaser 足够灵活，既能快速搭玩法，也能支撑工具化工程；关键是从第一版就把规则层和表现层的边界立住。