Web 图形与 3D / 知识点
WebGL 开发速查手册
手册条目
通过一次绘制调用渲染大量结构相同但属性不同的对象。
执行实例化绘制
当大量对象共用同一套顶点或索引数据,只是位置、颜色、缩放等属性不同,用实例化绘制可把多次 draw* 调用合并为一次,减少 CPU 到 GPU 的调用开销。

基本语法
WebGL 2 直接提供 drawArraysInstanced、drawElementsInstanced 和 vertexAttribDivisor。除数为 0 时属性按顶点推进,为 1 时每绘制一个实例推进一次。
gl.vertexAttribDivisor(instanceAttributeLocation, 1);
gl.drawArraysInstanced(mode, first, vertexCount, instanceCount);
// 使用索引缓冲时
gl.drawElementsInstanced(mode, indexCount, indexType, indexOffset, instanceCount);以上是片段示例,依赖已完成的着色器、缓冲区和顶点属性配置。
可运行示例
下面用一份三角形顶点数据和三组实例属性,一次调用绘制三个不同位置、不同颜色的三角形。
<!doctype html>
<meta charset="utf-8">
<canvas id="gl" width="640" height="300"></canvas>
<script>
const gl = document.querySelector("#gl").getContext("webgl2");
if (!gl) throw new Error("需要支持 WebGL 2");
function shader(type, source) {
const s = gl.createShader(type);
gl.shaderSource(s, source);
gl.compileShader(s);
if (!gl.getShaderParameter(s, gl.COMPILE_STATUS)) {
throw new Error(gl.getShaderInfoLog(s));
}
return s;
}
const vs = shader(gl.VERTEX_SHADER, `#version 300 es
in vec2 aPosition;
in vec2 aOffset;
in vec3 aColor;
out vec3 vColor;
void main() {
gl_Position = vec4(aPosition * 0.35 + aOffset, 0.0, 1.0);
vColor = aColor;
}`);
const fs = shader(gl.FRAGMENT_SHADER, `#version 300 es
precision mediump float;
in vec3 vColor;
out vec4 outColor;
void main() {
outColor = vec4(vColor, 1.0);
}`);
const program = gl.createProgram();
gl.attachShader(program, vs);
gl.attachShader(program, fs);
gl.linkProgram(program);
if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
throw new Error(gl.getProgramInfoLog(program));
}
gl.useProgram(program);
const vao = gl.createVertexArray();
gl.bindVertexArray(vao);
function attribute(name, data, size, divisor) {
const buffer = gl.createBuffer();
gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
gl.bufferData(gl.ARRAY_BUFFER, new Float32Array(data), gl.STATIC_DRAW);
const location = gl.getAttribLocation(program, name);
gl.enableVertexAttribArray(location);
gl.vertexAttribPointer(location, size, gl.FLOAT, false, 0, 0);
// divisor=1 表示每个实例读取一组数据,而不是每个顶点读取
gl.vertexAttribDivisor(location, divisor);
}
attribute("aPosition", [0, 0.8, -0.7, -0.6, 0.7, -0.6], 2, 0);
attribute("aOffset", [-0.65, 0, 0, 0, 0.65, 0], 2, 1);
attribute("aColor", [1, 0.25, 0.2, 0.2, 0.8, 0.35, 0.2, 0.45, 1], 3, 1);
gl.viewport(0, 0, gl.canvas.width, gl.canvas.height);
gl.clearColor(0.08, 0.09, 0.12, 1);
gl.clear(gl.COLOR_BUFFER_BIT);
gl.drawArraysInstanced(gl.TRIANGLES, 0, 3, 3);
console.log("instances=3");
</script>预期结果
控制台输出:instances=3
画布显示 3 个共用几何形状、位置和颜色不同的三角形。高频用法
实例位置、颜色或缩放通常各占一个实例属性并设置除数 1。实例变换矩阵需要拆成四个 vec4 属性,四个属性都要调用 vertexAttribDivisor(location, 1)。
静态实例数据用 STATIC_DRAW;每帧更新实例缓冲时可用 DYNAMIC_DRAW,并优先通过 bufferSubData 更新已有存储。网格已使用索引缓冲时,改用 drawElementsInstanced,索引数量仍表示单个实例的索引数。
风险与边界
当 instanceCount 大于实例缓冲可提供的数据组数时,着色器可能读取越界数据并产生未定义结果。安全做法是按最短实例属性数组计算实例数,并在绘制前校验容量。
实例矩阵会快速消耗顶点属性槽位,超过 MAX_VERTEX_ATTRIBS 会导致属性配置失败。可先查询限制,再把部分数据改放纹理或统一缓冲方案中。
实例化减少绘制调用,但不会自动减少片元填充、透明混合或过度绘制成本。对象遮挡严重时仍应配合视锥裁剪、距离分级或批次拆分。
排障清单
- 所有实例重叠:检查位移或矩阵属性是否设置了除数
1。 - 颜色按顶点变化:颜色属性的除数仍为
0。 - 只显示部分实例:核对实例缓冲长度、
instanceCount和属性步长。 - 画面完全空白:检查程序链接、属性位置、视口及裁剪空间坐标。
速查:共享几何属性使用除数 0,每实例属性使用除数 1,最后只调用一次实例化绘制。
捕获顶点着色器输出,用于粒子更新和 GPU 数据计算。
使用变换反馈
变换反馈把顶点着色器的输出直接写入 GPU 缓冲区,不经过光栅化即可完成批量计算。常用于粒子位置更新、动画数据生成和下一帧输入准备。

基本流程
必须在程序链接前调用 transformFeedbackVaryings 声明要捕获的输出。执行时绑定输出缓冲,开启 RASTERIZER_DISCARD,再以点、线或三角形模式调用绘制。
gl.transformFeedbackVaryings(program, ["vValue"], gl.SEPARATE_ATTRIBS);
gl.linkProgram(program);
gl.enable(gl.RASTERIZER_DISCARD);
gl.beginTransformFeedback(gl.POINTS);
gl.drawArrays(gl.POINTS, 0, count);
gl.endTransformFeedback();
gl.disable(gl.RASTERIZER_DISCARD);以上是片段示例,捕获模式必须与实际绘制图元兼容。
可运行示例
示例把输入数组 [1, 2, 3, 4] 交给顶点着色器乘以 2,结果写入另一个缓冲区并读回验证。
<!doctype html>
<meta charset="utf-8">
<canvas id="gl" width="1" height="1"></canvas>
<script>
const gl = document.querySelector("#gl").getContext("webgl2");
if (!gl) throw new Error("需要支持 WebGL 2");
function compile(type, source) {
const s = gl.createShader(type);
gl.shaderSource(s, source);
gl.compileShader(s);
if (!gl.getShaderParameter(s, gl.COMPILE_STATUS)) {
throw new Error(gl.getShaderInfoLog(s));
}
return s;
}
const vs = compile(gl.VERTEX_SHADER, `#version 300 es
in float aValue;
out float vValue;
void main() {
vValue = aValue * 2.0;
gl_Position = vec4(0.0);
}`);
const fs = compile(gl.FRAGMENT_SHADER, `#version 300 es
precision mediump float;
out vec4 outColor;
void main() {
outColor = vec4(1.0);
}`);
const program = gl.createProgram();
gl.attachShader(program, vs);
gl.attachShader(program, fs);
// 捕获列表必须在 linkProgram 之前设置
gl.transformFeedbackVaryings(program, ["vValue"], gl.SEPARATE_ATTRIBS);
gl.linkProgram(program);
if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
throw new Error(gl.getProgramInfoLog(program));
}
gl.useProgram(program);
const vao = gl.createVertexArray();
gl.bindVertexArray(vao);
const input = new Float32Array([1, 2, 3, 4]);
const inputBuffer = gl.createBuffer();
gl.bindBuffer(gl.ARRAY_BUFFER, inputBuffer);
gl.bufferData(gl.ARRAY_BUFFER, input, gl.STATIC_DRAW);
const location = gl.getAttribLocation(program, "aValue");
gl.enableVertexAttribArray(location);
gl.vertexAttribPointer(location, 1, gl.FLOAT, false, 0, 0);
const outputBuffer = gl.createBuffer();
gl.bindBuffer(gl.TRANSFORM_FEEDBACK_BUFFER, outputBuffer);
gl.bufferData(gl.TRANSFORM_FEEDBACK_BUFFER, input.byteLength, gl.DYNAMIC_COPY);
const tf = gl.createTransformFeedback();
gl.bindTransformFeedback(gl.TRANSFORM_FEEDBACK, tf);
// 输出绑定属于当前 transform feedback 对象,顺序不能颠倒
gl.bindBufferBase(gl.TRANSFORM_FEEDBACK_BUFFER, 0, outputBuffer);
gl.enable(gl.RASTERIZER_DISCARD);
gl.beginTransformFeedback(gl.POINTS);
gl.drawArrays(gl.POINTS, 0, input.length);
gl.endTransformFeedback();
gl.disable(gl.RASTERIZER_DISCARD);
const result = new Float32Array(input.length);
gl.bindBuffer(gl.ARRAY_BUFFER, outputBuffer);
gl.getBufferSubData(gl.ARRAY_BUFFER, 0, result);
console.log(Array.from(result).join(", "));
</script>预期结果
2, 4, 6, 8读取方法:输出顺序与输入顶点顺序一致,每个元素是顶点着色器写出的 vValue。
捕获模式与缓冲布局
SEPARATE_ATTRIBS 为每个 varying 绑定一个独立输出缓冲,配置直观;INTERLEAVED_ATTRIBS 把多个 varying 交错写入同一缓冲,适合把位置、速度等组成一条粒子记录。
捕获多个输出时,bindBufferBase 的索引必须与 varying 列表顺序一致。交错模式通常只绑定索引 0,并按着色器输出类型计算每条记录的字节跨度。
高频用法
粒子系统通常准备 A、B 两个同尺寸缓冲:本帧从 A 读取并写入 B,下一帧交换角色。更新阶段启用光栅化丢弃;渲染阶段关闭丢弃,并把刚生成的缓冲作为普通顶点属性读取。
只需 GPU 内继续消费结果时,不要每帧调用 getBufferSubData。读回会迫使 CPU 等待 GPU,适合调试和离线验证,不适合实时主循环。
风险与边界
同一缓冲不能同时作为当前顶点输入和变换反馈输出,否则形成读写反馈环并触发错误。安全替代是双缓冲 ping-pong,执行完后交换引用。
输出缓冲容量小于着色器实际写入量时,绘制会失败或产生 INVALID_OPERATION。应按顶点数、每顶点输出字节数和捕获布局预先计算容量。
忘记关闭 RASTERIZER_DISCARD 会导致后续正常绘制没有任何片元输出。建议把启用、开始、结束和关闭放在同一更新函数中,并在异常路径使用 try/finally 恢复状态。
排障清单
- 链接失败:确认 varying 名称与顶点着色器输出完全一致,并在链接前注册。
- 输出全为零:检查属性是否启用、输出缓冲是否通过
bindBufferBase绑定。 - 触发
INVALID_OPERATION:排查输入输出是否复用了同一缓冲,以及输出容量是否足够。 - 粒子只更新一帧:检查 A/B 缓冲是否在每帧结束后交换。
速查:先声明捕获输出并链接程序,再绑定输出缓冲、开启丢弃、执行绘制,最后结束捕获并恢复状态。
从颜色缓冲区读取像素数据,用于截图、检测和结果导出。
读取渲染像素
使用 gl.readPixels() 把当前读取缓冲区中的像素复制到 JavaScript 类型数组。常用于单点颜色检测、离屏渲染验收、截图导出和鼠标拾取结果读取。
基本语法
gl.readPixels(x, y, width, height, format, type, destination);WebGL 1 常用组合是 format = gl.RGBA、type = gl.UNSIGNED_BYTE,目标数组使用 Uint8Array(width * height * 4)。坐标原点位于左下角,不是 DOM 事件使用的左上角。
读取单个像素
下面的代码可直接粘贴到浏览器控制台运行。它创建画布、清空为固定颜色,再读取中心像素。
const canvas = document.createElement("canvas");
canvas.width = 64;
canvas.height = 64;
document.body.appendChild(canvas);
const gl = canvas.getContext("webgl");
if (!gl) throw new Error("当前浏览器不支持 WebGL");
gl.clearColor(0.2, 0.4, 0.6, 1.0);
gl.clear(gl.COLOR_BUFFER_BIT);
// readPixels 的 y 从画布底部开始计算。
const pixel = new Uint8Array(4);
gl.readPixels(
32,
32,
1,
1,
gl.RGBA,
gl.UNSIGNED_BYTE,
pixel
);
console.log(Array.from(pixel));预期输出
[51, 102, 153, 255]四个值依次是红、绿、蓝、透明度,范围为 0~255。实际浏览器若使用不同颜色缓冲格式或发生颜色转换,边界值可能有少量差异。
读取矩形区域
读取整块区域时,目标数组长度必须精确匹配。下面是片段示例,依赖上一节已经创建的 gl 和 64 × 64 画布。读取默认帧缓冲区前,应先确认当前绑定的是目标缓冲区;读取离屏结果时先绑定对应 framebuffer。
const width = gl.drawingBufferWidth;
const height = gl.drawingBufferHeight;
const pixels = new Uint8Array(width * height * 4);
gl.bindFramebuffer(gl.FRAMEBUFFER, null);
gl.readPixels(
0,
0,
width,
height,
gl.RGBA,
gl.UNSIGNED_BYTE,
pixels
);
console.log(`读取 ${pixels.length} 个通道值`);预期输出
读取 16384 个通道值这里画布为 64 × 64,因此长度是 64 × 64 × 4 = 16384。实际尺寸变化时输出数字会不同。
风险与边界
readPixels() 会等待之前的绘制完成。若在每帧读取整张画布,容易造成 GPU 与 CPU 同步停顿,表现为掉帧。安全做法是只在用户触发截图、检测或拾取时读取,并尽量缩小读取区域。
DOM 鼠标坐标需要转换为绘图缓冲区坐标,尤其要处理 CSS 缩放和 Y 轴翻转。读取前还要检查 framebuffer 是否完整,否则可能得到全零数据或触发 INVALID_FRAMEBUFFER_OPERATION。
排障清单
- 全部为零:确认读取发生在绘制之后,且没有在读取前清空目标缓冲区。
- 位置偏移:使用
canvas.getBoundingClientRect()换算 CSS 坐标,并按drawingBufferHeight - 1 - y翻转 Y。 - 读取离屏纹理失败:检查
gl.checkFramebufferStatus(gl.FRAMEBUFFER)是否返回gl.FRAMEBUFFER_COMPLETE。 - 性能突降:避免在动画循环中读取大区域;先缩小到
1 × 1或低分辨率检测缓冲区。
速查:读取单点分配 4 字节,读取区域分配 width * height * 4 字节,并始终核对当前绑定的 framebuffer。
通过颜色编码或射线检测识别用户点击的场景对象。
实现鼠标拾取
鼠标拾取用于把一次画布点击转换为场景对象 ID。对象数量不多且已有 WebGL 渲染管线时,颜色编码拾取最直接:把每个对象以唯一纯色绘制到离屏 framebuffer,再读取点击位置的一个像素。

实现步骤
拾取渲染必须与可见渲染使用相同的几何位置、视口和变换矩阵,只把片元颜色替换成对象 ID。点击时先完成坐标换算,再绑定拾取 framebuffer、绘制 ID 颜色、读取一个像素并恢复默认 framebuffer。
ID 可编码到 RGB 三个通道中:
function idToColor(id) {
return [
(id & 0xff) / 255,
((id >> 8) & 0xff) / 255,
((id >> 16) & 0xff) / 255,
1
];
}
function colorToId(pixel) {
return pixel[0] | (pixel[1] << 8) | (pixel[2] << 16);
}
const encoded = idToColor(257);
console.log(encoded.map((value) => Math.round(value * 255)));
console.log(colorToId(new Uint8Array([1, 1, 0, 255])));预期输出
[1, 1, 0, 255]
257完整示例
下面示例创建两个矩形。正常画面显示红色和绿色,点击后使用离屏颜色缓冲读取对象 ID,并在控制台输出结果。
const canvas = document.createElement("canvas");
canvas.width = 400;
canvas.height = 240;
canvas.style.border = "1px solid #999";
document.body.appendChild(canvas);
const gl = canvas.getContext("webgl", { antialias: false });
if (!gl) throw new Error("当前浏览器不支持 WebGL");
const vertexSource = `
attribute vec2 a_position;
uniform vec2 u_offset;
void main() {
gl_Position = vec4(a_position + u_offset, 0.0, 1.0);
}
`;
const fragmentSource = `
precision mediump float;
uniform vec4 u_color;
void main() {
gl_FragColor = u_color;
}
`;
function createShader(type, source) {
const shader = gl.createShader(type);
gl.shaderSource(shader, source);
gl.compileShader(shader);
if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
throw new Error(gl.getShaderInfoLog(shader));
}
return shader;
}
const program = gl.createProgram();
gl.attachShader(program, createShader(gl.VERTEX_SHADER, vertexSource));
gl.attachShader(program, createShader(gl.FRAGMENT_SHADER, fragmentSource));
gl.linkProgram(program);
if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
throw new Error(gl.getProgramInfoLog(program));
}
const buffer = gl.createBuffer();
gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
gl.bufferData(
gl.ARRAY_BUFFER,
new Float32Array([
-0.25, -0.25,
0.25, -0.25,
-0.25, 0.25,
-0.25, 0.25,
0.25, -0.25,
0.25, 0.25
]),
gl.STATIC_DRAW
);
const positionLoc = gl.getAttribLocation(program, "a_position");
const offsetLoc = gl.getUniformLocation(program, "u_offset");
const colorLoc = gl.getUniformLocation(program, "u_color");
const pickTexture = gl.createTexture();
gl.bindTexture(gl.TEXTURE_2D, pickTexture);
gl.texImage2D(
gl.TEXTURE_2D,
0,
gl.RGBA,
canvas.width,
canvas.height,
0,
gl.RGBA,
gl.UNSIGNED_BYTE,
null
);
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
const pickFramebuffer = gl.createFramebuffer();
gl.bindFramebuffer(gl.FRAMEBUFFER, pickFramebuffer);
gl.framebufferTexture2D(
gl.FRAMEBUFFER,
gl.COLOR_ATTACHMENT0,
gl.TEXTURE_2D,
pickTexture,
0
);
if (gl.checkFramebufferStatus(gl.FRAMEBUFFER) !== gl.FRAMEBUFFER_COMPLETE) {
throw new Error("拾取 framebuffer 不完整");
}
const objects = [
{ id: 1, offset: [-0.45, 0], color: [1, 0, 0, 1] },
{ id: 2, offset: [0.45, 0], color: [0, 0.7, 0, 1] }
];
function idToColor(id) {
return [
(id & 0xff) / 255,
((id >> 8) & 0xff) / 255,
((id >> 16) & 0xff) / 255,
1
];
}
function draw(picking) {
gl.viewport(0, 0, canvas.width, canvas.height);
gl.clearColor(0, 0, 0, 0);
gl.clear(gl.COLOR_BUFFER_BIT);
gl.useProgram(program);
gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
gl.enableVertexAttribArray(positionLoc);
gl.vertexAttribPointer(positionLoc, 2, gl.FLOAT, false, 0, 0);
for (const object of objects) {
gl.uniform2fv(offsetLoc, object.offset);
gl.uniform4fv(colorLoc, picking ? idToColor(object.id) : object.color);
gl.drawArrays(gl.TRIANGLES, 0, 6);
}
}
gl.bindFramebuffer(gl.FRAMEBUFFER, null);
draw(false);
canvas.addEventListener("click", (event) => {
const rect = canvas.getBoundingClientRect();
const x = Math.floor(
(event.clientX - rect.left) * canvas.width / rect.width
);
const y = Math.floor(
canvas.height - 1 -
(event.clientY - rect.top) * canvas.height / rect.height
);
// 拾取缓冲区禁用混合和抖动,避免 ID 颜色被修改。
const blendWasEnabled = gl.isEnabled(gl.BLEND);
const ditherWasEnabled = gl.isEnabled(gl.DITHER);
gl.bindFramebuffer(gl.FRAMEBUFFER, pickFramebuffer);
gl.disable(gl.BLEND);
gl.disable(gl.DITHER);
draw(true);
const pixel = new Uint8Array(4);
gl.readPixels(x, y, 1, 1, gl.RGBA, gl.UNSIGNED_BYTE, pixel);
const id = pixel[0] | (pixel[1] << 8) | (pixel[2] << 16);
gl.bindFramebuffer(gl.FRAMEBUFFER, null);
if (blendWasEnabled) gl.enable(gl.BLEND);
if (ditherWasEnabled) gl.enable(gl.DITHER);
draw(false);
console.log(id === 0 ? "未命中对象" : `命中对象 ID: ${id}`);
});预期结果
点击左侧矩形:命中对象 ID: 1
点击右侧矩形:命中对象 ID: 2
点击空白区域:未命中对象关键边界
拾取缓冲区必须关闭抗锯齿、混合、颜色空间转换和会修改片元颜色的后处理,否则边缘像素可能被混合成错误 ID。安全做法是使用 NEAREST 纹理过滤、禁用 BLEND 与 DITHER,并为拾取单独维护简单着色器。
高 DPI 页面不能直接使用 event.offsetX 作为读取坐标。应根据 getBoundingClientRect() 和实际 canvas.width、canvas.height 换算,否则点击位置会按设备像素比产生偏移。
对象数量很大、需要拾取三角形内部位置或已有 CPU 空间索引时,可改用射线检测。颜色拾取更适合快速获取对象级 ID,但每次点击会产生一次额外绘制和一次同步像素读取。
排障清单
- 始终返回 0:确认拾取 framebuffer 已绑定、已绘制,并且清屏颜色编码为 ID 0。
- 命中相邻对象:关闭混合、抖动和多重采样,避免边缘颜色插值。
- 点击位置上下颠倒:将 DOM 的 Y 坐标转换为
drawingBufferHeight - 1 - y。 - 画布缩放后偏移:使用 CSS 尺寸与 drawing buffer 尺寸的比例换算。
- 场景移动后拾取错误:可见渲染与拾取渲染必须使用同一套模型、视图和投影矩阵。
速查:颜色编码拾取的稳定性取决于“同几何、纯 ID 色、正确坐标、只读 1 像素”四点。
使用 requestAnimationFrame 按帧更新时间、状态并执行绘制。
构建 WebGL 动画循环
用 requestAnimationFrame 驱动每一帧:先根据时间差更新状态,再提交 WebGL 绘制。浏览器会把回调与屏幕刷新同步,页面不可见时通常自动降频。
基本结构
片段示例:依赖同一作用域中已定义的 update 和 render。每帧接收高精度时间戳 timestamp,用它计算 deltaTime,不要假设设备固定为 60 FPS。
let lastTime = 0;
function frame(timestamp) {
if (lastTime === 0) {
lastTime = timestamp;
}
const deltaTime = Math.min((timestamp - lastTime) / 1000, 0.1);
lastTime = timestamp;
update(deltaTime);
render();
requestAnimationFrame(frame);
}
requestAnimationFrame(frame);deltaTime 的单位是秒;上限 0.1 用于防止切回页面后一次更新跨越过长时间。
可运行示例
下面代码创建一个 WebGL 三角形,并按真实经过时间持续旋转。
<!doctype html>
<html lang="zh-CN">
<head>
<meta charset="utf-8">
<title>WebGL 动画循环</title>
<style>
canvas { width: 480px; height: 320px; border: 1px solid #ccc; }
</style>
</head>
<body>
<canvas id="glcanvas" width="480" height="320"></canvas>
<script>
const canvas = document.getElementById("glcanvas");
const gl = canvas.getContext("webgl");
if (!gl) {
throw new Error("当前浏览器不支持 WebGL");
}
function compileShader(type, source) {
const shader = gl.createShader(type);
gl.shaderSource(shader, source);
gl.compileShader(shader);
if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
const message = gl.getShaderInfoLog(shader);
gl.deleteShader(shader);
throw new Error(message);
}
return shader;
}
const vertexShader = compileShader(gl.VERTEX_SHADER, `
attribute vec2 aPosition;
uniform float uAngle;
void main() {
float c = cos(uAngle);
float s = sin(uAngle);
vec2 rotated = vec2(
aPosition.x * c - aPosition.y * s,
aPosition.x * s + aPosition.y * c
);
gl_Position = vec4(rotated, 0.0, 1.0);
}
`);
const fragmentShader = compileShader(gl.FRAGMENT_SHADER, `
precision mediump float;
void main() {
gl_FragColor = vec4(0.10, 0.55, 0.95, 1.0);
}
`);
const program = gl.createProgram();
gl.attachShader(program, vertexShader);
gl.attachShader(program, fragmentShader);
gl.linkProgram(program);
if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
throw new Error(gl.getProgramInfoLog(program));
}
const vertices = new Float32Array([
0.0, 0.6,
-0.5, -0.4,
0.5, -0.4
]);
const buffer = gl.createBuffer();
gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
gl.bufferData(gl.ARRAY_BUFFER, vertices, gl.STATIC_DRAW);
const aPosition = gl.getAttribLocation(program, "aPosition");
const uAngle = gl.getUniformLocation(program, "uAngle");
gl.useProgram(program);
gl.enableVertexAttribArray(aPosition);
gl.vertexAttribPointer(aPosition, 2, gl.FLOAT, false, 0, 0);
let angle = 0;
let lastTime = 0;
function update(deltaTime) {
angle = (angle + deltaTime) % (Math.PI * 2);
}
function render() {
gl.viewport(0, 0, canvas.width, canvas.height);
gl.clearColor(0.04, 0.05, 0.08, 1.0);
gl.clear(gl.COLOR_BUFFER_BIT);
gl.uniform1f(uAngle, angle);
gl.drawArrays(gl.TRIANGLES, 0, 3);
}
function frame(timestamp) {
if (lastTime === 0) {
lastTime = timestamp;
}
// 限制大时间差,避免调试暂停或切换标签页后状态突跳。
const deltaTime = Math.min((timestamp - lastTime) / 1000, 0.1);
lastTime = timestamp;
update(deltaTime);
render();
requestAnimationFrame(frame);
}
requestAnimationFrame(frame);
</script>
</body>
</html>预期结果
页面显示一个蓝色三角形,并以接近每秒 1 弧度的速度平滑旋转。
刷新率不同的设备上,旋转速度基本一致。高频用法
需要固定步长物理更新时,可累计 deltaTime,按固定间隔多次调用 update,最后只绘制一次。普通 UI 动画直接使用可变步长更简单。
只在状态变化时重绘的编辑器或图表,不必保持永久循环;修改状态后调用一次 requestAnimationFrame(render),并用布尔标记避免重复排队。
风险与边界
直接使用“每帧增加固定角度”会让动画速度依赖刷新率,144 Hz 屏幕会明显快于 60 Hz。安全做法是按 deltaTime 更新。
切换标签页、断点调试或设备卡顿会产生很大的时间差,可能导致物体穿透、状态突跳。应限制最大 deltaTime,严格物理模拟则改用固定步长累计器。
不要在一次回调中重复调用多个 requestAnimationFrame,否则循环数量会倍增,造成重复绘制和 CPU、GPU 占用上升。始终保证每个活动循环只有一个下一帧请求。
排障清单
- 画面静止:确认首次调用了
requestAnimationFrame(frame),且回调末尾仍会安排下一帧。 - 速度忽快忽慢:检查是否使用时间差,并确认单位已从毫秒换算为秒。
- 画面黑屏:检查着色器编译、程序链接、顶点属性绑定和
gl.viewport。 - 页面切回后突跳:重置
lastTime或限制最大deltaTime。
速查:动画循环的稳定顺序是“计算时间差 → 更新状态 → 绘制 → 请求下一帧”。
在页面或画布不可见时暂停动画,降低 CPU、GPU 和电量消耗。
暂停不可见渲染
当页面进入后台或画布滚出视口时,停止申请下一帧;重新可见后再恢复,并重置上一帧时间,避免状态突然跳变。
可见性判断
document.visibilityState 判断整个页面是否可见,IntersectionObserver 判断画布是否进入视口。两者同时满足时才运行动画。
片段示例:依赖同一作用域中已定义的 canvasInViewport。
const shouldRender = () =>
document.visibilityState === "visible" && canvasInViewport;页面隐藏时,浏览器通常会节流 requestAnimationFrame,但显式暂停仍可阻止业务更新、计时器联动和恢复时的大时间差。
可运行示例
下面示例持续改变 WebGL 清屏颜色。切换标签页或把画布滚出视口后暂停,恢复可见时继续。
<!doctype html>
<html lang="zh-CN">
<head>
<meta charset="utf-8">
<title>暂停不可见 WebGL 渲染</title>
<style>
body { margin: 0; font-family: sans-serif; }
.spacer { height: 900px; padding: 16px; box-sizing: border-box; }
canvas { display: block; width: 480px; height: 320px; margin: 24px auto; }
#status { text-align: center; }
</style>
</head>
<body>
<div class="spacer">向下滚动查看画布。</div>
<p id="status">等待画布进入视口</p>
<canvas id="glcanvas" width="480" height="320"></canvas>
<div class="spacer">继续滚动可让画布离开视口。</div>
<script>
const canvas = document.getElementById("glcanvas");
const status = document.getElementById("status");
const gl = canvas.getContext("webgl");
if (!gl) {
throw new Error("当前浏览器不支持 WebGL");
}
let frameId = null;
let canvasInViewport = false;
let lastTime = 0;
let phase = 0;
function shouldRender() {
return document.visibilityState === "visible" && canvasInViewport;
}
function render(timestamp) {
if (!shouldRender()) {
frameId = null;
return;
}
if (lastTime === 0) {
lastTime = timestamp;
}
const deltaTime = Math.min((timestamp - lastTime) / 1000, 0.1);
lastTime = timestamp;
phase += deltaTime;
const red = (Math.sin(phase) + 1) / 2;
gl.viewport(0, 0, canvas.width, canvas.height);
gl.clearColor(red, 0.25, 0.65, 1.0);
gl.clear(gl.COLOR_BUFFER_BIT);
frameId = requestAnimationFrame(render);
}
function startIfNeeded() {
if (shouldRender() && frameId === null) {
// 恢复时重置时间基准,避免把暂停时长计入下一帧。
lastTime = 0;
frameId = requestAnimationFrame(render);
status.textContent = "渲染中";
} else if (!shouldRender()) {
stop();
}
}
function stop() {
if (frameId !== null) {
cancelAnimationFrame(frameId);
frameId = null;
}
lastTime = 0;
status.textContent = "已暂停";
}
document.addEventListener("visibilitychange", startIfNeeded);
const observer = new IntersectionObserver(
([entry]) => {
canvasInViewport = entry.isIntersecting;
startIfNeeded();
},
{ threshold: 0.01 }
);
observer.observe(canvas);
</script>
</body>
</html>预期结果
画布进入视口且标签页可见时,背景颜色持续变化,状态显示“渲染中”。
画布离开视口或标签页进入后台时,状态显示“已暂停”,恢复后动画从当前状态继续。高频用法
只有页面级后台暂停需求时,仅监听 visibilitychange 即可。长列表、仪表盘或多个 WebGL 画布应再加 IntersectionObserver,避免渲染屏幕外内容。
播放视频、音频或联网对战时,不要把“停止绘制”等同于“停止业务”。渲染、音频、网络同步和游戏逻辑应分别控制,必要时后台只降低更新频率。
风险与边界
只调用 cancelAnimationFrame 但没有清除 frameId,恢复逻辑可能误判循环仍在运行,导致永久停帧。取消后应把句柄设为 null。
每次可见性变化都直接启动新循环,会形成多个并行回调,导致帧率异常和资源占用翻倍。启动前必须检查当前是否已有活动的 frameId。
IntersectionObserver 只表示元素与视口相交,不保证用户真正看得到;元素可能被遮挡、透明或位于后台标签页。安全做法是同时检查页面可见性,并把它作为性能优化而非业务权限判断。
排障清单
- 恢复后不再渲染:检查
frameId是否在停止时清空,以及恢复条件是否同时满足。 - 恢复首帧突跳:确认暂停和恢复时重置了
lastTime。 - 页面后台仍耗电:检查是否还有
setInterval、Worker、视频解码或其他独立任务。 - 快速滚动时重复启动:确认启动函数使用
frameId === null做幂等保护。 - 观察器不触发:确认目标元素已插入文档,并检查
threshold与滚动容器配置。
速查:页面可见且画布在视口内才启动;任一条件失效立即停止并清空帧句柄。
通过批处理、实例化和状态排序降低绘制调用与状态切换开销。
减少 WebGL 绘制调用
当场景中存在大量使用相同几何或材质的对象时,优先把多个对象合并为一次提交,或使用实例化绘制;材质不同但无法合并时,按程序、纹理和混合状态排序,减少 CPU 到 GPU 的调用与状态切换。
命令定位
重点观察每帧 drawArrays、drawElements、drawArraysInstanced 和 drawElementsInstanced 的调用次数。帧率随对象数量下降、JavaScript 主线程耗时高但着色器并不复杂时,通常先查绘制调用和状态切换,而不是先改 GLSL。

选择策略
- 批处理:多个静态对象使用相同着色器、纹理和顶点格式时,将顶点与索引写入同一缓冲区,再一次绘制。适合地图块、静态 UI、粒子快照。
- 实例化:多个对象共享同一网格,只是位置、缩放、颜色等实例数据不同。WebGL 2 直接使用实例化 API;WebGL 1 通过
ANGLE_instanced_arrays。 - 状态排序:对象不能合并时,先按
program → framebuffer → blend/depth state → texture分组,避免反复useProgram、bindTexture和启停混合。 - 纹理图集:小纹理数量多且采样规则一致时,合并到图集,减少纹理绑定;边缘需留 padding,避免双线性采样串色。
高频用法
下面示例在 WebGL 2 中用一个四边形和 100 组实例偏移,只执行一次绘制调用。复制到浏览器控制台即可运行。
(() => {
const canvas = document.createElement("canvas");
canvas.width = 640;
canvas.height = 360;
document.body.appendChild(canvas);
const gl = canvas.getContext("webgl2");
if (!gl) throw new Error("当前浏览器不支持 WebGL 2");
const compile = (type, source) => {
const shader = gl.createShader(type);
gl.shaderSource(shader, source);
gl.compileShader(shader);
if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
throw new Error(gl.getShaderInfoLog(shader) || "shader compile failed");
}
return shader;
};
const vs = compile(gl.VERTEX_SHADER, `#version 300 es
layout(location = 0) in vec2 aPosition;
layout(location = 1) in vec2 aOffset;
void main() {
gl_Position = vec4(aPosition * 0.035 + aOffset, 0.0, 1.0);
}`);
const fs = compile(gl.FRAGMENT_SHADER, `#version 300 es
precision mediump float;
out vec4 outColor;
void main() {
outColor = vec4(0.1, 0.7, 0.9, 1.0);
}`);
const program = gl.createProgram();
gl.attachShader(program, vs);
gl.attachShader(program, fs);
gl.linkProgram(program);
if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
throw new Error(gl.getProgramInfoLog(program) || "program link failed");
}
const positions = new Float32Array([
-1, -1, 1, -1, -1, 1, 1, 1
]);
const offsets = new Float32Array(100 * 2);
for (let i = 0; i < 100; i++) {
offsets[i * 2] = -0.9 + (i % 10) * 0.2;
offsets[i * 2 + 1] = -0.9 + Math.floor(i / 10) * 0.2;
}
const vao = gl.createVertexArray();
gl.bindVertexArray(vao);
const positionBuffer = gl.createBuffer();
gl.bindBuffer(gl.ARRAY_BUFFER, positionBuffer);
gl.bufferData(gl.ARRAY_BUFFER, positions, gl.STATIC_DRAW);
gl.enableVertexAttribArray(0);
gl.vertexAttribPointer(0, 2, gl.FLOAT, false, 0, 0);
const offsetBuffer = gl.createBuffer();
gl.bindBuffer(gl.ARRAY_BUFFER, offsetBuffer);
gl.bufferData(gl.ARRAY_BUFFER, offsets, gl.STATIC_DRAW);
gl.enableVertexAttribArray(1);
gl.vertexAttribPointer(1, 2, gl.FLOAT, false, 0, 0);
gl.vertexAttribDivisor(1, 1); // 每个实例读取一组偏移
gl.viewport(0, 0, canvas.width, canvas.height);
gl.clearColor(0.04, 0.06, 0.1, 1);
gl.clear(gl.COLOR_BUFFER_BIT);
gl.useProgram(program);
gl.drawArraysInstanced(gl.TRIANGLE_STRIP, 0, 4, 100);
console.log("instances=100, drawCalls=1");
})();预期输出:
instances=100, drawCalls=1画布会显示 10×10 个青色方块。控制台中的 drawCalls=1 表示 100 个实例由一次 drawArraysInstanced 提交;实际项目应在渲染器中统一计数,而不是按对象数推测。
风险与边界
批处理会扩大缓冲区更新范围。触发条件是动态对象频繁移动却仍合并在大缓冲中,后果是每帧上传大量顶点数据;安全替代方案是把静态和动态对象分批,动态数据使用独立缓冲或实例属性。
状态排序可能改变透明对象顺序。触发条件是开启 alpha 混合后只按材质分组,后果是前后遮挡错误;安全替代方案是不透明对象按状态排序,透明对象先按材质粗分组,再按相机距离从远到近绘制。
纹理图集在 mipmap 和线性过滤下可能串色。触发条件是子图边缘没有扩边,后果是缩小时采到相邻图块;安全替代方案是增加 2~4 像素 padding,并同步调整 UV。
排障清单
- 统计每帧绘制调用、程序切换、纹理绑定次数,并与对象数量对照。
- 确认实例属性已调用
vertexAttribDivisor(location, 1);遗漏时所有实例会读取错误数据。 - 使用实例化后仍慢,继续检查缓冲区上传量、顶点数量、过度绘制和片元着色器成本。
- WebGL 1 中先检测
ANGLE_instanced_arrays;扩展不存在时回退为批处理或普通循环绘制。
速查结论:相同网格优先实例化,相同静态材质优先批处理,无法合并时按状态排序;透明对象不要只按材质重排。
删除不再使用的缓冲区、纹理、着色器、程序和帧缓冲区资源。
释放 WebGL 资源
对象从场景移除、页面切换或渲染器销毁时,应停止继续使用该对象,解除绑定并调用对应的 delete* API。这样可避免纹理、缓冲区和帧缓冲区长期占用 GPU 内存,导致后续分配失败或上下文丢失。
命令定位
常用释放 API 与创建 API 一一对应:deleteBuffer、deleteTexture、deleteShader、deleteProgram、deleteFramebuffer、deleteRenderbuffer、deleteVertexArray。WebGL 没有统一的 dispose(),应用必须保存资源句柄并在明确的生命周期节点集中清理。

基本语法
gl.bindBuffer(gl.ARRAY_BUFFER, null);
gl.deleteBuffer(buffer);
gl.bindTexture(gl.TEXTURE_2D, null);
gl.deleteTexture(texture);
gl.useProgram(null);
gl.deleteProgram(program);
gl.bindFramebuffer(gl.FRAMEBUFFER, null);
gl.deleteFramebuffer(framebuffer);删除调用通常会把对象标记为删除;若 GPU 或其他对象仍在引用,底层回收可能延后。应用层仍应立即把自己的引用设为 null,防止后续误用。
高频用法
下面示例创建缓冲区、纹理、着色器、程序和帧缓冲区,然后统一解除绑定并释放。复制到浏览器控制台即可运行。
(() => {
const canvas = document.createElement("canvas");
const gl = canvas.getContext("webgl2");
if (!gl) throw new Error("当前浏览器不支持 WebGL 2");
const compile = (type, source) => {
const shader = gl.createShader(type);
gl.shaderSource(shader, source);
gl.compileShader(shader);
if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
throw new Error(gl.getShaderInfoLog(shader) || "shader compile failed");
}
return shader;
};
let buffer = gl.createBuffer();
gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
gl.bufferData(gl.ARRAY_BUFFER, new Float32Array([0, 0]), gl.STATIC_DRAW);
let texture = gl.createTexture();
gl.bindTexture(gl.TEXTURE_2D, texture);
gl.texImage2D(
gl.TEXTURE_2D, 0, gl.RGBA, 1, 1, 0,
gl.RGBA, gl.UNSIGNED_BYTE, new Uint8Array([255, 0, 0, 255])
);
let vertexShader = compile(
gl.VERTEX_SHADER,
`#version 300 es
void main() { gl_Position = vec4(0.0); }`
);
let fragmentShader = compile(
gl.FRAGMENT_SHADER,
`#version 300 es
precision mediump float;
out vec4 outColor;
void main() { outColor = vec4(1.0); }`
);
let program = gl.createProgram();
gl.attachShader(program, vertexShader);
gl.attachShader(program, fragmentShader);
gl.linkProgram(program);
if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
throw new Error(gl.getProgramInfoLog(program) || "program link failed");
}
// 链接完成后 shader 可标记删除,program 仍可正常使用
gl.deleteShader(vertexShader);
gl.deleteShader(fragmentShader);
vertexShader = null;
fragmentShader = null;
let framebuffer = gl.createFramebuffer();
gl.bindFramebuffer(gl.FRAMEBUFFER, framebuffer);
gl.framebufferTexture2D(
gl.FRAMEBUFFER,
gl.COLOR_ATTACHMENT0,
gl.TEXTURE_2D,
texture,
0
);
gl.bindFramebuffer(gl.FRAMEBUFFER, null);
gl.bindTexture(gl.TEXTURE_2D, null);
gl.bindBuffer(gl.ARRAY_BUFFER, null);
gl.useProgram(null);
gl.deleteFramebuffer(framebuffer);
gl.deleteTexture(texture);
gl.deleteBuffer(buffer);
gl.deleteProgram(program);
framebuffer = null;
texture = null;
buffer = null;
program = null;
console.log({
arrayBufferBinding: gl.getParameter(gl.ARRAY_BUFFER_BINDING),
texture2DBinding: gl.getParameter(gl.TEXTURE_BINDING_2D),
framebufferBinding: gl.getParameter(gl.FRAMEBUFFER_BINDING),
currentProgram: gl.getParameter(gl.CURRENT_PROGRAM)
});
})();预期输出:
{
arrayBufferBinding: null,
texture2DBinding: null,
framebufferBinding: null,
currentProgram: null
}输出只验证当前绑定已清空。生产环境还应在资源管理器中维护创建数与释放数,页面反复进入退出后两者应趋于平衡。
推荐释放顺序
先停止 requestAnimationFrame 或让对象退出渲染队列,再解绑帧缓冲区、程序、纹理、缓冲区,最后调用对应 delete*。帧缓冲区引用的纹理或渲染缓冲区需要分别删除,删除 framebuffer 本身不会自动释放附件。
程序链接成功后,着色器对象通常可立即 deleteShader;程序仍持有已链接结果。程序不再使用时再 deleteProgram。多个材质共享同一纹理或程序时,应使用引用计数或资源所有权表,最后一个使用者退出后才删除。
风险与边界
提前删除共享资源的触发条件是多个对象共用同一纹理、缓冲区或程序,但任一对象销毁时直接删除。后果是其他对象下一帧黑屏、绘制错误或产生 INVALID_OPERATION;安全替代方案是引用计数、资源句柄池或由渲染器统一拥有共享资源。
只删除 JavaScript 变量不会释放 GPU 对象。触发条件是把变量设为 null 却未调用 delete*,后果是显存回收时机不可控;安全替代方案是显式删除后再清空引用。
在渲染循环中边用边删会造成难以复现的闪烁。触发条件是资源仍可能被后续 draw command 使用,后果是对象消失或错误状态传播;安全替代方案是先从渲染队列移除,在帧末统一执行销毁队列。WebGL 2 对严格同步有特殊需求时可使用 fenceSync,但通常资源生命周期分帧管理更简单。
排障清单
- 页面多次进入退出后,检查纹理、缓冲区和程序的创建计数是否持续增长。
- 删除 framebuffer 时同时核对其纹理、renderbuffer 附件是否由当前对象拥有。
- 清理 VAO 前确认其引用的 buffer 也会按所有权释放;删除 VAO 不会删除 buffer。
- 发生上下文丢失后,旧句柄全部失效;恢复事件中必须重新创建资源,不要复用旧对象。
速查结论:先停止使用,再解绑,再调用对应 delete*,最后清空应用引用;共享资源只能由明确的所有者或最后一个使用者释放。
读取 WebGL 错误码并定位无效参数、状态或资源操作。
检查 WebGL 错误
使用 gl.getError() 检查最近一段 WebGL 调用是否产生错误,适合定位非法枚举、参数越界、资源状态不完整和上下文丢失。排查时先清空旧错误,再执行目标调用,避免把更早的错误误判到当前代码。
基本语法
gl.getError() 每次返回一个待处理错误码,并清除该错误标记;持续调用直到返回 gl.NO_ERROR。错误不会自动指出具体代码行,因此应在可疑操作前后分段检查,而不是只在一帧末尾检查一次。
const canvas = document.createElement("canvas");
const gl = canvas.getContext("webgl");
if (!gl) {
throw new Error("当前浏览器或环境无法创建 WebGL 上下文");
}
const errorNames = {
[gl.INVALID_ENUM]: "INVALID_ENUM",
[gl.INVALID_VALUE]: "INVALID_VALUE",
[gl.INVALID_OPERATION]: "INVALID_OPERATION",
[gl.INVALID_FRAMEBUFFER_OPERATION]: "INVALID_FRAMEBUFFER_OPERATION",
[gl.OUT_OF_MEMORY]: "OUT_OF_MEMORY",
[gl.CONTEXT_LOST_WEBGL]: "CONTEXT_LOST_WEBGL"
};
function drainGlErrors(label) {
let code;
while ((code = gl.getError()) !== gl.NO_ERROR) {
const hex = `0x${code.toString(16).padStart(4, "0")}`;
console.warn(`[${label}] ${errorNames[code] ?? "UNKNOWN_ERROR"} (${hex})`);
}
}
// 先清空历史错误,再制造一个非法枚举,确保定位结果只属于本次调用。
drainGlErrors("before test");
gl.enable(0xDEADBEEF);
drainGlErrors("after invalid enable");预期输出
[after invalid enable] INVALID_ENUM (0x0500)读取方法:标签说明错误出现在哪个检查区间,错误名用于判断类型,十六进制值便于与规范或调试工具对照。
常见错误码
| 错误码 | 常见触发条件 | 优先检查 |
|---|---|---|
INVALID_ENUM |
目标、格式、模式等枚举值不受支持 | API 参数是否属于该函数允许的常量 |
INVALID_VALUE |
尺寸、偏移、数量或级别越界 | width、height、count、offset |
INVALID_OPERATION |
当前绑定或资源状态不允许该操作 | program、buffer、texture、attribute 的绑定顺序 |
INVALID_FRAMEBUFFER_OPERATION |
在不完整的帧缓冲上清除或绘制 | gl.checkFramebufferStatus() |
OUT_OF_MEMORY |
纹理、缓冲或渲染目标分配失败 | 资源尺寸、格式、重复创建与释放 |
CONTEXT_LOST_WEBGL |
GPU 重置、驱动异常或系统回收上下文 | webglcontextlost 与恢复后的资源重建 |
高频用法
在着色器编译、纹理上传、帧缓冲配置和绘制调用后分别检查,能够快速缩小错误区间。封装函数时把阶段名传入日志,例如 upload texture、bind framebuffer、draw elements,不要只打印数字错误码。
当 gl.getError() 返回 NO_ERROR 但结果仍异常时,继续检查着色器编译日志、program 链接状态、帧缓冲完整性和实际像素输出;很多“逻辑正确但画面错误”的问题不会设置 WebGL 错误码。
风险与边界
在每帧、每次 draw 后调用 gl.getError() 可能增加 CPU 与 GPU 命令同步开销,导致调试代码本身改变性能表现。生产环境应关闭高频检查,只在开发构建或异常采样中启用。
若不先清空旧错误,后续读到的错误可能来自更早的调用。安全做法是在目标代码块前排空错误,执行少量调用后立即读取,并保留阶段标签。出现 OUT_OF_MEMORY 时应减少资源尺寸或复用对象;出现上下文丢失时停止绘制,等待恢复事件后重新创建 GPU 资源。
按上下文、着色器、数据、状态、矩阵和绘制参数逐项排查无画面问题。
调试 WebGL 黑屏
当 <canvas> 已创建但画面为空时,按“上下文 → 着色器 → 顶点数据 → 渲染状态 → 矩阵/Uniform → 绘制参数”顺序排查。目标是先确认最小三角形能渲染,再把生产代码逐段接回,避免同时猜多个原因。
基线验证
先保存为 webgl-black-screen.html 并直接用浏览器打开。这个最小示例不依赖纹理、矩阵或索引缓冲;若它也失败,优先检查浏览器、GPU、上下文创建和着色器编译。
<!doctype html>
<meta charset="utf-8">
<canvas id="c" width="320" height="180"></canvas>
<script>
const canvas = document.getElementById("c");
const gl = canvas.getContext("webgl");
if (!gl) throw new Error("WebGL context unavailable");
function compile(type, source) {
const shader = gl.createShader(type);
gl.shaderSource(shader, source);
gl.compileShader(shader);
if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
throw new Error(gl.getShaderInfoLog(shader) || "shader compile failed");
}
return shader;
}
const vs = compile(gl.VERTEX_SHADER, `
attribute vec2 a_position;
void main() {
gl_Position = vec4(a_position, 0.0, 1.0);
}`);
const fs = compile(gl.FRAGMENT_SHADER, `
precision mediump float;
void main() {
gl_FragColor = vec4(1.0, 0.2, 0.1, 1.0);
}`);
const program = gl.createProgram();
gl.attachShader(program, vs);
gl.attachShader(program, fs);
gl.linkProgram(program);
if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
throw new Error(gl.getProgramInfoLog(program) || "program link failed");
}
gl.useProgram(program);
const buffer = gl.createBuffer();
gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
gl.bufferData(gl.ARRAY_BUFFER, new Float32Array([
-0.7, -0.6,
0.7, -0.6,
0.0, 0.7
]), gl.STATIC_DRAW);
const loc = gl.getAttribLocation(program, "a_position");
gl.enableVertexAttribArray(loc);
gl.vertexAttribPointer(loc, 2, gl.FLOAT, false, 0, 0);
gl.viewport(0, 0, canvas.width, canvas.height);
gl.clearColor(0.05, 0.05, 0.05, 1.0);
gl.clear(gl.COLOR_BUFFER_BIT);
gl.drawArrays(gl.TRIANGLES, 0, 3);
console.log("context:", !!gl);
console.log("programLinked:", gl.getProgramParameter(program, gl.LINK_STATUS));
console.log("glError:", gl.getError());
</script>预期结果
页面:深灰背景中央出现一个红色三角形
context: true
programLinked: true
glError: 0glError: 0 即 gl.NO_ERROR。如果控制台直接抛出编译或链接错误,先修复日志中的 GLSL 问题,不要继续查矩阵和深度测试。
排障清单
- 上下文:确认
getContext()非空、未触发webglcontextlost,且canvas.width/canvas.height大于 0。CSS 尺寸不等于绘图缓冲尺寸时,同时核对drawingBufferWidth和drawingBufferHeight。 - 着色器:检查
COMPILE_STATUS、LINK_STATUS和 info log,并确认绘制前调用了正确的useProgram()。 - 顶点数据:属性位置不能误当成固定值;核对当前
ARRAY_BUFFER、enableVertexAttribArray()、size/type/stride/offset。drawElements()还要确认索引缓冲已绑定。 - 矩阵与 Uniform:Uniform 位置不能为
null;矩阵中不要出现NaN/Infinity。顶点变换后若全部落到裁剪空间外,画面会正常清屏但没有几何体。 - 渲染状态:检查
viewport、scissor、colorMask、深度测试、面剔除和当前 framebuffer。自定义 framebuffer 必须满足FRAMEBUFFER_COMPLETE。 - 绘制参数:核对 primitive、
first/count、索引类型和 offset;count为 0、索引类型不匹配或 offset 未按类型对齐都会导致无有效输出或产生 GL 错误。

风险与边界
不要为了“先看到东西”长期关闭深度测试、面剔除、混合或改写 viewport。触发条件是把临时诊断状态直接留在生产渲染循环中;后果是遮蔽真正的状态泄漏,并造成穿插、反面可见或透明度错误。安全做法是在最小复现或单帧诊断中修改,并在结束后恢复原状态。
gl.getError() 适合在初始化阶段或可疑 API 调用后检查,但高频放进每个 draw call 会增加 CPU 开销。生产环境优先在调试构建、关键帧边界或错误采样点使用。
兼容性
WebGL 1 与 WebGL 2 都可使用上述编译、链接、getError() 与 framebuffer 检查思路。WebGL 2 若启用了 VAO,还要确认绘制时绑定的是包含正确属性状态的 VAO;切换自定义 framebuffer 后,也要重新核对目标尺寸对应的 viewport。
排查纹理翻转、颜色错误、采样黑色和尺寸限制等常见问题。
处理 WebGL 纹理显示异常
出现纹理上下颠倒、整块发黑、透明边缘异常或颜色偏差时,先把纹理上传状态、纹理单元和完整性固定下来,再检查资源本身。最常见的根因不是着色器算法,而是 pixelStorei、sampler 绑定或 WebGL 1 的 NPOT 限制。
基线验证
下面示例用 2×2 Canvas 生成四个颜色块,避免网络与 CORS 干扰,同时验证 Y 翻转、纹理单元、采样器和纹理完整性。保存为 webgl-texture-check.html 后直接打开。
<!doctype html>
<meta charset="utf-8">
<canvas id="c" width="320" height="180"></canvas>
<script>
const gl = document.getElementById("c").getContext("webgl");
if (!gl) throw new Error("WebGL context unavailable");
function shader(type, source) {
const s = gl.createShader(type);
gl.shaderSource(s, source);
gl.compileShader(s);
if (!gl.getShaderParameter(s, gl.COMPILE_STATUS)) {
throw new Error(gl.getShaderInfoLog(s) || "shader compile failed");
}
return s;
}
const program = gl.createProgram();
gl.attachShader(program, shader(gl.VERTEX_SHADER, `
attribute vec2 a_position;
attribute vec2 a_uv;
varying vec2 v_uv;
void main() {
v_uv = a_uv;
gl_Position = vec4(a_position, 0.0, 1.0);
}`));
gl.attachShader(program, shader(gl.FRAGMENT_SHADER, `
precision mediump float;
varying vec2 v_uv;
uniform sampler2D u_tex;
void main() {
gl_FragColor = texture2D(u_tex, v_uv);
}`));
gl.linkProgram(program);
if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
throw new Error(gl.getProgramInfoLog(program) || "program link failed");
}
gl.useProgram(program);
const src = document.createElement("canvas");
src.width = src.height = 2;
const ctx = src.getContext("2d");
ctx.fillStyle = "red"; ctx.fillRect(0, 0, 1, 1);
ctx.fillStyle = "lime"; ctx.fillRect(1, 0, 1, 1);
ctx.fillStyle = "blue"; ctx.fillRect(0, 1, 1, 1);
ctx.fillStyle = "white"; ctx.fillRect(1, 1, 1, 1);
const texture = gl.createTexture();
gl.activeTexture(gl.TEXTURE0);
gl.bindTexture(gl.TEXTURE_2D, texture);
// DOM 图像源通常需要翻转 Y,且此状态会持续影响后续上传。
gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, true);
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, src);
const data = new Float32Array([
-1, -1, 0, 0,
1, -1, 1, 0,
-1, 1, 0, 1,
1, 1, 1, 1
]);
const buffer = gl.createBuffer();
gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
gl.bufferData(gl.ARRAY_BUFFER, data, gl.STATIC_DRAW);
const pos = gl.getAttribLocation(program, "a_position");
const uv = gl.getAttribLocation(program, "a_uv");
gl.enableVertexAttribArray(pos);
gl.vertexAttribPointer(pos, 2, gl.FLOAT, false, 16, 0);
gl.enableVertexAttribArray(uv);
gl.vertexAttribPointer(uv, 2, gl.FLOAT, false, 16, 8);
gl.uniform1i(gl.getUniformLocation(program, "u_tex"), 0);
gl.viewport(0, 0, gl.canvas.width, gl.canvas.height);
gl.drawArrays(gl.TRIANGLE_STRIP, 0, 4);
console.log("flipY:", gl.getParameter(gl.UNPACK_FLIP_Y_WEBGL));
console.log("activeUnit0:", gl.getParameter(gl.ACTIVE_TEXTURE) === gl.TEXTURE0);
console.log("boundTexture:", gl.getParameter(gl.TEXTURE_BINDING_2D) === texture);
console.log("glError:", gl.getError());
</script>预期结果
页面:左上红、右上绿、左下蓝、右下白
flipY: true
activeUnit0: true
boundTexture: true
glError: 0若四象限方向不对,优先检查上传前的 UNPACK_FLIP_Y_WEBGL;若方向正确但业务纹理仍黑,再查纹理完整性、sampler 和资源加载。

高频问题
| 现象 | 优先检查 | 修复要点 |
|---|---|---|
| 上下颠倒 | UNPACK_FLIP_Y_WEBGL 与 UV 方向 |
在 texImage2D() 前明确设置;不要靠改模型矩阵补救纹理方向 |
| 整块发黑 | sampler、纹理单元、绑定对象、mipmap 完整性 | uniform1i() 传纹理单元编号;未生成 mipmap 时把 TEXTURE_MIN_FILTER 设为 LINEAR/NEAREST |
| WebGL 1 的 NPOT 纹理黑屏 | 宽高非 2 的幂且使用 REPEAT 或 mipmap | WRAP_S/T=CLAMP_TO_EDGE,使用非 mipmap min filter,不调用 generateMipmap() |
| 透明边缘发黑或发灰 | 预乘 Alpha 与混合公式不一致 | 核对 UNPACK_PREMULTIPLY_ALPHA_WEBGL 和 blendFunc(),两端统一预乘策略 |
| 跨域图片上传失败 | 图片响应缺少 CORS | 在设置 src 前设 crossOrigin="anonymous",服务端允许对应 Origin |
输出读取
activeUnit0: true 只表示当前激活的是 TEXTURE0;真正决定 sampler 采哪一单元的是 uniform1i(u_tex, 0)。boundTexture: true 表示该单元当前绑定了目标纹理。glError: 0 说明到检查点为止没有未读取的 WebGL 错误,但不能替代资源加载状态与视觉检查。
颜色偏暗或偏亮时,再检查 sRGB/线性空间是否一致;不要把色彩空间问题误判为纹理数据损坏。
风险与边界
UNPACK_FLIP_Y_WEBGL、UNPACK_PREMULTIPLY_ALPHA_WEBGL 都是上下文级像素上传状态,会持续影响后续纹理。触发条件是上传某张特殊纹理时修改状态,却没有在下一次上传前重新显式设置;后果是其他纹理被意外翻转或透明颜色改变。安全做法是把所需 unpack 状态写进每次纹理上传函数,而不是依赖“当前值应该没变”。
不要为了修复 NPOT 问题无条件把所有纹理缩放成 2 的幂;这会增加显存和预处理成本。WebGL 1 才有上述 NPOT 完整性限制,优先通过合法的 wrap/filter 组合解决。
兼容性
WebGL 2 已取消 WebGL 1 对 NPOT 纹理的 wrap 与 mipmap 限制,但 sampler 绑定、纹理单元和 mipmap 完整性仍需正确配置。WebGL 1 若需要 sRGB 纹理格式通常依赖 EXT_sRGB;WebGL 2 可使用核心 sRGB 内部格式。
正确配置图片跨域属性和服务器响应头,避免纹理上传失败。
处理跨域纹理
当纹理图片来自不同协议、主机或端口时,同时配置图片的 CORS 模式和图片服务器响应头;只改前端或只改服务器都可能导致 texImage2D 上传失败。
基本配置
crossOrigin 必须在设置 src 之前赋值。通常使用 anonymous,表示跨域请求不携带 Cookie 等凭据。
<!doctype html>
<canvas id="c" width="64" height="64"></canvas>
<script>
const gl = document.getElementById('c').getContext('webgl');
const image = new Image();
// 必须先声明 CORS 模式,再触发图片请求。
image.crossOrigin = 'anonymous';
image.onload = () => {
const texture = gl.createTexture();
gl.bindTexture(gl.TEXTURE_2D, texture);
// WebGL 1 对非 2 次幂纹理更严格,使用这组参数可避免额外限制。
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
gl.texImage2D(
gl.TEXTURE_2D, 0, gl.RGBA,
gl.RGBA, gl.UNSIGNED_BYTE, image
);
console.log(`texture uploaded: ${image.naturalWidth}x${image.naturalHeight}`);
};
image.onerror = () => console.error('texture load failed');
image.src = '<URL>';
</script>预期输出
texture uploaded: <WIDTH>x<HEIGHT>把 <URL> 替换为实际图片地址;尺寸会随图片变化。若输出 texture load failed,先查网络与 CORS,不要直接怀疑 WebGL 参数。
服务器响应头
匿名跨域纹理至少要让图片响应返回允许当前页面 Origin 的 Access-Control-Allow-Origin。固定单一前端域名时,Nginx 可这样配置:
location /textures/ {
add_header Access-Control-Allow-Origin https://app.example.com always;
add_header Vary Origin always;
}片段示例:把域名替换为真实前端 Origin,并在对应静态资源 location 中生效。用响应头直接验证:
curl -I <URL>预期输出
HTTP/2 200
access-control-allow-origin: https://app.example.com
vary: OriginHTTP 版本和其他响应头可能不同;关键是 Access-Control-Allow-Origin 必须与页面 Origin 匹配。
风险与边界
- 若
crossOrigin在src之后设置,请求可能已经发出,后续即使属性正确也可能继续使用错误的响应;安全做法是先设置crossOrigin,再设置src。 - 若使用
use-credentials,服务器不能返回Access-Control-Allow-Origin: *,否则浏览器会拒绝响应;应返回明确 Origin,并同时启用Access-Control-Allow-Credentials: true。 - 若 CDN 按 Origin 动态返回 CORS 头却没有正确区分缓存,可能把别的域名的响应头复用过来;应让 CDN 缓存键包含 Origin,并保留
Vary: Origin。 - 不要把关闭浏览器同源策略作为生产方案;应修正资源域名、CORS 响应头或把纹理迁移到同源/CDN 受控域名。
排障清单
- 在 Network 中确认图片请求成功且不是重定向到未配置 CORS 的地址。
- 核对页面的完整 Origin:协议、主机、端口任一不同都属于跨域。
- 核对最终图片响应的
Access-Control-Allow-Origin,不要只看 302/301 中间响应。 - CORS 已通过但纹理仍异常时,再检查图片是否加载完成、纹理尺寸、像素格式和 WebGL 错误状态。
WebGL 1 与 WebGL 2 都遵循浏览器的同源与 CORS 规则;区别主要来自浏览器和资源服务器,不来自 WebGL 版本本身。
查询纹理尺寸、顶点属性数量、纹理单元和缓冲区等硬件限制。
查询 WebGL 设备能力限制
在创建大纹理、批量顶点属性、多个采样器或离屏缓冲前,用 gl.getParameter() 读取当前浏览器与 GPU 实际暴露的上限。不要把开发机数值写死为业务配置,应按查询结果降级资源尺寸或功能。
基本语法
gl.getParameter(pname) 返回指定限制值。限制属于当前 WebGL 上下文;同一设备在 WebGL 1、WebGL 2、不同浏览器或显卡驱动下可能不同。
(() => {
const canvas = document.createElement("canvas");
const gl =
canvas.getContext("webgl2") ||
canvas.getContext("webgl") ||
canvas.getContext("experimental-webgl");
if (!gl) {
throw new Error("当前环境不支持 WebGL");
}
const limits = {
contextVersion:
typeof WebGL2RenderingContext !== "undefined" &&
gl instanceof WebGL2RenderingContext
? "WebGL 2"
: "WebGL 1",
maxTextureSize: gl.getParameter(gl.MAX_TEXTURE_SIZE),
maxCubeMapTextureSize: gl.getParameter(gl.MAX_CUBE_MAP_TEXTURE_SIZE),
maxRenderbufferSize: gl.getParameter(gl.MAX_RENDERBUFFER_SIZE),
maxVertexAttribs: gl.getParameter(gl.MAX_VERTEX_ATTRIBS),
maxFragmentTextureUnits: gl.getParameter(gl.MAX_TEXTURE_IMAGE_UNITS),
maxVertexTextureUnits: gl.getParameter(gl.MAX_VERTEX_TEXTURE_IMAGE_UNITS),
maxCombinedTextureUnits: gl.getParameter(gl.MAX_COMBINED_TEXTURE_IMAGE_UNITS)
};
const isWebGL2 =
typeof WebGL2RenderingContext !== "undefined" &&
gl instanceof WebGL2RenderingContext;
if (isWebGL2) {
// WebGL 2 才有统一缓冲区与多渲染目标相关限制。
limits.maxUniformBufferBindings = gl.getParameter(gl.MAX_UNIFORM_BUFFER_BINDINGS);
limits.maxUniformBlockSize = gl.getParameter(gl.MAX_UNIFORM_BLOCK_SIZE);
limits.maxColorAttachments = gl.getParameter(gl.MAX_COLOR_ATTACHMENTS);
limits.maxDrawBuffers = gl.getParameter(gl.MAX_DRAW_BUFFERS);
}
console.table(limits);
})();预期输出
(index) Values
contextVersion "WebGL 2"
maxTextureSize <DEVICE_VALUE>
maxCubeMapTextureSize <DEVICE_VALUE>
maxRenderbufferSize <DEVICE_VALUE>
maxVertexAttribs <DEVICE_VALUE>
maxFragmentTextureUnits <DEVICE_VALUE>
maxVertexTextureUnits <DEVICE_VALUE>
maxCombinedTextureUnits <DEVICE_VALUE>
maxUniformBufferBindings <DEVICE_VALUE>
maxUniformBlockSize <DEVICE_VALUE>
maxColorAttachments <DEVICE_VALUE>
maxDrawBuffers <DEVICE_VALUE><DEVICE_VALUE> 是当前设备返回的整数,实际值会因浏览器、GPU、驱动和上下文版本不同而变化。
高频查询项
| 常量 | 何时检查 | 读取方式 |
|---|---|---|
MAX_TEXTURE_SIZE |
上传二维纹理、图集或大画布前 | 最大宽高,单位为像素 |
MAX_CUBE_MAP_TEXTURE_SIZE |
创建立方体贴图前 | 每个面的最大宽高 |
MAX_RENDERBUFFER_SIZE |
创建深度、模板或多采样渲染缓冲前 | 最大宽高 |
MAX_VERTEX_ATTRIBS |
设计顶点布局或实例化数据前 | 可启用的顶点属性槽数量 |
MAX_*_TEXTURE_IMAGE_UNITS |
着色器需要多个采样器时 | 各阶段或合计可使用的纹理单元数量 |
MAX_UNIFORM_BLOCK_SIZE |
WebGL 2 使用 UBO 前 | 单个 uniform 块最大字节数 |
MAX_COLOR_ATTACHMENTS |
WebGL 2 使用 MRT 前 | 帧缓冲可挂载的颜色附件数 |
按限制降级
资源尺寸应先与设备上限取较小值,再创建纹理或渲染缓冲。下面片段依赖已获得的 gl 上下文。
const requestedSize = 8192;
const maxTextureSize = gl.getParameter(gl.MAX_TEXTURE_SIZE);
const safeSize = Math.min(requestedSize, maxTextureSize);
console.log({ requestedSize, maxTextureSize, safeSize });预期输出
{ requestedSize: 8192, maxTextureSize: <DEVICE_VALUE>, safeSize: <FINAL_SIZE> }当设备上限低于 8192 时,safeSize 会自动降到设备上限;否则保持 8192。
风险与边界
超过限制创建资源时,常见后果是 INVALID_VALUE、帧缓冲不完整、纹理上传失败或画面为空。安全做法是创建前查询并裁剪尺寸,创建后再用 gl.getError() 或 gl.checkFramebufferStatus() 验证。
限制值表示理论上限,不代表接近上限时仍有足够显存或稳定性能。生产环境应保留余量,并优先降低分辨率、附件数量或纹理单元占用,而不是直接顶格分配。
排障清单
- 查询结果异常为
null或代码停止时,检查上下文是否创建失败或已触发webglcontextlost。 - 纹理尺寸未超限仍失败时,继续核对格式、类型、mipmap 完整性和显存压力。
- 帧缓冲创建失败时,同时检查附件尺寸一致、格式可渲染以及
checkFramebufferStatus()返回值。 - WebGL 1 不存在的常量不要直接查询;先判断上下文版本,再访问 WebGL 2 专有限制。
速查原则:先查询、再裁剪、创建后验证,不能把某台开发机的上限当作所有用户设备的能力。
按需检测和启用浮点纹理、各向异性过滤等 WebGL 扩展能力。
检测 WebGL 扩展支持
需要浮点纹理线性过滤、浮点颜色附件或各向异性过滤时,先用 gl.getExtension() 获取扩展对象。返回对象表示当前上下文可用;返回 null 时必须关闭功能或走兼容路径。
基本语法
gl.getSupportedExtensions() 适合列出候选名称,真正启用能力仍应调用 gl.getExtension(name)。扩展名称区分大小写,部分旧环境只暴露厂商前缀名称。
(() => {
const canvas = document.createElement("canvas");
const gl = canvas.getContext("webgl2") || canvas.getContext("webgl");
if (!gl) {
throw new Error("当前环境不支持 WebGL");
}
const getFirstExtension = (...names) => {
for (const name of names) {
const extension = gl.getExtension(name);
if (extension) return { name, extension };
}
return null;
};
const anisotropy = getFirstExtension(
"EXT_texture_filter_anisotropic",
"WEBKIT_EXT_texture_filter_anisotropic",
"MOZ_EXT_texture_filter_anisotropic"
);
const isWebGL2 =
typeof WebGL2RenderingContext !== "undefined" &&
gl instanceof WebGL2RenderingContext;
const floatColorBuffer = getFirstExtension(
"EXT_color_buffer_float",
"WEBGL_color_buffer_float"
);
const capabilities = {
contextVersion: isWebGL2 ? "WebGL 2" : "WebGL 1",
floatTextureUpload:
isWebGL2 || Boolean(gl.getExtension("OES_texture_float")),
floatTextureLinearFilter: Boolean(gl.getExtension("OES_texture_float_linear")),
floatColorAttachment: Boolean(floatColorBuffer),
anisotropicFiltering: Boolean(anisotropy)
};
if (anisotropy) {
capabilities.maxAnisotropy = gl.getParameter(
anisotropy.extension.MAX_TEXTURE_MAX_ANISOTROPY_EXT
);
}
console.table(capabilities);
})();预期输出
(index) Values
contextVersion "WebGL 1" 或 "WebGL 2"
floatTextureUpload true 或 false
floatTextureLinearFilter true 或 false
floatColorAttachment true 或 false
anisotropicFiltering true 或 false
maxAnisotropy <DEVICE_VALUE>只有支持各向异性过滤时才会出现 maxAnisotropy;<DEVICE_VALUE> 为设备实际返回值。
常见扩展判断
| 能力 | WebGL 1 | WebGL 2 |
|---|---|---|
| 上传并采样 32 位浮点纹理 | 需要 OES_texture_float |
核心能力 |
| 对 32 位浮点纹理使用线性过滤 | 需要 OES_texture_float_linear |
仍应检测该扩展 |
| 将浮点纹理作为颜色附件渲染 | 常见实现需相关颜色缓冲扩展 | 检测 EXT_color_buffer_float |
| 各向异性过滤 | 检测 EXT_texture_filter_anisotropic 及旧前缀 |
同样需要扩展 |
不要把“可以创建浮点纹理”与“可以线性过滤”或“可以作为帧缓冲颜色附件”混为一项;它们是不同能力。
启用各向异性过滤
下面示例创建一张有效的 1×1 纹理,并在扩展可用时把过滤等级限制在设备上限内。
(() => {
const gl = document.createElement("canvas").getContext("webgl2");
if (!gl) throw new Error("此示例需要 WebGL 2");
const ext = gl.getExtension("EXT_texture_filter_anisotropic");
const texture = gl.createTexture();
gl.bindTexture(gl.TEXTURE_2D, texture);
gl.texImage2D(
gl.TEXTURE_2D,
0,
gl.RGBA8,
1,
1,
0,
gl.RGBA,
gl.UNSIGNED_BYTE,
new Uint8Array([255, 255, 255, 255])
);
if (ext) {
const max = gl.getParameter(ext.MAX_TEXTURE_MAX_ANISOTROPY_EXT);
const applied = Math.min(8, max);
gl.texParameterf(gl.TEXTURE_2D, ext.TEXTURE_MAX_ANISOTROPY_EXT, applied);
console.log(`anisotropy=${applied}`);
} else {
console.log("anisotropy=unsupported; fallback=bilinear");
}
})();预期输出
anisotropy=<APPLIED_LEVEL>或
anisotropy=unsupported; fallback=bilinear<APPLIED_LEVEL> 不超过请求值 8,也不会超过设备返回的最大等级。
风险与边界
未判空就读取扩展对象常量会触发 JavaScript 异常,导致渲染初始化中断。安全替代是先检查返回值,并把扩展功能封装成可选分支。
扩展支持不等于所有格式组合都可用。浮点纹理作为帧缓冲附件后,仍需调用 gl.checkFramebufferStatus();纹理过滤、内部格式和类型也必须满足对应版本规则。
上下文丢失并恢复后,旧扩展对象和纹理对象不可继续复用。应在 webglcontextrestored 后重新获取扩展并重建 GPU 资源。
排障清单
getSupportedExtensions()中有名称但getExtension()返回null时,以后者为准,并检查上下文是否已丢失。- 浮点纹理能采样但线性过滤报错时,检查
OES_texture_float_linear,缺失时改用NEAREST。 - 浮点帧缓冲不完整时,检查
EXT_color_buffer_float、内部格式、附件尺寸及checkFramebufferStatus()。 - 各向异性设置无效时,确认使用的是扩展对象提供的常量,并将请求值限制到最大值。
速查原则:扩展逐项检测、对象判空、失败时明确降级,不能仅凭浏览器型号或 WebGL 版本推断支持。
监听上下文丢失与恢复事件,并重新创建全部 GPU 资源。
处理上下文丢失
当浏览器、GPU 驱动或系统回收 WebGL 上下文时,旧的纹理、Buffer、Program、Framebuffer 等 GPU 对象都应视为失效;监听丢失与恢复事件,并在恢复后从 CPU 侧数据重新创建资源。
恢复流程
webglcontextlost 发生时停止渲染并调用 preventDefault() 表示应用能够处理恢复;真正的资源重建只能放在 webglcontextrestored 之后。

可运行示例
下面的页面使用 WEBGL_lose_context 主动模拟一次丢失和恢复。该扩展只用于测试恢复代码,不应作为生产逻辑依赖。
<!doctype html>
<canvas id="c" width="160" height="90"></canvas>
<script>
const canvas = document.getElementById('c');
let gl = canvas.getContext('webgl');
let buffer;
let raf;
function createGpuResources() {
// 恢复后必须创建新对象,不能继续引用丢失前的 GPU 句柄。
buffer = gl.createBuffer();
gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
gl.bufferData(gl.ARRAY_BUFFER, new Float32Array([0, 0]), gl.STATIC_DRAW);
}
function render() {
if (gl.isContextLost()) return;
gl.clearColor(0.1, 0.2, 0.3, 1);
gl.clear(gl.COLOR_BUFFER_BIT);
raf = requestAnimationFrame(render);
}
canvas.addEventListener('webglcontextlost', (event) => {
event.preventDefault();
cancelAnimationFrame(raf);
console.log('context lost');
});
canvas.addEventListener('webglcontextrestored', () => {
gl = canvas.getContext('webgl');
createGpuResources();
console.log('context restored');
render();
});
createGpuResources();
render();
const lose = gl.getExtension('WEBGL_lose_context');
if (lose) {
setTimeout(() => lose.loseContext(), 500);
setTimeout(() => lose.restoreContext(), 1500);
} else {
console.log('WEBGL_lose_context unavailable');
}
</script>预期输出
context lost
context restored不支持测试扩展的实现会输出 WEBGL_lose_context unavailable;这不代表真实环境不会发生上下文丢失。
风险与边界
- 若丢失事件中不停止渲染循环,应用可能持续调用无效上下文并产生大量无意义错误;安全做法是暂停 RAF、定时器和依赖 GPU 的任务。
- 若恢复后继续复用旧的
WebGLTexture、WebGLBuffer、WebGLProgram等对象,结果不可依赖;应从保留在 CPU 内存、缓存或可重新获取的数据重建全部 GPU 资源。 - 不要在
webglcontextlost回调里立即重建资源,此时上下文仍处于丢失状态;应等待webglcontextrestored。 - 大纹理和模型只保存在 GPU 时,恢复后可能无法重建;生产代码应保留可恢复的源数据,或设计重新下载/重新解码路径。
排障清单
- 监听器应绑定在实际创建 WebGL 上下文的
canvas上。 - 丢失时用
gl.isContextLost()区分上下文问题与普通INVALID_OPERATION。 - 恢复后按依赖顺序重建 Shader/Program、Buffer、Texture、Framebuffer/Renderbuffer,以及 WebGL 2 中的 VAO、Sampler 等对象。
- 重建完成后再恢复渲染循环;若仍黑屏,优先检查 Program 是否重新链接、纹理是否重新上传、Framebuffer 是否重新绑定完整附件。
webglcontextlost 与 webglcontextrestored 适用于 WebGL 1 和 WebGL 2。WEBGL_lose_context 主要用于测试兼容性,业务代码不能假设它一定存在。
通过计时查询和浏览器图形工具定位 GPU 渲染瓶颈。
分析 GPU 性能
当帧率下降但无法判断是 JavaScript、浏览器合成还是 GPU 渲染过慢时,用 GPU 计时查询测量指定 WebGL 命令段,再结合浏览器 Performance 轨迹和 WebGL 帧捕获定位具体渲染阶段。
命令定位
WebGL 2 优先探测 EXT_disjoint_timer_query_webgl2。它使用原生 WebGLQuery:gl.beginQuery()/gl.endQuery() 包住待测绘制,稍后用 gl.getQueryParameter() 异步读取结果,并检查 ext.GPU_DISJOINT_EXT。
浏览器侧先用 DevTools Performance 观察 Frames、Main 与 GPU 活动:Main 线程长任务明显时先查 CPU;GPU 活动持续偏长时,再把 timer query 放到阴影、主场景、后处理等渲染阶段。需要进一步看具体 draw call、Shader、纹理和状态切换时,可用 Spector.js 一类 WebGL 帧捕获工具抓取异常帧。
高频用法
下面代码可直接粘贴到支持 WebGL 2 的页面控制台。它创建一个最小三角形,把一次 drawArrays 放进 GPU 查询,并跨浏览器事件循环等待结果;不要在同一个同步循环里反复读取查询状态。
(async () => {
const canvas = document.createElement("canvas");
canvas.width = 64;
canvas.height = 64;
document.body.appendChild(canvas);
const gl = canvas.getContext("webgl2");
if (!gl) throw new Error("WebGL2 unavailable");
const ext = gl.getExtension("EXT_disjoint_timer_query_webgl2");
if (!ext) {
console.warn("EXT_disjoint_timer_query_webgl2 unavailable");
canvas.remove();
return;
}
const compile = (type, source) => {
const shader = gl.createShader(type);
gl.shaderSource(shader, source);
gl.compileShader(shader);
if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
throw new Error(gl.getShaderInfoLog(shader) || "shader compile failed");
}
return shader;
};
const vs = compile(gl.VERTEX_SHADER, `#version 300 es
const vec2 P[3] = vec2[3](
vec2(-1.0, -1.0), vec2(3.0, -1.0), vec2(-1.0, 3.0)
);
void main() { gl_Position = vec4(P[gl_VertexID], 0.0, 1.0); }
`);
const fs = compile(gl.FRAGMENT_SHADER, `#version 300 es
precision highp float;
out vec4 color;
void main() { color = vec4(0.2, 0.6, 1.0, 1.0); }
`);
const program = gl.createProgram();
gl.attachShader(program, vs);
gl.attachShader(program, fs);
gl.linkProgram(program);
if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
throw new Error(gl.getProgramInfoLog(program) || "program link failed");
}
const vao = gl.createVertexArray();
gl.bindVertexArray(vao);
gl.useProgram(program);
gl.viewport(0, 0, canvas.width, canvas.height);
const query = gl.createQuery();
gl.beginQuery(ext.TIME_ELAPSED_EXT, query);
gl.drawArrays(gl.TRIANGLES, 0, 3);
gl.endQuery(ext.TIME_ELAPSED_EXT);
// 查询结果只能异步变为可用;每轮都把控制权还给浏览器。
while (!gl.getQueryParameter(query, gl.QUERY_RESULT_AVAILABLE)) {
await new Promise((resolve) => requestAnimationFrame(resolve));
}
if (gl.getParameter(ext.GPU_DISJOINT_EXT)) {
console.warn("GPU timing invalid: disjoint");
} else {
const ns = gl.getQueryParameter(query, gl.QUERY_RESULT);
console.log(`GPU time: ${(ns / 1e6).toFixed(3)} ms`);
}
gl.deleteQuery(query);
gl.deleteVertexArray(vao);
gl.deleteProgram(program);
gl.deleteShader(vs);
gl.deleteShader(fs);
canvas.remove();
})();支持该扩展且本次计时有效时,预期输出:
GPU time: <GPU_MS> ms<GPU_MS> 是本次被包围 GPU 命令的执行时间,实际值随 GPU、驱动和系统负载变化;它不是整帧 CPU 时间。若输出 GPU timing invalid: disjoint,本次结果必须丢弃。
定位时建议按“整帧 → 渲染阶段 → 单帧命令”逐层缩小范围,而不是给每个 draw call 都长期挂查询。

输出字段说明
| 字段 | 含义 | 读取方式 |
|---|---|---|
TIME_ELAPSED_EXT |
计时查询目标,覆盖 beginQuery 到 endQuery 之间的 GPU 命令 |
作为查询 target |
QUERY_RESULT_AVAILABLE |
查询结果是否已可读取 | gl.getQueryParameter(query, gl.QUERY_RESULT_AVAILABLE) |
QUERY_RESULT |
GPU 执行耗时,单位为纳秒 | 除以 1e6 转为毫秒 |
GPU_DISJOINT_EXT |
GPU 时钟或执行状态是否发生不连续 | 为 true 时丢弃该次计时 |
风险与边界
timer query 只覆盖被包围的 GPU 命令,不包含 JavaScript、资源准备、浏览器调度、合成和呈现。若 GPU 查询很低但整帧仍慢,应回到 Performance 轨迹检查 Main 线程、GC、布局、合成或其他帧阶段。
不要在生产环境长期为每个 draw call 创建新 query。高频创建和大量查询会增加调试开销与对象管理压力;优先按渲染 pass 采样,并及时 deleteQuery(),确认瓶颈后再缩小范围。
排障清单
- 扩展返回
null:当前浏览器、GPU 或驱动未暴露该能力;改用 Performance/帧捕获工具做相对定位,不要把 CPU 提交时间当成 GPU 时间。 - 查询一直不可用:确认已经调用
endQuery,且轮询之间确实返回了浏览器事件循环;同时检查 WebGL context 是否丢失。 - 首帧异常偏高:Shader 编译、纹理上传或缓存预热会污染数据;先预热若干帧,再连续采样并比较中位数或稳定区间。
- GPU 时间高但 draw call 不多:重点检查片元 Shader、过绘制、分辨率、全屏后处理和高成本纹理采样。
- GPU 时间低但 FPS 仍差:优先查 Main 线程长任务、GC、布局/样式、资源解码和浏览器合成。
兼容性
WebGL 2 使用 EXT_disjoint_timer_query_webgl2;WebGL 1 使用 EXT_disjoint_timer_query,对应方法名为 createQueryEXT()、beginQueryEXT()、getQueryObjectEXT() 等。两种环境都应先 getExtension() 做能力探测,不能假设所有浏览器、显卡和驱动组合都支持。
控制资源生命周期和缓存规模,防止纹理与缓冲区持续占用显存。
避免 GPU 内存泄漏
当页面频繁切换场景、重建模型或更新纹理时,必须让每个 WebGL 资源都有明确的创建者和释放点。目标是资源数量在稳定负载下保持平台期,而不是随着操作次数持续增长。
资源生命周期
WebGL 对象不会因为 JavaScript 变量失去引用就立即释放 GPU 资源。缓冲区、纹理、程序、着色器、帧缓冲、渲染缓冲、查询对象、采样器和顶点数组对象都应调用对应的 delete* 方法。

删除对象后不要继续放回缓存。驱动可能等在途绘制完成后才真正回收显存,因此短时间内观察到延迟下降属于正常现象。
可复制的资源跟踪器
下面示例可直接粘贴到浏览器控制台运行。它集中登记资源,并在场景销毁时统一释放,适合单页面应用的模型预览、地图图层和可视化面板。
const canvas = document.createElement("canvas");
const gl = canvas.getContext("webgl2");
if (!gl) throw new Error("当前浏览器不支持 WebGL2");
class GLResourceTracker {
constructor(gl) {
this.gl = gl;
this.buffers = new Set();
this.textures = new Set();
this.programs = new Set();
this.framebuffers = new Set();
this.renderbuffers = new Set();
this.vertexArrays = new Set();
}
track(kind, resource) {
if (!resource) throw new Error(`创建 ${kind} 失败`);
this[kind].add(resource);
return resource;
}
dispose() {
const gl = this.gl;
for (const x of this.vertexArrays) gl.deleteVertexArray(x);
for (const x of this.framebuffers) gl.deleteFramebuffer(x);
for (const x of this.renderbuffers) gl.deleteRenderbuffer(x);
for (const x of this.textures) gl.deleteTexture(x);
for (const x of this.buffers) gl.deleteBuffer(x);
for (const x of this.programs) gl.deleteProgram(x);
for (const set of [
this.vertexArrays,
this.framebuffers,
this.renderbuffers,
this.textures,
this.buffers,
this.programs
]) {
set.clear();
}
}
counts() {
return {
buffers: this.buffers.size,
textures: this.textures.size,
programs: this.programs.size
};
}
}
const tracker = new GLResourceTracker(gl);
tracker.track("buffers", gl.createBuffer());
tracker.track("textures", gl.createTexture());
tracker.track("programs", gl.createProgram());
console.log("释放前", tracker.counts());
tracker.dispose();
console.log("释放后", tracker.counts());预期输出:
释放前 {buffers: 1, textures: 1, programs: 1}
释放后 {buffers: 0, textures: 0, programs: 0}输出只证明应用登记的资源已释放,不能直接代表驱动显存已立即归零。实际对象显示顺序可能因浏览器控制台而不同。
缓存规模与淘汰
缓存必须同时设置数量或字节上限,并在淘汰时调用对应 delete*。纹理预算可按 宽 × 高 × 每像素字节数 × mipmap 系数 粗估;RGBA8 且生成完整 mipmap 时,系数约为 4/3。
不要用 URL 作为永久缓存键而不淘汰,也不要在每帧创建临时纹理、缓冲区或程序。动态几何优先复用已有缓冲区并调用 bufferSubData,尺寸变化明显时再重新分配。
风险与边界
调用 deleteTexture、deleteBuffer 等方法时,如果对象仍被后续绘制逻辑引用,可能出现黑屏、采样异常或 INVALID_OPERATION。安全做法是先停止提交相关绘制,再从业务缓存移除,最后统一释放。
WEBGL_lose_context 会让整个上下文失效,可能导致画面中断和全部资源重建。它只适合测试上下文恢复或彻底卸载独立画布,不应作为日常清理单个资源的替代方案。
浏览器没有标准 API 精确返回当前 WebGL 显存占用。应结合资源计数、纹理尺寸预算、性能面板和重复操作后的稳定性判断,避免只看 JavaScript 堆内存。
排障清单
- 连续进入并退出同一场景 20 次,确认跟踪器计数回到基线。
- 检查纹理替换、模型热更新、窗口缩放和异常中断路径是否都执行释放。
- 确认事件监听器、闭包和缓存没有继续持有已废弃的资源包装对象。
- 用
gl.isTexture、gl.isBuffer等方法检查可疑对象;删除后的对象不应再次进入渲染队列。
速查原则:创建时登记,复用时设上限,淘汰和场景销毁时调用对应 delete*。
限制动态着色器生成并提前编译程序,降低运行时编译和链接停顿。
防止着色器卡顿
着色器卡顿通常发生在首次使用某个程序变体时:浏览器和驱动需要编译着色器、链接程序并完成底层管线准备。应把这段工作移到加载阶段,限制变体数量,并在支持时异步轮询完成状态。
预编译流程
不要在动画帧内拼接着色器源码或调用 compileShader、linkProgram。根据材质特性生成稳定的变体键,在场景展示前创建并缓存程序;首次绘制只做缓存查找和 useProgram。

WebGL 不提供可移植的程序二进制缓存接口,因此跨页面会话是否复用驱动缓存不可依赖。应用层应缓存当前上下文中的 WebGLProgram。
可复制的异步预热示例
下面代码可直接粘贴到支持 WebGL2 的浏览器控制台。它预热两个片元颜色变体,并使用 KHR_parallel_shader_compile 避免过早查询链接状态造成主线程阻塞。
const canvas = document.createElement("canvas");
const gl = canvas.getContext("webgl2");
if (!gl) throw new Error("当前浏览器不支持 WebGL2");
const ext = gl.getExtension("KHR_parallel_shader_compile");
const vertexSource = `#version 300 es
in vec2 a_position;
void main() {
gl_Position = vec4(a_position, 0.0, 1.0);
}`;
function fragmentSource(rgb) {
return `#version 300 es
precision highp float;
out vec4 outColor;
void main() {
outColor = vec4(${rgb}, 1.0);
}`;
}
function compile(type, source) {
const shader = gl.createShader(type);
gl.shaderSource(shader, source);
gl.compileShader(shader);
return shader;
}
function createProgram(fragment) {
const vs = compile(gl.VERTEX_SHADER, vertexSource);
const fs = compile(gl.FRAGMENT_SHADER, fragment);
const program = gl.createProgram();
gl.attachShader(program, vs);
gl.attachShader(program, fs);
gl.linkProgram(program);
// 链接后即可标记着色器删除;程序仍保留已附加的编译结果。
gl.deleteShader(vs);
gl.deleteShader(fs);
return program;
}
function waitForProgram(program) {
return new Promise((resolve, reject) => {
function poll() {
if (ext && !gl.getProgramParameter(program, ext.COMPLETION_STATUS_KHR)) {
requestAnimationFrame(poll);
return;
}
if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
const log = gl.getProgramInfoLog(program) || "未知链接错误";
gl.deleteProgram(program);
reject(new Error(log));
return;
}
resolve(program);
}
poll();
});
}
const variants = new Map([
["red", fragmentSource("1.0, 0.0, 0.0")],
["green", fragmentSource("0.0, 1.0, 0.0")]
]);
Promise.all(
[...variants].map(async ([key, source]) => {
const program = await waitForProgram(createProgram(source));
return [key, program];
})
).then((pairs) => {
const programCache = new Map(pairs);
console.log("预热完成", [...programCache.keys()]);
});预期输出:
预热完成 ["red", "green"]当扩展不可用时,示例仍能工作,但最终查询 LINK_STATUS 可能产生一次同步等待。数组显示格式可能因浏览器而略有不同。
变体控制
把会改变源码的开关限制在必要集合,例如阴影、蒙皮、实例化和透明模式。变体键必须规范化,避免同一组合因参数顺序不同被重复编译。
运行时连续值优先使用 uniform,而不是把颜色、粗糙度、时间或灯光强度写进源码。只有会改变代码路径、顶点布局或输出结构的特性才适合生成独立程序。
错误检查与验证
开发环境应记录 getShaderInfoLog 和 getProgramInfoLog,但不要在每帧重复查询编译或链接状态。预热结束后统计程序缓存数量,并用性能面板确认首次进入场景不再出现明显长任务。
对于多个复杂程序,可分批预热,每帧提交少量创建任务,让加载动画保持响应。真正进入交互前,再等待必需程序全部完成。
风险与边界
一次性预编译数百个变体会把卡顿从首帧搬到加载页,并增加 GPU 与驱动内存占用。安全做法是按即将使用的场景分组预热,设置缓存上限,并删除长期不用的程序。
动态拼接未经约束的宏或用户输入,可能造成变体爆炸、编译失败和长时间主线程停顿。应使用白名单功能位生成源码,并对变体总数设硬限制。
即使 LINK_STATUS 成功,部分驱动仍可能在第一次真实绘制时完成额外管线准备。关键路径可在不可见的小尺寸帧缓冲中执行一次代表性绘制进行预热,但必须复用正式顶点布局和渲染状态。
排障清单
- 搜索渲染循环内是否调用
shaderSource、compileShader或linkProgram。 - 记录变体键和缓存命中率,确认同一组合没有重复创建。
- 检查首次卡顿是否来自程序编译,还是纹理上传、缓冲分配或同步读回。
- 在支持的浏览器中确认已启用
KHR_parallel_shader_compile,并只在完成后查询链接结果。
速查原则:源码变体要少,程序要缓存,加载阶段预热,支持扩展时异步轮询完成状态。
识别 WebGL 2 专用语法和功能,并为旧环境设计兼容或降级方案。
兼容 WebGL 1
需要同时覆盖旧浏览器、嵌入式 WebView 或低端设备时,先尝试创建 WebGL 2 上下文,失败后回退到 WebGL 1,并为着色器、索引类型和扩展能力准备替代实现。不要只根据浏览器版本判断,最终以实际上下文和扩展检测结果为准。
语法与功能替换
| WebGL 2 用法 | WebGL 1 兼容方案 |
|---|---|
#version 300 es、in/out、texture() |
移除版本行,改用 attribute/varying、gl_FragColor、texture2D() |
createVertexArray() |
检测 OES_vertex_array_object;没有扩展时每次绘制重新绑定属性 |
drawArraysInstanced()、vertexAttribDivisor() |
使用 ANGLE_instanced_arrays |
drawBuffers() |
使用 WEBGL_draw_buffers |
UNSIGNED_INT 索引 |
检测 OES_element_index_uint,否则拆分网格或改用 UNSIGNED_SHORT |
| 3D 纹理、Uniform Buffer | WebGL 1 无直接等价能力,应改成 2D 图集、普通 uniform 或关闭该效果 |
可运行降级示例
将以下内容保存为 webgl-fallback.html 后直接用浏览器打开。代码会优先使用 WebGL 2;不支持时自动切换 WebGL 1,并选择对应 GLSL 语法绘制同一个三角形。
<!doctype html>
<meta charset="utf-8">
<title>WebGL fallback</title>
<canvas id="canvas" width="320" height="180"></canvas>
<script>
const canvas = document.querySelector("#canvas");
const gl = canvas.getContext("webgl2") || canvas.getContext("webgl");
if (!gl) {
throw new Error("当前环境不支持 WebGL");
}
const isWebGL2 =
typeof WebGL2RenderingContext !== "undefined" &&
gl instanceof WebGL2RenderingContext;
// WebGL 2 与 WebGL 1 的关键差异集中在着色器接口语法。
const vertexSource = isWebGL2
? `#version 300 es
in vec2 a_position;
void main() {
gl_Position = vec4(a_position, 0.0, 1.0);
}`
: `attribute vec2 a_position;
void main() {
gl_Position = vec4(a_position, 0.0, 1.0);
}`;
const fragmentSource = isWebGL2
? `#version 300 es
precision mediump float;
out vec4 outColor;
void main() {
outColor = vec4(0.1, 0.7, 0.4, 1.0);
}`
: `precision mediump float;
void main() {
gl_FragColor = vec4(0.1, 0.7, 0.4, 1.0);
}`;
function compile(type, source) {
const shader = gl.createShader(type);
gl.shaderSource(shader, source);
gl.compileShader(shader);
if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
throw new Error(gl.getShaderInfoLog(shader) || "shader compile failed");
}
return shader;
}
const program = gl.createProgram();
gl.attachShader(program, compile(gl.VERTEX_SHADER, vertexSource));
gl.attachShader(program, compile(gl.FRAGMENT_SHADER, fragmentSource));
gl.linkProgram(program);
if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
throw new Error(gl.getProgramInfoLog(program) || "program link failed");
}
const buffer = gl.createBuffer();
gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
gl.bufferData(
gl.ARRAY_BUFFER,
new Float32Array([-0.7, -0.6, 0.7, -0.6, 0.0, 0.7]),
gl.STATIC_DRAW
);
gl.useProgram(program);
const location = gl.getAttribLocation(program, "a_position");
gl.enableVertexAttribArray(location);
gl.vertexAttribPointer(location, 2, gl.FLOAT, false, 0, 0);
gl.viewport(0, 0, canvas.width, canvas.height);
gl.clearColor(0.05, 0.05, 0.08, 1);
gl.clear(gl.COLOR_BUFFER_BIT);
gl.drawArrays(gl.TRIANGLES, 0, 3);
console.log(`context=${isWebGL2 ? "WebGL2" : "WebGL1"}`);
</script>预期结果
页面显示绿色三角形。
控制台输出以下其中一项:
context=WebGL2
context=WebGL1能力检测
创建上下文后立即缓存扩展和限制值,后续渲染只读取能力表,不要在热路径反复调用 getExtension()。
function detectCapabilities(gl) {
const isWebGL2 =
typeof WebGL2RenderingContext !== "undefined" &&
gl instanceof WebGL2RenderingContext;
return {
isWebGL2,
vao: isWebGL2 ? true : Boolean(gl.getExtension("OES_vertex_array_object")),
instancing: isWebGL2 ? true : Boolean(gl.getExtension("ANGLE_instanced_arrays")),
uintIndices: isWebGL2 ? true : Boolean(gl.getExtension("OES_element_index_uint")),
maxTextureSize: gl.getParameter(gl.MAX_TEXTURE_SIZE)
};
}该片段依赖已创建的 gl 上下文。验证时打印返回对象,并根据 false 项关闭对应效果或切换替代路径。
风险与边界
WebGL 1 的非二次幂纹理不能使用 mipmap 和 REPEAT;触发条件是纹理宽高不是 2 的幂,错误配置可能导致纹理不完整并显示黑色。安全方案是改用 CLAMP_TO_EDGE 与非 mipmap 过滤,或在上传前缩放为二次幂尺寸。
不要把“扩展存在”视为性能足够。旧 GPU 即使支持实例化或多渲染目标,也可能在高实例数、大纹理和多附件下明显掉帧;应同时设置质量档位、资源预算和运行时降级开关。
排障清单
- WebGL 1 编译失败时,先检查是否残留
#version 300 es、in/out、layout、texture()或自定义片元输出。 - 索引绘制报
INVALID_ENUM时,确认UNSIGNED_INT是否有OES_element_index_uint。 - 纹理变黑时,检查非二次幂纹理的环绕方式、缩小过滤器和 mipmap。
- 扩展缺失时关闭单项功能,不要让整个渲染器初始化失败。
速查原则:先检测能力,再选择实现;无法可靠替代的 WebGL 2 功能应明确关闭,而不是静默产生错误画面。
校验模型、纹理和着色器输入规模,降低资源耗尽和页面失去响应的风险。
限制不可信渲染输入
加载用户上传的模型、纹理或着色器参数前,必须在解析、解码和 GPU 分配之前执行硬限制。目标是让异常输入尽早失败,避免超大缓冲区、解压后巨型纹理、着色器编译卡顿或持续丢失 WebGL 上下文。

建议限制
限制值应同时参考设备能力和业务预算,最终取较小值。例如纹理边长使用 min(MAX_TEXTURE_SIZE, 4096),即使设备支持 16384,也不代表单个页面应该允许上传同等大小的纹理。
| 输入 | 起始限制 | 超限处理 |
|---|---|---|
| 单模型顶点数 | 1,000,000 | 拒绝或要求服务端简化 |
| 单模型索引数 | 3,000,000 | 拒绝或拆分模型 |
| 单缓冲区字节数 | 64 MiB | 拒绝,禁止先分配后检查 |
| 单纹理解码后字节数 | 64 MiB | 降采样或拒绝 |
| 单纹理边长 | min(MAX_TEXTURE_SIZE, 4096) |
缩放后再上传 |
| 自定义着色器源码 | 64 KiB、2000 行 | 拒绝;生产优先固定模板 |
| 单请求 GPU 资源预算 | 128 MiB | 分批加载或拒绝 |
这些数值是保守起点,不是通用标准。移动端、同屏多模型或多标签页场景应进一步收紧。
可运行校验示例
将以下内容保存为 webgl-input-guard.html 并打开。示例只校验元数据,不创建大对象,避免“为了检查大小先耗尽内存”。
<!doctype html>
<meta charset="utf-8">
<title>WebGL input guard</title>
<script>
const canvas = document.createElement("canvas");
const gl = canvas.getContext("webgl2") || canvas.getContext("webgl");
if (!gl) {
throw new Error("当前环境不支持 WebGL");
}
const MiB = 1024 * 1024;
const LIMITS = {
maxVertices: 1_000_000,
maxIndices: 3_000_000,
maxBufferBytes: 64 * MiB,
maxTextureSide: Math.min(gl.getParameter(gl.MAX_TEXTURE_SIZE), 4096),
maxTextureBytes: 64 * MiB,
maxShaderChars: 64 * 1024,
maxShaderLines: 2000
};
function requireInteger(name, value, min, max) {
if (!Number.isSafeInteger(value) || value < min || value > max) {
throw new Error(`${name} 超限: ${value}`);
}
}
function checkedProduct(name, values, max) {
const result = values.reduce((total, value) => total * value, 1);
if (!Number.isSafeInteger(result) || result > max) {
throw new Error(`${name} 超限: ${result}`);
}
return result;
}
function validateModel(meta) {
requireInteger("vertexCount", meta.vertexCount, 1, LIMITS.maxVertices);
requireInteger("indexCount", meta.indexCount, 0, LIMITS.maxIndices);
requireInteger("componentsPerVertex", meta.componentsPerVertex, 1, 32);
requireInteger("bytesPerComponent", meta.bytesPerComponent, 1, 8);
// 先用元数据计算所需字节,确认预算后才允许创建 TypedArray。
checkedProduct(
"vertexBufferBytes",
[meta.vertexCount, meta.componentsPerVertex, meta.bytesPerComponent],
LIMITS.maxBufferBytes
);
}
function validateTexture(meta) {
requireInteger("textureWidth", meta.width, 1, LIMITS.maxTextureSide);
requireInteger("textureHeight", meta.height, 1, LIMITS.maxTextureSide);
requireInteger("textureChannels", meta.channels, 1, 4);
// 必须按解码后的像素计算,压缩文件大小不能代表真实内存占用。
checkedProduct(
"decodedTextureBytes",
[meta.width, meta.height, meta.channels],
LIMITS.maxTextureBytes
);
}
function validateShaderSource(source) {
if (typeof source !== "string") {
throw new Error("shaderSource 必须是字符串");
}
const sourceBytes = new TextEncoder().encode(source).byteLength;
if (sourceBytes > LIMITS.maxShaderChars) {
throw new Error(`shaderSource 超限: ${sourceBytes}`);
}
if (source.split("\n").length > LIMITS.maxShaderLines) {
throw new Error("shaderSource 行数超限");
}
}
function check(label, action) {
try {
action();
console.log(`${label}: accepted`);
} catch (error) {
console.log(`${label}: blocked - ${error.message}`);
}
}
console.log(`hardwareMaxTextureSize=${gl.getParameter(gl.MAX_TEXTURE_SIZE)}`);
check("safe-model", () => validateModel({
vertexCount: 120_000,
indexCount: 300_000,
componentsPerVertex: 8,
bytesPerComponent: 4
}));
check("huge-texture", () => validateTexture({
width: 8192,
height: 8192,
channels: 4
}));
check("huge-shader", () => {
validateShaderSource("x".repeat(70 * 1024));
});
</script>预期输出
hardwareMaxTextureSize=<N>
safe-model: accepted
huge-texture: blocked - textureWidth 超限: 8192
huge-shader: blocked - shaderSource 超限: 71680<N> 是当前 GPU 报告的最大纹理边长,实际值可能不同。若设备上限小于 4096,纹理失败信息中的允许上限也会相应降低。
校验顺序
先校验文件数量、声明尺寸和外部引用数量,再解析容器结构;解析后校验顶点、索引、材质和节点计数;图片完成解码后再次按真实宽高计算像素预算;最后汇总本次请求预计占用的 CPU 与 GPU 字节数,通过后才调用 bufferData()、texImage2D() 等分配接口。
模型格式允许外部 URI 时,应限制协议、域名、重定向次数、总下载字节和并发数。只检查主文件大小会漏掉外部缓冲区、纹理和压缩后膨胀的数据。
风险与安全替代
仅限制着色器源码长度不能构成沙箱。触发条件是允许用户提交任意 GLSL;后果可能是编译耗时过长、驱动异常或页面失去响应。最安全的替代方案是只开放可信着色器模板,让用户提交受限的材质参数、宏开关或预定义 shaderId。
只检查图片压缩包大小也不安全。小文件可能在解码后占用数十或数百 MiB;应在解码前读取尺寸元数据,在解码后再次验证真实尺寸,并优先使用 Worker 或 createImageBitmap() 减少主线程阻塞。
排障清单
- 页面在上传后立即卡死:检查是否在限制前创建了
ArrayBuffer、ImageBitmap或 TypedArray。 - GPU 内存持续增长:确认场景切换时调用
deleteBuffer()、deleteTexture()、deleteProgram(),并清理缓存引用。 - 频繁触发
webglcontextlost:降低单请求预算、纹理分辨率和并发上传数,恢复前暂停绘制。 - 校验通过仍掉帧:增加每帧绘制调用、实例数、骨骼数和材质数限制,资源大小不是唯一成本。
速查原则:任何不可信数据都应在“解析前、解码后、GPU 分配前”各检查一次,且总预算必须覆盖当前页面已经占用的资源。