WebGL 上下文丢失恢复与错误码定位
一句话结论：上下文丢失会静默作废所有 GPU 资源，必须在事件中阻止默认行为并重建资源；错误码只在主动查询时返回，是定位运行期问题的唯一线索。
上下文丢失与恢复
是什么
上下文丢失是浏览器主动回收 WebGL 上下文的机制，触发时会派发 webglcontextlost 事件，所有已创建的 GPU 资源立即失效，接口调用变为空操作。恢复时派发 webglcontextrestored。
解决什么问题
它解决 GPU 异常时的稳定性问题。驱动重置或显存耗尽若直接崩溃会导致整个标签页不可用，丢失机制把故障范围限制在单个上下文内，给页面留出重建资源、继续运行的机会。
为什么这样做
浏览器无法保证 GPU 进程永远存活，因此把上下文设计成可失效可重建的资源。事件模型中要求页面在丢失时调用 preventDefault 声明"我能恢复"，浏览器才会在条件允许时重建上下文，否则默认放弃恢复以避免无意义的重建开销。
怎么用
canvas.addEventListener('webglcontextlost', (e) => {
e.preventDefault(); // 必须调用，否则不会派发恢复事件
cancelAnimationFrame(rafId); // 先停掉渲染循环
log.warn('WebGL 上下文丢失，等待恢复');
}, false);
canvas.addEventListener('webglcontextrestored', () => {
initResources(); // 重建缓冲、纹理、程序、帧缓冲
rafId = requestAnimationFrame(render);
}, false);
// 主动释放（页面卸载或复用组件时）
const ext = gl.getExtension('WEBGL_lose_context');
if (ext) ext.loseContext();
常见坑
- 恢复后画面全黑 → 原因：资源未重建，仍在用失效对象 → 处理：把资源创建抽成函数，恢复时整体重跑
- 只重建了一半资源 → 原因：部分资源分散在模块里 → 处理：统一登记资源清单，集中创建与销毁
- 未调用 preventDefault → 原因：误以为事件只是通知 → 处理：丢失回调首行就阻止默认行为
- 恢复后忘记重启渲染循环 → 原因：循环在丢失时被取消 → 处理：恢复事件里重新请求动画帧
- 频繁切换页面导致反复丢失 → 原因：后台标签被回收 → 处理：页面不可见时暂停渲染，可见时再恢复
错误码检查与定位
是什么
错误码检查是通过 gl.getError() 读取最近一次错误状态的过程。WebGL 不会抛异常，错误被记录在上下文内部，只有调用 getError 才会返回并清空，返回值包括 NO_ERROR、INVALID_ENUM、INVALID_VALUE、INVALID_OPERATION、OUT_OF_MEMORY 与 CONTEXT_LOST_WEBGL。
解决什么问题
它解决接口调用失败却毫无提示的问题。例如绑定了未编译成功的程序、绘制时顶点属性未启用、纹理未完成上传，这些都不会抛异常，只能通过错误码确认。
为什么这样做
GPU 是异步执行的，若每次调用都同步校验并抛错，会严重拖慢渲染。因此设计上把错误暂存，由开发者在需要时主动查询，把校验成本从每次调用转移到排查阶段，兼顾性能与可诊断性。
怎么用
function checkError(tag) {
const err = gl.getError();
if (err === gl.NO_ERROR) return;
const names = {
[gl.INVALID_ENUM]: 'INVALID_ENUM（枚举参数非法）',
[gl.INVALID_VALUE]: 'INVALID_VALUE（数值越界）',
[gl.INVALID_OPERATION]: 'INVALID_OPERATION（当前状态不允许该操作）',
[gl.OUT_OF_MEMORY]: 'OUT_OF_MEMORY（显存不足）',
};
console.error(`[${tag}] ${names[err] || err}`);
}
gl.bindBuffer(gl.ARRAY_BUFFER, vbo);
checkError('bindBuffer');
gl.drawArrays(gl.TRIANGLES, 0, 3);
checkError('drawArrays');
| 错误码 | 常见原因 |
|---|---|
| INVALID_ENUM | 传错常量，如把 gl.TRIANGLES 写成数字 |
| INVALID_VALUE | 偏移或长度为负，数据超出缓冲范围 |
| INVALID_OPERATION | 未绑定程序、属性未启用、纹理未上传完整 |
| OUT_OF_MEMORY | 纹理或缓冲过大，显存不足 |
| CONTEXT_LOST_WEBGL | 上下文已丢失，需等待恢复 |
定位技巧：在可疑调用前后各查一次，错误出现在两次查询之间；用二分法逐段插入检查，快速收敛到出错的那一行。
常见坑
- 把 getError 放进渲染循环 → 原因：每次调用触发同步 → 处理：仅开发模式或按下开关时启用
- 只在最后查一次 → 原因：错误码已被覆盖，无法定位位置 → 处理：分段插入检查点
- 忽略 INVALID_OPERATION → 原因：多数状态错误的信号 → 处理：检查程序、属性、纹理绑定状态
- 认为返回 NO_ERROR 就一定画出来了 → 原因：逻辑错误不产生错误码 → 处理：配合抓帧工具看实际调用
要点总结
- 上下文丢失会作废全部资源，必须在恢复事件中整体重建
webglcontextlost中必须调用 preventDefault 才能收到恢复事件- 资源创建要集中成函数，便于丢失后一键重建
getError是运行期唯一的错误线索，分段插入可二分定位- getError 有同步开销，生产环境不要放进渲染循环
