Web 图形与 3D / 系统课时
用错误作用域捕获校验失败
用错误作用域捕获校验失败
当缓冲区用法、绑定资源或渲染管线配置不合法时,WebGPU 的验证错误不一定通过 JavaScript 的 throw 报出。本篇用 pushErrorScope() 和 popErrorScope() 定位一次故意制造的缓冲区校验失败,并演示修复后如何确认错误消失。
学习目标
- 正确配对错误作用域,获取
GPUValidationError或null。 - 运行一段可复现的缓冲区校验示例并验证修复。
- 区分验证失败、未捕获 GPU 错误、JavaScript 异常与设备丢失。
错误作用域如何收集错误
device.pushErrorScope('validation') 开始收集此后相关 WebGPU 调用产生的验证错误;调用完可疑操作,再以 await device.popErrorScope() 关闭作用域并读取结果。返回值是作用域中捕获的第一条匹配错误;如果没有匹配错误,则为 null。这不是收集所有错误的数组。
| 过滤器 | 捕获的错误类型 |
|---|---|
validation |
GPUValidationError:描述符、用法或资源约束不合法 |
out-of-memory |
GPUOutOfMemoryError:GPU 内存分配失败 |
internal |
GPUInternalError:实现内部错误 |
作用域按栈管理,嵌套时必须后入先出。实际排查时,每个可疑操作单独包一对作用域,避免多个操作的第一条错误遮住真正的故障位置。

复现失败并验证修复
在支持 WebGPU 的浏览器中打开 https:// 页面或本机 http://localhost 页面,再按 F12 打开开发者工具的 Console,执行下列完整 JavaScript。代码故意组合 MAP_WRITE 和 UNIFORM:规范只允许 MAP_WRITE 搭配 COPY_SRC,因此第一轮应产生验证错误。
async function demoErrorScope() {
if (!navigator.gpu) throw new Error('当前环境不支持 WebGPU');
const adapter = await navigator.gpu.requestAdapter();
if (!adapter) throw new Error('没有可用的 GPU 适配器');
const device = await adapter.requestDevice();
// 不属于任何匹配作用域的 GPU 错误仍应统一记录。
device.addEventListener('uncapturederror', (event) => {
console.error('未捕获 GPU 错误:', event.error.message);
});
device.lost.then((info) => {
console.warn('GPU 设备丢失:', info.reason);
});
// 故意触发校验失败:MAP_WRITE 不允许搭配 UNIFORM。
device.pushErrorScope('validation');
device.createBuffer({
size: 16,
usage: GPUBufferUsage.MAP_WRITE | GPUBufferUsage.UNIFORM,
});
const badError = await device.popErrorScope();
console.log(badError instanceof GPUValidationError
? '违规缓冲区:已捕获验证错误'
: '违规缓冲区:未捕获验证错误');
if (badError) console.log('错误详情:', badError.message);
// 合法的 uniform 缓冲区可通过 queue.writeBuffer 上传数据。
device.pushErrorScope('validation');
const buffer = device.createBuffer({
size: 16,
usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
});
const goodError = await device.popErrorScope();
console.log(goodError === null
? '合法缓冲区:无验证错误'
: '合法缓冲区:出现验证错误');
buffer.destroy();
}
demoErrorScope().catch((error) => {
console.error('初始化或 JavaScript 异常:', error.message);
});预期输出(浏览器成功获得 GPU 设备时):
违规缓冲区:已捕获验证错误
错误详情: <MESSAGE>
合法缓冲区:无验证错误<MESSAGE> 代表实际错误说明,不同浏览器和驱动的措辞可能不同。修复方式不是继续映射 uniform 缓冲区,而是移除 MAP_WRITE,保留 UNIFORM | COPY_DST,需要更新数据时使用 device.queue.writeBuffer()。
把其他异常交给正确的处理方式
validation 作用域不会吞掉 JavaScript 抛出的 TypeError,也不会捕获 GPU 内存不足或内部错误。下面几条出口应分别排查:
- 已知 GPU 校验风险:在调用前
pushErrorScope('validation'),调用后await popErrorScope(),检查error.message。 - 未匹配或未设置作用域的 GPU 错误:监听
device的uncapturederror事件,读取event.error。 - 初始化与 JavaScript 异常:用
try/catch或 Promise 的.catch()处理,例如requestDevice()的拒绝;requestAdapter()返回null也要显式检查。 - 设备丢失:监听
device.lostPromise 的完成并查看原因;它不等同于普通验证失败。
避免作用域失效的三个细节
- 先压栈再调用:把
pushErrorScope()放在可疑资源创建、命令编码或提交之前;事后再压栈抓不到先前的错误。 - 调用结束后及时出栈:不要在同一个作用域中混入多个不相关的 GPU 操作,防止先发生的匹配错误掩盖当前问题。
- 等待异步结果:
popErrorScope()返回 Promise,必须await或使用.then();直接把 Promise 当成错误对象检查会误判。
如果第二轮仍出现验证错误,先单独记录 goodError.message,检查 size、usage 和设备状态,再将真实项目中的可疑 createBindGroup()、createRenderPipeline() 或命令编码操作逐段移进同样的作用域定位。