Three.js 浏览器游戏调试与性能剖析：定位空白画布…

当 Three.js 游戏出现空白画布、渲染或运行时错误、资源/音频加载、动画、输入、移动端或性能问题时，按顺序排查根因并基于实测数据优化。

适用场景

解决思路

1. 遵循改动行为的范围；复用负责人已有的复现步骤和证据，修复后验证受影响的路径；聚焦检查通过后，仅在共享行为发生变化或存在未解决风险时才需要更广泛的测试；将测量结果和缺陷交回负责人进行统一验证。
2. 阅读 references/debug-playbook.md，其中包含空白画布、资源与音频加载、循环/动画/物理、输入与移动端的有序排查流程、性能剖析顺序，以及 __THREE_GAME_DIAGNOSTICS__ 的结构；在调试或剖析任何非显而易见的问题时阅读它。
3. 调试：用与用户相同的命令和 URL 在本地复现。
4. 调试：阅读 console、page 和 network 错误。
5. 调试：检查 canvas 显示尺寸与绘制缓冲区（drawing-buffer）尺寸是否一致。
6. 调试：检查 renderer、context 和循环所有权——存在多个活动循环是常见原因。
7. 调试：检查相机 aspect、near/far、灯光、材质、雾、场景内容、变换。
8. 调试：检查资源路径、加载器、CORS 和 base path。
9. 调试：检查动画 delta 单位、物理更新顺序与固定时间步长、碰撞体与刚体所有权、输入监听器、指针与触摸行为、resize，以及涉及音频时的 audio context 解锁。
10. 调试：在拥有该问题的模块中修复根因，然后重新测试确切的出错路径。
11. 剖析：在正确的构建模式下复现——当面向用户的性能重要时，使用生产预览（production preview）。
12. 剖析：建立场景基线：FPS 与帧时间、draw calls、三角形数、几何体数、纹理数、内存、bundle。
13. 剖析：将瓶颈分类为 CPU、GPU draw、GPU fragment、GPU vertex、内存或网络。
14. 剖析：一次只改一件事——instancing、共享资源、culling、LOD、DPR 上限、更便宜的阴影或后处理、纹理规范。
15. 剖析：重新测量同一场景，并确认视觉效果和可玩性保持不变。
16. 报告：先给出根因或实测瓶颈；然后列出更改的文件、基线与优化后指标、命令、截图、重新测试的出错路径，以及残余风险。