Web 图形与 3D / 系统课时
读取 WGSL 编译错误与诊断信息
读取 WGSL 编译错误与诊断信息
当 WGSL 着色器写错却只看到管线创建失败时,可以直接读取着色器模块的编译诊断,找到具体的错误位置。本课用一个故意引用未定义变量的计算着色器,演示如何获取错误类型、行列、源码位置与诊断消息,并按顺序修复问题。
学习目标
- 使用 `GPUShaderModule.getCompilationInfo()` 获取 WGSL 编译诊断。
- 理解 `type`、`message`、`lineNum`、`linePos`、`offset` 和 `length` 的含义。
- 根据诊断检查 WGSL 语法、变量与资源绑定,并区分编译错误和管线验证错误。
获取编译诊断的正确时机
WebGPU 通过 `device.createShaderModule({ code })` 创建着色器模块,但成功返回 `GPUShaderModule` 不代表 WGSL 已经通过编译检查。着色器编译诊断需要通过模块的 `getCompilationInfo()` 异步读取。
推荐在创建渲染或计算管线之前执行以下检查:
- 调用 `device.createShaderModule()`,传入 WGSL 源码和便于识别的 `label`。
- 对返回的模块调用 `await shaderModule.getCompilationInfo()`。
- 遍历 `info.messages`,优先处理 `type === 'error'` 的消息。
- 修复源码后重新创建模块并获取诊断,确认不再存在编译错误。
`messages` 可能包含 `error`、`warning` 和 `info` 三类消息。`error` 表示编译失败,`warning` 表示需要关注但不一定阻止编译的问题,`info` 提供额外信息。没有消息不代表后续管线、资源绑定和绘制一定正确。
运行条件是支持 WebGPU 的浏览器,并使用 HTTPS 或 `localhost` 等安全上下文。打开浏览器开发者工具的 Console,即可运行下面的 JavaScript 示例。
运行一个故意写错的着色器
下面的计算着色器声明了一个存储缓冲区 `results`,然后尝试把不存在的 `missingValue` 写入数组。错误位于 WGSL 源码第 4 行,用于验证诊断是否能准确定位变量引用。
将以下完整 JavaScript 代码粘贴到浏览器控制台执行:
(async () => {
const adapter = await navigator.gpu?.requestAdapter();
if (!adapter) {
console.log('无法获取 WebGPU 适配器');
return;
}
const device = await adapter.requestDevice();
// 使用数组固定源码行号,便于根据诊断定位原文
const lines = [
'@group(0) @binding(0) var<storage, read_write> results: array<f32>;',
'@compute @workgroup_size(1)',
'fn main(@builtin(global_invocation_id) gid: vec3<u32>) {',
' results[gid.x] = missingValue;',
'}',
];
const code = lines.join('\n');
const shaderModule = device.createShaderModule({
label: 'diagnostic-demo',
code,
});
// 编译诊断需要异步读取,不能仅判断模块是否返回
const info = await shaderModule.getCompilationInfo();
console.log(`存在 error:${info.messages.some(m => m.type === 'error')}`);
for (const m of info.messages) {
const detail = m.message.split('\n').join(' ');
console.log(`[${m.type}] ${m.lineNum}:${m.linePos} ${detail}`);
// 全局诊断可能没有对应行号,不能直接访问源码数组
if (m.lineNum >= 1 && m.lineNum <= lines.length) {
console.log(`源码: ${lines[m.lineNum - 1].trim()}`);
}
}
})().catch(console.error);预期输出示意(支持 WebGPU 的环境):
存在 error:true
[error] 4:<COLUMN> <MESSAGE>
源码: results[gid.x] = missingValue;`<COLUMN>` 表示编译器报告的列号,`<MESSAGE>` 表示实际诊断文字。具体位置、措辞和消息条数可能随浏览器及底层编译器变化,但错误应指向第 4 行未定义的标识符。浏览器还可能另外输出设备验证错误,这不影响从 `getCompilationInfo()` 读取 WGSL 诊断。
这里没有创建计算管线或执行 GPU 工作组,因此不需要实际创建并绑定存储缓冲区。示例只验证 WGSL 模块的编译诊断能力。
根据诊断字段定位源码
每条 `GPUCompilationMessage` 都提供一组用于定位问题的字段。排查时建议保留完整消息,而不是只记录第一条错误的字符串。
| 字段 | 含义及使用方法 |
|---|---|
| `type` | `error`、`warning` 或 `info`;先处理错误 |
| `message` | 编译器给出的诊断文本,可包含具体原因和相关提示 |
| `lineNum` | 从 1 开始的行号;没有具体源码位置时可能为 0 |
| `linePos` | 从 1 开始的行内位置;没有具体位置时可能为 0 |
| `offset` | 诊断位置相对源码字符串开头的偏移,从 0 开始 |
| `length` | 相关源码范围的长度,可用于编辑器高亮 |
`linePos`、`offset` 和 `length` 使用 UTF-16 代码单元计数。对于包含非 ASCII 字符的源码,不应简单把这些值当成屏幕上显示的字符数量。
假设诊断指向第 4 行,定位时先使用 `lineNum - 1` 访问 JavaScript 的源码行数组,再查看 `linePos` 指向的区域。`offset` 和 `length` 则更适合用于编辑器内部的字符串范围标记。
[!info] 同一个源文件可能存在多条诊断,而且修复前面的语法错误后,编译器才有机会发现后面的类型或绑定问题。因此每次修改后都应重新读取全部消息,而不是只检查第一条。
逐项检查语法、变量和绑定
遇到编译错误时,建议按以下顺序检查,避免先调整不相关的 GPU 资源配置。
- **检查 WGSL 语法。** 确认函数声明的括号和花括号配对,赋值语句以分号结束,属性使用正确写法。例如计算入口需要 `@compute` 属性和合法的 `@workgroup_size(1)` 声明。缺少 `)`、`}` 或 `;` 都可能使解析在后续位置失败。
- **检查标识符与作用域。** 示例中的 `missingValue` 没有任何声明,因此无法解析。将第 4 行的 `missingValue` 替换为合法的 `f32` 值 `1.0`,即可消除这处错误。真实项目中还要检查大小写、局部变量作用域和表达式类型是否匹配。
- **检查资源绑定声明。** 示例的 `@group(0) @binding(0)` 表示第 0 组第 0 个绑定,`var<storage, read_write>` 表示可读写存储资源。应确认资源类型、地址空间和访问模式有效,并避免在同一着色器接口中重复使用同一个组号与绑定号。
- **重新编译并确认结果。** 修改源码后必须重新调用 `createShaderModule()`,再对新模块获取编译信息。旧模块不会因为 JavaScript 中的源码字符串改变而自动更新。
对本例完成变量修复后,再执行整段 JavaScript,预期第一条汇总输出变为:
存在 error:false如果仍有错误,继续查看新消息所对应的源码位置;如果只剩 `warning`,应结合具体文字判断是否需要处理。不同浏览器可能产生不同数量的非错误诊断。
编译通过后仍可能失败的情况
WGSL 编译通过,只表示着色器模块没有报告编译错误。管线创建和运行时还有独立的验证规则,不能把所有 GPU 错误都归类为 WGSL 语法错误。
例如,着色器声明 `@group(0) @binding(0)` 为可读写存储缓冲区,但应用提供的绑定组布局与其要求不兼容,就可能在创建管线或绑定资源时出现验证错误。类似地,错误的入口函数名、着色器阶段不匹配或超出设备限制,也可能在后续步骤暴露。
建议将故障分成三个检查层次:
- **编译层:** 使用 `getCompilationInfo()` 检查 WGSL 语法、名称解析、类型和声明是否合法。
- **管线与绑定层:** 检查 `createComputePipelineAsync()` 或 `createRenderPipelineAsync()` 的结果,以及入口函数、管线布局、绑定组和资源类型是否匹配;必要时使用 `device.pushErrorScope('validation')` 与 `device.popErrorScope()` 捕获相应验证错误。
- **运行层:** 编译和管线验证通过后,再检查派发规模、缓冲区容量、索引边界、纹理用途和最终计算结果。运行结果错误不一定会产生编译诊断。
实际项目中,可以给每个 `GPUShaderModule` 设置包含文件或功能名称的 `label`,并在开发阶段记录完整的 `type`、`lineNum`、`linePos` 与 `message`。修复时优先消除 WGSL 编译错误,再进入管线验证和 GPU 执行结果检查,通常能减少大量无效排查。