WebGL 黑屏与渲染差异排查
一句话结论：黑屏按五层递进排查，差异看精度与状态，坐标问题用视口与辅助线验证，能把"猜"变成确定的结论。
黑屏问题排查思路
是什么
黑屏排查是按固定顺序排除渲染管线各层故障的方法，顺序为着色器、顶点数据、矩阵、视口、渲染状态。每一层都能用最小用例独立验证。
解决什么问题
它解决黑屏无报错、无从下手的问题。WebGL 出错不抛异常，因此必须有一套可复现的排除顺序，否则只能随机试错，排查时间不可控。
为什么这样做
渲染管线是串行的，后一层的正确性依赖前一层。从最上游的着色器开始，用最简输入逐级放大复杂度，第一次出现黑屏的那一层就是故障点，这是代价最低的定位策略。
怎么用
// 第 1 层：着色器——先用固定输出验证管线
gl_FragColor = vec4(1.0, 0.0, 0.0, 1.0); // 全红说明着色器与绘制调用正常
// 第 2 层：顶点数据——用覆盖全屏的三角形验证
const verts = new Float32Array([-1, -1, 0, 3, -1, 0, -1, 3, 0]);
// 第 3 层：矩阵——先去掉矩阵，用裁剪坐标直出
// 第 4 层：视口——确认尺寸与视口一致
gl.viewport(0, 0, canvas.width, canvas.height);
// 第 5 层：状态——每帧显式设置
gl.clearColor(0, 0, 0, 1);
gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT);
gl.disable(gl.CULL_FACE); // 排查阶段先关剔除
gl.disable(gl.DEPTH_TEST); // 排查阶段先关深度测试
排查清单：着色器是否编译链接成功 → 顶点数据是否上传且属性已启用 → 矩阵是否把顶点变换进裁剪空间 → 视口与画布尺寸是否一致 → 深度、剔除、混合状态是否遮挡了画面。
常见坑
- 只看最后一步不看日志 → 原因：编译失败静默 → 处理：每次编译链接后必读状态与日志
- 属性未启用就绘制 → 原因：顶点属性默认关闭 → 处理：绑定后调用 enableVertexAttribArray
- 顶点在视锥外 → 原因：矩阵算错或坐标超出 -1 到 1 → 处理：先用固定坐标验证
- 清屏颜色与物体同色 → 原因：误判为黑屏 → 处理：临时把背景改成对比色
渲染结果不一致排查
是什么
渲染结果不一致，指同一份代码在不同设备或不同时刻得到不同画面，常见成因包括精度限定符、扩展支持、纹理限制与状态残留。
解决什么问题
它解决"本地正常线上异常"的问题。移动端 GPU 的浮点精度、扩展集合与驱动实现差异很大，只有把这些差异点逐一收敛，才能保证各端表现一致。
为什么这样做
GLSL ES 把精度选择权交给实现，highp 在部分移动 GPU 上只有 16 位有效精度；扩展属于可选能力，缺失时接口返回 null；状态机是全局的，任何一处遗漏都会污染后续绘制。三者都是"环境相关"的差异源，必须显式处理。
怎么用
// 精度：按能力声明，颜色可用 mediump，位置与法线用 highp
#ifdef GL_FRAGMENT_PRECISION_HIGH
precision highp float;
#else
precision mediump float;
#endif
// 扩展：先检测再决定分支
const floatTex = gl.getExtension('OES_texture_float');
const maxTexSize = gl.getParameter(gl.MAX_TEXTURE_SIZE);
// 状态：每帧开头显式重置，杜绝残留
function resetState() {
gl.disable(gl.BLEND);
gl.disable(gl.CULL_FACE);
gl.enable(gl.DEPTH_TEST);
gl.depthFunc(gl.LEQUAL);
gl.colorMask(true, true, true, true);
}
| 差异源 | 表现 | 处理 |
|---|---|---|
| 精度限定符 | 色带、条纹、位置抖动 | 高精度分支 + 能力检测 |
| 扩展缺失 | 特性失效或报错 | getExtension 判空后降级 |
| 纹理尺寸上限 | 贴图空白 | 按 MAX_TEXTURE_SIZE 缩放 |
| 状态残留 | 时好时坏 | 每帧显式重置状态 |
| 上下文数量 | 后创建的画布失效 | 控制数量并及时释放 |
常见坑
- 全部用 highp 以为最保险 → 原因：部分设备不支持 → 处理：用预处理宏做能力分支
- 直接调用扩展接口 → 原因：未判空 → 处理：getExtension 返回 null 时走降级路径
- 依赖默认状态 → 原因：不同实现默认值可能不同 → 处理：初始化时显式设置全部关键状态
- 认为桌面正常即可上线 → 原因：移动 GPU 差异大 → 处理：至少覆盖低端安卓与 iOS 真机验证
坐标系与视口调试
是什么
坐标系与视口调试，是通过调整 gl.viewport 区域、绘制辅助线与标记点，验证裁剪坐标到屏幕像素的映射是否正确的方法。
解决什么问题
它解决内容偏移、只显示一部分、点击位置不对等坐标类问题。这类问题往往不是渲染错误，而是视口与坐标范围不匹配，用肉眼观察难以判断，需要构造可验证的参照物。
为什么这样做
视口定义了裁剪坐标到窗口坐标的线性映射，只要改小视口观察内容是否随之收缩，就能确认映射链路是否生效；再用位于 -1 与 1 的辅助线端点验证边界，可以一次性判断坐标范围、视口尺寸与宽高比三者的正确性。
怎么用
// 临时把视口缩到左下角四分之一，确认映射生效
gl.viewport(0, 0, canvas.width / 2, canvas.height / 2);
// 画一条从 (-1,-1) 到 (1,1) 的辅助线，端点应落在视口对角
const axis = new Float32Array([-1, -1, 0, 1, 1, 0]);
gl.bufferData(gl.ARRAY_BUFFER, axis, gl.STATIC_DRAW);
gl.drawArrays(gl.LINES, 0, 2);
// 恢复正常视口并核对尺寸来源
gl.viewport(0, 0, canvas.width, canvas.height);
console.log(canvas.width, canvas.height, canvas.clientWidth, canvas.clientHeight);
常见坑
- 用 CSS 尺寸设置视口 → 原因：视口单位是渲染缓冲像素 → 处理：用 canvas.width/height
- 尺寸变化后视口未更新 → 原因：视口不随画布自动变化 → 处理：resize 时同步重设
- 设备像素比未参与换算 → 原因：高分屏只画了一角 → 处理：缓冲尺寸乘 DPR 并同步视口
- 视口超出画布范围 → 原因：参数过大 → 处理：宽高不得超过渲染缓冲尺寸
要点总结
- 黑屏按着色器、顶点、矩阵、视口、状态五层递进排查
- 排查阶段先关剔除与深度测试，用纯色与固定坐标验证管线
- 差异主要来自精度、扩展、纹理限制与状态残留，逐项显式处理
- 每帧显式重置状态，不依赖默认值
- 视口与辅助线是验证坐标映射最直接的手段，尺寸一律用缓冲像素
