SuperAPI AI 工具集

webgpu-errors-device-loss

通用与其它

查看项目

更新于 10-15 22:18

技能介绍

用途:正确处理 WebGPU 的 GPUDevice.lost,并在设备丢失后重建 GPU 状态,采用显式且经原因判断的重新初始化,而不是静默重试循环。适用于 WebGPU 1.0-stable(Chrome 113+、Safari 26+、Firefox 141+)。

主要事实与能力:GPUDevice.lost 是只读的 Promise<GPUDeviceLostInfo>,在设备整个生命周期内保持 pending,设备不可用时解析一次,永不 reject;解析值包含 reason 和 message。reason 为 "destroyed" 表示应用主动调用 device.destroy(),不恢复;为 "unknown" 表示 GPU 进程崩溃、驱动更新、硬件移除、浏览器回收资源等外部或隐式 OOM/内部错误,需经原因判断后恢复。丢失后的旧 GPUDevice 永久失效,旧 GPUAdapter 可能失效(如 GPU 被拔出),旧 buffer、texture、pipeline、bind group 均绑定于已死设备,均不可复用。

使用方式:在 requestDevice 后的同一异步步骤、首帧渲染前就注册 device.lost 处理函数,如 device.lost.then(handleDeviceLost)。处理时先判断 info.reason:"destroyed" 直接返回,不恢复;"unknown" 执行恢复序列——重新请求 GPUAdapter、申请新 GPUDevice、针对新设备重建所有 GPU 资源、给新设备重新挂载 device.lost 处理器。恢复尝试次数要有上限(示例为 3 次),超限后向用户显示持久失败提示并停止。device.lost 视为已解析 Promise,用 await 或 .then() 消费,不要用 try/catch 或 .catch() 当作丢失处理。

适用场景:GPU 进程崩溃、驱动更新、硬件移除、资源被回收后的恢复,以及避免静默重试循环的反模式。

限制与警告:绝不因 "destroyed" 恢复;绝不复用丢失的 device、adapter 或其创建的任何资源;绝不运行无上限的 requestDevice 重试循环;绝不把 device.lost 当作会 reject 的 Promise;恢复达到上限后必须显式提示用户,而非静默重试。参考文件 references/methods.md、examples.md、anti-patterns.md 提供细节,相关技能含 webgpu-core-architecture、webgpu-errors-validation、webgpu-core-limits-features。