用途:让 WebGPU 失败变得可诊断——为每个对象加标签、精确定位 WGSL 编译错误、用错误作用域隔离出错调用、给命令流加注释以便 GPU 捕获可读。
主要能力与工具:对象标签(每个描述符的 label 字段)用于判断验证消息指向哪个对象;错误作用域 device.pushErrorScope / popErrorScope 定位具体出错调用;着色器编译信息 shaderModule.getCompilationInfo() 提供 WGSL 语法与类型错误的行号列号;调试分组 encoder.pushDebugGroup / popDebugGroup 与标记 insertDebugMarker 组织帧捕获层级;Chrome DevTools 控制台查看未捕获错误;chrome://gpu 查看适配器与驱动状态、是否被屏蔽;chrome://flags/#enable-unsafe-webgpu 启用实验特性;RenderDoc 或 Windows 上经 Dawn 的 PIX 做 GPU 帧捕获。
必要用法要点:每个缓冲区、纹理、采样器、管线、绑定组、着色器模块、命令编码器都设置有意义 label;createShaderModule 不抛错,须立即检查 getCompilationInfo() 中 type === "error" 的消息;用错误作用域包住可疑调用定位首个失败;用调试分组包裹每个 pass 或阶段。
限制与警告:pushDebugGroup 必须与同一编码器上的 popDebugGroup 一一配对,否则编码验证失败;错误具有传染性,须先修最早报错而非下游噪音;uncapturederror 仅作遥测,不能定位调用点;WebGPU 需要安全上下文(https 或 localhost)。具体环境支持细节暂未提供。