跳到主要内容

常见问题

本文档统一收敛 Web 原生与 Unity-WebGL 在作品/模版开发中的常见错误。

Web 原生 · 作品开发​

  • init 未完成就触发 ready，平台会提前进入可开始状态。
  • ready 漏发，平台一直等待，用户无法开始。
  • start 前开放输入，导致状态错位（用户可操作但运行态未就绪）。
  • end 重复上报，出现重复结算或重复回调。
  • 异步加载失败没有兜底，页面停留在"未 ready"悬挂态。

Web 原生 · 模版开发​

  • craft 字段名与运行时代码不一致（大小写、命名、层级）。
  • init 收到 craft 后未做默认值处理，导致空字段崩溃。
  • Schema 和 craft 实际结构不一致（字段类型、required 不匹配）。
  • ready 在 craft 渲染完成前触发，平台侧时序异常。
  • end 上报缺少关键字段（如分数、状态），后续流程消费失败。

Unity-WebGL · 作品开发​

  • OnMiniInit 没有解析到有效参数，仍继续流程。
  • ready 漏发，宿主始终不触发 start。
  • OnMiniStart 未做幂等控制，重复触发导致状态异常。
  • end 未做单次保护，可能重复上报。
  • WebGL 模板资源路径写法错误（大小写/相对路径），导致导出后白屏或 404。

Unity-WebGL · 模版开发​

  • init 阶段未处理 craft，启动后参数丢失或展示默认内容。
  • Schema 更新后未同步 C# 数据结构，反序列化失败或字段缺失。
  • ready 在资源装配前触发，start 后立刻报错。
  • end 上报缺少业务结果字段，平台无法正确结算。

快速排查顺序​

  1. 先看信号量顺序是否正确：init -> ready -> start -> end
  2. 再看 craft / 初始化参数是否完整、字段是否匹配
  3. 再看资源路径与构建产物是否齐全（尤其 WebGL 导出）
  4. 最后看结束上报是否幂等且字段完整