Vue3中销毁Unity WebGL实例触发报错问题咨询

Unity WebGL 实例默认会向全局window对象挂载大量运行时回调、内存堆引用、事件监听，且原生Quit()方法是为整页关闭场景设计的，没有适配单页应用下DOM提前卸载、渲染上下文丢失的边界情况：

• 切换路由不做特殊处理时：承载Unity的canvas节点被Vue卸载回收，但Unity的渲染帧循环、全局事件监听仍在持续触发，找不到挂载节点就会抛出第一类报错
• 在onUnmount生命周期直接调用unityInstance.Quit()时：Vue进入onUnmount阶段时canvas节点已经被移除，Quit流程中的上下文清理步骤找不到对应的WebGL渲染上下文，就会抛出第二类报错

方案1：适配SPA场景的标准卸载流程（推荐，支持同路由重复挂载Unity） #

不要在onUnmount阶段直接裸调Quit方法，按以下顺序执行清理逻辑：

1. Unity加载完成后，单独保存三个核心引用：Unity实例本身、挂载的canvas DOM节点、canvas对应的WebGL渲染上下文
2. 组件卸载逻辑放在onBeforeUnmount阶段执行（该阶段DOM节点还未被Vue销毁，可避免大部分上下文丢失报错），第一步先终止Unity的渲染循环，阻断后续帧回调：

   if (unityInstance?.Module) {
     unityInstance.Module.shouldStopRendering = true
     cancelAnimationFrame(unityInstance.Module.animationFrameId)
   }
   

3. 手动清理全局残留的Unity事件监听，主动释放WebGL渲染上下文：

   // 清空全局挂载的Unity回调
   Object.keys(window).forEach(key => {
     if ((key.startsWith('unity') || key.startsWith('_Unity')) && typeof window[key] === 'function') {
       window[key] = () => {}
     }
   })
   // 主动释放WebGL上下文
   const gl = canvas.getContext('webgl2') || canvas.getContext('webgl')
   gl?.getExtension('WEBGL_lose_context')?.loseContext()
   

4. 最后调用Quit方法，加错误捕获忽略卸载阶段的预期内报错，清空引用触发垃圾回收：

   try {
     await unityInstance.Quit()
   } catch (err) {
     // 卸载阶段的上下文丢失报错属于预期行为，无需处理
   }
   unityInstance = null
   

方案2：iframe隔离方案（稳定性最高，无清理残留） #

如果Unity和Vue页面不需要高频双向通信，直接将Unity WebGL应用放在独立iframe中承载，组件卸载时直接移除iframe节点即可。浏览器会自动回收iframe内的所有内存、全局变量、运行时进程，完全不会有残留报错，是单页应用集成强全局依赖第三方脚本的通用兜底方案。

• Unity WebGL同一时间全局仅能存在一个运行时实例，未完全清理前重复初始化会导致内存溢出、全局回调冲突
• Unity 2020及更早版本的Quit()方法存在已知的内存泄漏问题，即使调用成功也会残留部分内存无法回收，这类版本优先选择iframe隔离方案
• 不要手动修改Unity生成的Build文件夹下的JS源码适配卸载逻辑，大版本升级Unity后适配代码会直接失效

内容的提问来源于stack exchange，提问作者Anzhari