Web 图形与 3D / 系统课时

WebGL 上下文丢失如何恢复

WebGL 上下文丢失如何恢复

当浏览器重置 GPU、显存紧张或设备切换导致 WebGL 上下文丢失时,展厅画布可能突然变空。本课实现一套可验证的恢复流程:监听事件、暂停绘制、恢复后检查画面,并在无法恢复时展示静态产品预览。

学习目标

  • 区分上下文丢失、恢复与首次创建失败,知道各自的处理时机。
  • 使用 Three.js 监听事件并模拟故障,验证场景能否继续渲染。
  • 为恢复超时和初始化失败提供用户可见的静态预览。

识别故障与恢复边界

webglcontextlost 和 webglcontextrestored 都在 renderer.domElement(画布)上触发,而不是在 scene 上触发。丢失后旧的 WebGL 纹理、缓冲区和程序对象无效;恢复事件到来前不能假定 GPU 可用。

Three.js WebGLRenderer 在支持的版本中会监听上述事件并重建内部 WebGL 状态,随后按需重新上传其管理的几何体、材质和纹理资源。应用仍要负责暂停自己的动画循环、恢复业务交互,以及重建绕过 Three.js 直接创建的原生 WebGL 资源。不要在事件中每次都重新创建 WebGLRenderer,否则可能制造更多上下文。

上下文丢失与恢复状态迁移

实现可运行的恢复演示

下面以 Three.js r180(npm 版本 0.180.0)为例。保存为 index.html;示例通过 CDN 导入库,需要联网并通过本地 HTTP 服务打开。静态预览由页面自身的 HTML/CSS 提供,即使 WebGL 创建失败也能显示;正式产品可替换为预先准备的产品封面图。

html
<!doctype html>
<html lang="zh-CN">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>WebGL 上下文恢复</title>
  <style>
    body { font: 16px system-ui; padding: 20px; }
    #viewer { width: 640px; height: 360px; max-width: 100%;
      position: relative; background: #eef2f6; }
    #viewer canvas { width: 100% !important; height: 100% !important; display: block; }
    #preview { position: absolute; inset: 0; display: grid; place-content: center;
      text-align: center; background: #e4edf2; }
    #preview[hidden] { display: none; }
    button { margin: 12px 8px 0 0; }
  </style>
</head>
<body>
  <div id="viewer">
    <div id="preview" hidden role="status">
      <strong>产品静态预览</strong><p id="hint"></p>
    </div>
  </div>
  <p id="status">初始化中</p>
  <button id="lose">模拟丢失</button>
  <button id="restore">模拟恢复</button>
  <script type="module">
    const viewer = document.querySelector('#viewer');
    const preview = document.querySelector('#preview');
    const hint = document.querySelector('#hint');
    const status = document.querySelector('#status');
    let renderer, cube, scene, camera, frameId = 0, lost = false, timeoutId;

    function showPreview(message) {
      preview.hidden = false;
      hint.textContent = status.textContent = message;
    }
    function animate() {
      if (lost) return;
      cube.rotation.y += 0.01;
      renderer.render(scene, camera);
      frameId = requestAnimationFrame(animate);
    }

    try {
      const THREE = await import('https://cdn.jsdelivr.net/npm/three@0.180.0/build/three.module.js');
      renderer = new THREE.WebGLRenderer({ antialias: true });
      renderer.setSize(640, 360);
      viewer.prepend(renderer.domElement);
      scene = new THREE.Scene();
      scene.background = new THREE.Color(0xf5f7fb);
      camera = new THREE.PerspectiveCamera(45, 640 / 360, 0.1, 100);
      camera.position.z = 4;
      cube = new THREE.Mesh(new THREE.BoxGeometry(1.5, 1.5, 1.5),
        new THREE.MeshNormalMaterial());
      scene.add(cube);

      renderer.domElement.addEventListener('webglcontextlost', (event) => {
        event.preventDefault(); // 允许浏览器后续尝试恢复
        lost = true;
        cancelAnimationFrame(frameId);
        showPreview('图形上下文已丢失,等待恢复');
        clearTimeout(timeoutId);
        timeoutId = setTimeout(() => {
          if (lost) showPreview('8 秒仍未恢复,可使用静态预览或刷新页面');
        }, 8000); // 8秒只是本例的产品提示阈值
        console.log('APP: lost');
      });

      renderer.domElement.addEventListener('webglcontextrestored', () => {
        clearTimeout(timeoutId);
        lost = false;
        try {
          // Three.js 的内部恢复监听器先于此处注册
          renderer.setSize(640, 360);
          renderer.render(scene, camera);
          preview.hidden = true;
          status.textContent = '3D 已恢复';
          console.log('APP: restored', renderer.getContext().isContextLost());
          animate();
        } catch (error) {
          lost = true;
          showPreview('恢复后渲染失败,请使用静态预览');
          console.error(error);
        }
      });
      status.textContent = '3D 正常';
      animate();
    } catch (error) {
      showPreview('3D 依赖加载或 WebGL 初始化失败,请使用静态预览');
      console.error(error);
    }

    document.querySelector('#lose').onclick = () => {
      if (!renderer || lost) return;
      if (!renderer.getContext().getExtension('WEBGL_lose_context')) {
        status.textContent = '浏览器不支持模拟上下文丢失';
        return;
      }
      renderer.forceContextLoss(); // 仅用于故障注入
    };
    document.querySelector('#restore').onclick = () => {
      if (renderer && lost) renderer.forceContextRestore();
    };
  </script>
</body>
</html>

预期结果:通过本地 HTTP 服务打开后,画布显示旋转方块;故障时覆盖显示静态预览,恢复后回到 3D 画面。若 3D 依赖加载失败或 WebGL 无法创建,则保留预览并显示错误提示。

用 Python 3 在 index.html 所在目录启动静态服务:

bash
python3 -m http.server 8000

预期结果:终端显示 HTTP 服务正在监听 8000 端口(绑定地址随系统而异)。访问 http://localhost:8000/index.html,应看到旋转方块和“3D 正常”;点击“模拟丢失”后出现静态预览,再点“模拟恢复”则恢复旋转并显示“3D 已恢复”。控制台中应用自定义日志依次为:

text
APP: lost
APP: restored false

其中 false 是恢复事件后的 isContextLost() 返回值;Three.js 还可能打印自身的上下文状态日志。浏览器没有 WEBGL_lose_context 扩展时不能使用这两个测试按钮,不等于真实上下文不会丢失。

验证恢复后的渲染状态

收到 webglcontextrestored 只说明浏览器恢复了上下文,不代表产品页面全部恢复。按下列顺序检查:首先确认 renderer.getContext().isContextLost() 为 false;接着执行一次 renderer.render(scene, camera),确认没有抛出异常且模型在画面中可见;最后试转动视角、切换材质和加载纹理,确保应用交互没有停留在失效前的状态。

使用 EffectComposer、自定义 WebGLRenderTarget 或直接调用 gl.createTexture() 的项目,还应检查离屏输出、深度纹理、帧缓冲和自定义 GPU 句柄是否需要重新建立。普通 Three.js 对象不要在恢复时无条件重复添加到场景,否则会产生重影、事件监听重复或资源泄漏。

恢复失败时的降级处理

本例把 8 秒作为界面提示阈值,而不是 WebGL 规范规定的恢复期限。真正的上下文恢复由浏览器决定,事件可能迟迟不来;不要在真实故障中用定时器反复调用 forceContextRestore()。

上线时将静态预览保留在画布之外的独立 HTML 层,并提供“刷新页面”“查看产品图片”操作。初始化失败时立即展示降级内容;运行中丢失则立刻展示预览,恢复成功且画面检查通过后再隐藏。若用户多次遇到故障,记录浏览器版本、设备类型、场景规模与纹理数量,排查显存压力和重复创建渲染器的问题。

API 依据可查阅 Three.js WebGLRenderer 和 MDN webglcontextrestored。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

WebGL 上下文丢失如何恢复

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通