Phaser 4 Debugger 是一个用于诊断和修复 Phaser 4 问题的技能，核心理念是基于证据而非猜测来定位和解决问题。
用途 当用户报告 Phaser 4 的 bug、黑屏、精灵缺失、碰撞失败、物理异常、动画问题、崩溃或控制台报错时，可使用该技能进行系统化排查。
工作流程
- 收集确切症状、错误文本、堆栈跟踪、浏览器/设备上下文以及可用的复现步骤。
- 在编辑前先阅读相关代码。对于黑屏，检查 src/main.ts、场景注册、场景切换、preload 路径以及浏览器控制台/网络错误。
- 按照 Phaser 生命周期顺序追踪可能的根因：config、preload、create、update、资源键、物理体创建、碰撞、输入、场景启动/停止状态以及渲染深度。
- 做能解决根因的最小修复。
- 使用 npx tsc --noEmit 验证 TypeScript 项目，并在可行时进行本地开发服务器冒烟测试。
调试检查清单
- 资源 404 与纹理键不匹配
- 场景未注册或场景键错误
- 在场景初始化前使用 this.physics、this.input 或 this.anims
- 对象创建时未启用物理，导致 Arcade 物理体缺失
- 碰撞器/重叠注册到了错误的对象或组
- 动画键/帧不匹配
- 深度/透明度/相机边界隐藏了对象
- 升级到 Phaser 4 后仍使用 Phaser 3 API
- 每帧分配、无界组以及缺少对象池
- 定时器事件未跟踪——time.addEvent() 未保存引用，在场景重启时会累积
- 物理组未显式销毁——进化武器组和生成阶段组若未 clear(true,true) + destroy() 会泄漏
- 属性变更未使用 base+modifiers——两个系统在同一帧写入同一属性会产生竞态值
- 通知去重使用字符串相等——会丢弃合法的快速重复事件（例如 200 毫秒内两次拾取金币）；应使用时间窗口去重
- 覆盖层/面板背景使用模块级常量设定尺寸——在启动尺寸处冻结；应使用 this.cameras.main.width/height + resize 监听器
常见静默失败类别 当游戏冻结或行为异常但没有控制台错误时，在查阅 references/agent-guidance.md 中的完整指南之前，可使用以下快速诊断路径。
静默冻结（无错误）： 在 new Phaser.Game(config) 之前添加到 main.ts： window.onerror = (msg, _src, _line, _col, err) => { console.error('GLOBAL ERROR:', msg, err?.stack); }; window.onunhandledrejection = (ev) => { console.error('UNHANDLED REJECTION:', ev.reason); }; 然后强制刷新。任何之前静默的失败现在都会记录日志。完整检查清单见 references/agent-guidance.md → Silent Freeze。
生成中途停止（无错误）： 池槽泄漏——实体离开相机视野时未回收其槽位。在生成调用中添加 console.log('pool free:', pool.getTotalFree())。如果它降为零并保持不变，说明某个槽位被占用。见 references/agent-guidance.md → Pool Slot Leak。
强制动画播放一帧后回退： 实体的 update() 在一个 tick 后覆盖了强制动画。使用 cinematicMode 标志修复。见 skills/phaser-animation/references/state-machine-patterns.md。
速度或属性间歇性跳到错误值： 两个系统在同一帧修改同一属性。使用 base+modifiers 模式。见 references/agent-guidance.md → Race Between Two Systems。
卡住实体检测误触发（假阳性或假阴性）： body.velocity 在推墙时返回 0。改用位置增量采样。见 references/agent-guidance.md → Stuck Detection Fails。
完整指南 完整的诊断手册请阅读 references/agent-guidance.md。它复制自 Claude 子代理定义，但应作为可移植技能应用；忽略仅适用于 Claude 的字段，如 model、color 和 tools。