Web 图形与 3D / 系统课时

根据编译日志定位着色器错误

根据编译日志定位着色器错误

着色器画面变黑或程序无法启动时,先判断失败发生在单个着色器编译阶段,还是顶点与片元着色器的链接阶段。本课通过故意制造语法错误和接口不匹配,学会读日志、回查源码行号,并验证修复结果。

学习目标

  • 区分 COMPILE_STATUS 与 LINK_STATUS,获取对应错误日志。
  • 根据日志行号定位 GLSL ES 3.00 语法错误。
  • 排查跨阶段接口、精度声明与语言版本不匹配。

先确定错误发生在哪个阶段

WebGL2 的着色器检查分两层。gl.compileShader() 分别编译顶点、片元着色器;编译失败时查询 gl.getShaderInfoLog(shader)。两者编译成功后,gl.linkProgram() 才能检查阶段之间的接口兼容性,失败时查询 gl.getProgramInfoLog(program)。

以状态位判定成功或失败:gl.getShaderParameter(shader, gl.COMPILE_STATUS) 和 gl.getProgramParameter(program, gl.LINK_STATUS) 返回布尔值。信息日志即使非空也可能只是警告,不能仅凭日志是否为空认定失败。

WebGL2 着色器编译和程序链接的错误定位流程

复现语法错误与接口不匹配

创建 shader-check.html,保存以下完整代码,再用支持 WebGL2 的 Chrome、Edge 或 Firefox 打开。按 F12 打开开发者工具并切换到 Console(控制台)。代码先故意漏掉分号,再修复它,最后制造 out vec2 与 in vec3 的类型冲突。

html
<!doctype html>
<html lang="zh-CN">
<meta charset="utf-8">
<title>WebGL2 Shader 诊断</title>
<script>
const gl = document.createElement('canvas').getContext('webgl2');
if (!gl) throw new Error('当前环境不支持 WebGL2');

const vertex = `#version 300 es
layout(location = 0) in vec2 aPosition;
out vec2 vUv;
void main() {
  vUv = aPosition * 0.5 + 0.5;
  gl_Position = vec4(aPosition, 0.0, 1.0);
}`;

const broken = `#version 300 es
precision highp float;
in vec2 vUv;
out vec4 outColor;
void main() {
  outColor = vec4(vUv, 0.0, 1.0)
}`;

// 第一处错误:缺少分号;第二处错误:跨阶段接口类型不一致。
const fixed = broken.replace('vec4(vUv, 0.0, 1.0)', 'vec4(vUv, 0.0, 1.0);');
const mismatch = fixed
  .replace('in vec2 vUv;', 'in vec3 vUv;')
  .replace('vec4(vUv, 0.0, 1.0);', 'vec4(vUv, 1.0);');

function compile(type, source, label) {
  const shader = gl.createShader(type);
  gl.shaderSource(shader, source);
  gl.compileShader(shader);
  const ok = gl.getShaderParameter(shader, gl.COMPILE_STATUS);
  console.log(`${label}: ${ok ? '成功' : '失败'}`);
  if (!ok) {
    console.error(gl.getShaderInfoLog(shader) || '未提供编译日志');
    gl.deleteShader(shader);
  }
  return ok ? shader : null;
}

function link(vs, fs, label) {
  const program = gl.createProgram();
  gl.attachShader(program, vs);
  gl.attachShader(program, fs);
  gl.linkProgram(program);
  const ok = gl.getProgramParameter(program, gl.LINK_STATUS);
  console.log(`${label}: ${ok ? '成功' : '失败'}`);
  if (!ok) console.error(gl.getProgramInfoLog(program) || '未提供链接日志');
  gl.deleteProgram(program);
}

const vs = compile(gl.VERTEX_SHADER, vertex, '顶点编译');
compile(gl.FRAGMENT_SHADER, broken, '缺分号的片元编译');
const fs = compile(gl.FRAGMENT_SHADER, fixed, '修复后片元编译');
const badFs = compile(gl.FRAGMENT_SHADER, mismatch, '接口错误的片元编译');
if (vs && fs) link(vs, fs, '正确接口链接');
if (vs && badFs) link(vs, badFs, '错误接口链接');
for (const shader of [vs, fs, badFs]) {
  if (shader) gl.deleteShader(shader);
}
</script>
</html>

预期输出(错误日志中的行号、措辞因浏览器和图形驱动而异):

text
顶点编译: 成功
缺分号的片元编译: 失败
<编译器日志:提示语法错误,通常定位在缺少分号处或下一行>
修复后片元编译: 成功
接口错误的片元编译: 成功
正确接口链接: 成功
错误接口链接: 失败
<链接器日志:提示 vUv 的跨阶段类型不匹配>

根据日志回到真正的出错位置

错误信息可能出现 ERROR: 0:7: ... 一类格式,其中行号通常指传入 gl.shaderSource() 的 GLSL 字符串,不是 HTML 或 JavaScript 文件的行号。不同驱动的格式不统一,也可能把缺分号的错误标在下一行的 } 上。

定位时按这个顺序检查:

  1. 先读标签,确认是顶点编译、片元编译还是程序链接失败,不要混用两种日志。
  2. 如果是编译失败,找到实际传给 shaderSource() 的完整字符串;检查报告行以及前一行的分号、括号、变量名和类型。
  3. 如果是链接失败,逐个对照顶点 out 与片元 in 的名称、类型及数组长度;本例的 vUv 名称相同,却分别为 vec2 和 vec3。
  4. 每次只修复一类问题,重新编译、链接,并确认对应状态位已变成成功。

如果项目通过模板拼接着色器源码,行号要以拼接后的字符串为准。应在调试时保留最终源码,而不是直接按原始模板文件的行数查错。

排查精度声明与 GLSL 版本

典型现象 检查和修复
片元着色器提示浮点类型缺少精度 在 #version 300 es 后添加 precision highp float;,或给相应类型明确声明精度。
提示 attribute、varying 或 gl_FragColor 无效 GLSL ES 3.00 使用顶点 in、跨阶段 out/in,并自行声明 out vec4 outColor;。
编译器不识别 ES 3.00 语法 确认使用 getContext('webgl2'),且 #version 300 es 位于每份着色器源码的首行;不要在它前面加入空行或注释。
两个着色器各自编译成功,但链接失败 对照实际使用的跨阶段变量,例如 out vec2 vUv; 必须匹配 in vec2 vUv;。

遇到黑屏但编译和链接都成功时,下一步应检查顶点缓冲、属性位置、视口和绘制调用,而不是继续修改 GLSL 语法。编译通过只说明源码合法,链接通过只说明程序阶段能配合工作,并不保证已经发出绘制命令。

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

目录与阅读设置

阅读设置

17

记录一个想法

根据编译日志定位着色器错误

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

登录哪都通