Web 图形与 3D / 系统课时
读取着色器日志定位黑屏
读取着色器日志定位黑屏
WebGL 2 场景黑屏,可能是 GLSL 编译失败,也可能是画布尺寸、顶点布局、矩阵、纹理或深度状态出了问题。先运行一个可见的最小三角形,读取 Shader、Program 和 WebGL 错误信息,再按渲染链路逐层恢复,避免一次修改多个位置。
学习目标
- 使用
COMPILE_STATUS、LINK_STATUS和getError()区分三类错误。 - 按视口、清屏、Program、顶点属性、矩阵、纹理、深度的顺序定位模型缺失。
- 通过固定颜色和受控故障验证排查结论。
建立能独立运行的诊断场景
在支持 WebGL 2 的浏览器中打开开发者工具 Console,粘贴并执行以下 JavaScript。脚本自行创建 480×270 的 Canvas,绘制一个不依赖矩阵和纹理的蓝色三角形,并报告编译、链接和绘制阶段的检查结果。
(() => {
const canvas = document.createElement('canvas');
canvas.width = 480;
canvas.height = 270;
canvas.style.border = '1px solid #64748b';
document.body.appendChild(canvas);
const gl = canvas.getContext('webgl2');
if (!gl) throw new Error('当前环境不支持 WebGL 2');
const vertexSource = `#version 300 es
layout(location = 0) in vec2 aPosition;
void main() {
gl_Position = vec4(aPosition, 0.0, 1.0);
}`;
const fragmentSource = `#version 300 es
precision highp float;
out vec4 outColor;
void main() {
outColor = vec4(0.2, 0.7, 1.0, 1.0);
}`;
// 以状态位判定成功与否,日志即使为空也不能代替状态位。
function compile(type, source, label) {
const shader = gl.createShader(type);
if (!shader) throw new Error(label + '创建失败');
gl.shaderSource(shader, source);
gl.compileShader(shader);
const ok = gl.getShaderParameter(shader, gl.COMPILE_STATUS);
const info = gl.getShaderInfoLog(shader);
console.log(label + '编译: ' + (ok ? '成功' : '失败'));
if (info) console.log(info);
if (!ok) throw new Error(label + '编译失败');
return shader;
}
const vertex = compile(gl.VERTEX_SHADER, vertexSource, '顶点着色器');
const fragment = compile(gl.FRAGMENT_SHADER, fragmentSource, '片元着色器');
const program = gl.createProgram();
if (!program) throw new Error('Program 创建失败');
gl.attachShader(program, vertex);
gl.attachShader(program, fragment);
gl.linkProgram(program);
const linked = gl.getProgramParameter(program, gl.LINK_STATUS);
const linkInfo = gl.getProgramInfoLog(program);
console.log('Program 链接: ' + (linked ? '成功' : '失败'));
if (linkInfo) console.log(linkInfo);
if (!linked) throw new Error('Program 链接失败');
gl.deleteShader(vertex);
gl.deleteShader(fragment);
gl.useProgram(program);
// VAO 保存 location 0 的顶点属性配置。
const vao = gl.createVertexArray();
const vbo = gl.createBuffer();
gl.bindVertexArray(vao);
gl.bindBuffer(gl.ARRAY_BUFFER, vbo);
gl.bufferData(gl.ARRAY_BUFFER, new Float32Array([
-0.7, -0.7, 0.7, -0.7, 0.0, 0.7
]), gl.STATIC_DRAW);
gl.enableVertexAttribArray(0);
gl.vertexAttribPointer(0, 2, gl.FLOAT, false, 0, 0);
// 先关闭深度测试,用最少状态确认基本绘制可见。
gl.viewport(0, 0, gl.drawingBufferWidth, gl.drawingBufferHeight);
gl.disable(gl.DEPTH_TEST);
gl.clearColor(0.06, 0.08, 0.12, 1);
gl.clear(gl.COLOR_BUFFER_BIT);
gl.drawArrays(gl.TRIANGLES, 0, 3);
const error = gl.getError();
console.log('getError: ' + (error === gl.NO_ERROR ? 'NO_ERROR' : error));
})();预期 Console 至少出现以下四行,页面新增的画布显示深色背景和蓝色三角形;部分浏览器或驱动还可能输出额外提示。
顶点着色器编译: 成功
片元着色器编译: 成功
Program 链接: 成功
getError: NO_ERROR根据日志判断失败发生在哪里
Shader 编译失败:gl.getShaderParameter(shader, gl.COMPILE_STATUS) 返回 false,立即查看该 Shader 的 gl.getShaderInfoLog(shader)。重点检查 #version 300 es、变量类型、语法与 in/out 声明。日志中的行号指向传给 shaderSource 的源码,不一定对应 HTML 文件行号。
Program 链接失败:两个 Shader 可能都编译成功,但 gl.getProgramParameter(program, gl.LINK_STATUS) 仍为 false。这时读取 gl.getProgramInfoLog(program),检查跨阶段 out/in 类型和名称是否匹配;不能因为两个 Shader 编译成功就跳过链接检查。
WebGL 状态错误:gl.getError() 返回 gl.NO_ERROR 表示当前没有待报告的 GL 错误;若返回 gl.INVALID_OPERATION 等枚举值,应在 useProgram、属性设置和绘制调用之后分别检查,以定位出错的调用。一次 getError() 只取走一个错误标志,需要时重复读取直至 NO_ERROR。编译或链接失败应以各自状态位为准,而不是依赖 getError()。
按画面层级缩小故障范围
工程中先尝试把画布清成亮紫色,再逐层恢复绘制。每次只调整一项,确认画面变化后才继续。

- 视口与画布:先确认
canvas.width、canvas.height以及gl.drawingBufferWidth、gl.drawingBufferHeight均大于零;同时排除 CSS 隐藏或显示尺寸为零。画布调整尺寸后调用gl.viewport(0, 0, gl.drawingBufferWidth, gl.drawingBufferHeight)。 - 清屏:临时调用
gl.disable(gl.SCISSOR_TEST)、gl.colorMask(true, true, true, true)、gl.clearColor(1, 0, 1, 1),再执行gl.clear(gl.COLOR_BUFFER_BIT)。若仍看不到紫色,先查 Canvas 显示、当前绑定的帧缓冲及清屏区域,而不是修改光照公式。使用自建 FBO 时还要核对gl.checkFramebufferStatus(gl.FRAMEBUFFER)是否为gl.FRAMEBUFFER_COMPLETE。 - Program:确认
LINK_STATUS为true,绘制时用gl.getParameter(gl.CURRENT_PROGRAM)检查当前绑定的是目标 Program。Program 链接成功却没有gl.useProgram(program),仍可能无法按预期渲染。 - 顶点属性:检查 VAO 是否已绑定、
layout(location = 0)是否对应gl.enableVertexAttribArray(0)和gl.vertexAttribPointer(0, 2, gl.FLOAT, false, 0, 0)。本例gl.drawArrays(gl.TRIANGLES, 0, 3)必须提交三个顶点;顶点数写成0不会产生三角形。 - 矩阵与裁剪:先使用本例直接输出裁剪空间位置的顶点着色器;恢复场景时再检查
Projection × View × Model的乘法顺序、Uniform 上传和近远裁剪面。顶点进入裁剪空间后,只有满足-w ≤ x,y,z ≤ w(并且w有效)的部分才可能可见。 - 纹理与透明度:先让片元着色器输出固定不透明颜色;若这样可见而贴图后消失,检查
activeTexture对应的纹理单元、uniform1i的单元索引和纹理完整性。未生成 Mipmap 时可暂将TEXTURE_MIN_FILTER设为LINEAR,并排查采样结果是否为黑色或 Alpha 是否为零。 - 深度与剔除:暂时关闭
gl.DEPTH_TEST和gl.CULL_FACE。若模型出现,再逐个恢复;常见深度初始化是gl.depthMask(true)、gl.clearDepth(1)、gl.depthFunc(gl.LESS),并在绘制前清除gl.DEPTH_BUFFER_BIT。前后面绕序错误则检查剔除设置。
故意制造故障验证排查方法
在最小示例上一次只做一处修改,重新运行并观察现象:
- 将片元着色器里的
vec4(0.2, 0.7, 1.0, 1.0)改成不存在的vec5(0.2, 0.7, 1.0, 1.0):应看到“片元着色器编译: 失败”,具体错误日志措辞随浏览器和驱动变化。 - 将视口设置改为
gl.viewport(0, 0, 0, 0):编译、链接仍成功,getError仍可为NO_ERROR,但只有清屏背景,没有三角形。 - 将绘制调用改成
gl.drawArrays(gl.TRIANGLES, 0, 0):同样不会产生三角形,且不一定报告错误;这说明还必须核对提交的顶点数量。
实际项目中,先保留编译和链接日志,再从可见清屏色开始逐项恢复复杂状态。只要明确找到第一个由正常变为不可见的步骤,就能把黑屏范围收敛到一组具体 API、数据或渲染状态。