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 错误作用域的时间边界与错误分流

复现失败并验证修复

在支持 WebGPU 的浏览器中打开 https:// 页面或本机 http://localhost 页面,再按 F12 打开开发者工具的 Console,执行下列完整 JavaScript。代码故意组合 MAP_WRITE 和 UNIFORM:规范只允许 MAP_WRITE 搭配 COPY_SRC,因此第一轮应产生验证错误。

js
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 设备时):

text
违规缓冲区:已捕获验证错误
错误详情: <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.lost Promise 的完成并查看原因;它不等同于普通验证失败。

避免作用域失效的三个细节

  1. 先压栈再调用:把 pushErrorScope() 放在可疑资源创建、命令编码或提交之前;事后再压栈抓不到先前的错误。
  2. 调用结束后及时出栈:不要在同一个作用域中混入多个不相关的 GPU 操作,防止先发生的匹配错误掩盖当前问题。
  3. 等待异步结果:popErrorScope() 返回 Promise,必须 await 或使用 .then();直接把 Promise 当成错误对象检查会误判。

如果第二轮仍出现验证错误,先单独记录 goodError.message,检查 size、usage 和设备状态,再将真实项目中的可疑 createBindGroup()、createRenderPipeline() 或命令编码操作逐段移进同样的作用域定位。

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

目录与阅读设置

阅读设置

17

记录一个想法

用错误作用域捕获校验失败

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

登录哪都通