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 创建失败也能显示;正式产品可替换为预先准备的产品封面图。
<!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 所在目录启动静态服务:
python3 -m http.server 8000预期结果:终端显示 HTTP 服务正在监听 8000 端口(绑定地址随系统而异)。访问 http://localhost:8000/index.html,应看到旋转方块和“3D 正常”;点击“模拟丢失”后出现静态预览,再点“模拟恢复”则恢复旋转并显示“3D 已恢复”。控制台中应用自定义日志依次为:
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。