HTML WebGL 3D图形渲染入门速查教程

`getContext('webgl')` 返回 null 这事儿，是许多人的第一道坎。别急着怀疑代码写错了，多半是环境没伺候好——先把这个问题搞定，再谈渲染的事。

canvas 元素为什么拿不到 WebGL 上下文

浏览器返回 null，不代表它不支持 WebGL。大多数时候，是 canvas 自身状态出了问题： - 如果 canvas 被设置为 display: none、visibility: hidden，或者父容器折叠了，getContext('webgl') 就会悄悄失败，连个报错都不给。 - 宽高为 0 也是一个常见雷区。CSS 设置了尺寸？没用。HTML 的 width 和 height 属性不写，一样触发失败。 - 某些 Chrome 或 Edge 浏览器，在虚拟机或老旧集成显卡上，会默认禁用 WebGL。可以临时加上启动参数 --enable-webgl --ignore-gpu-blacklist 来调试。 - 生产环境就别指望 experimental-webgl 了，它早就被废弃。现代浏览器只认 webgl。

着色器编译失败，却看不到报错

GLSL 语法错误不会像 JavaScript 那样抛出异常。gl.compileShader() 总是“成功”返回，但里面的问题得你自己去查。 - 编译完成后，立刻调用 gl.getShaderParameter(shader, gl.COMPILE_STATUS)。如果返回 false，说明着色器挂了。 - 紧接着，必须调用 gl.getShaderInfoLog(shader)，否则控制台里什么线索都不会有。 - 一个常见的语法陷阱：attribute 和 varying 是 WebGL 1（GLSL ES 1.0）的写法。如果你用了 in 和 out，却没启用 WebGL 2，浏览器直接就报 syntax error。 - 最好不要把着色器直接写成 JavaScript 模板字符串，缩进和换行会被当作真实字符传入。更稳妥的做法是从 这样的标签里，通过 textContent 读取。

三角形画不出来，只看到一片黑或背景色

清屏成功并不等于渲染成功。黑屏的情况，通常卡在数据流向 GPU 的某个中间环节。 - gl.drawArrays() 之前，如果没调用 gl.useProgram(program)，GPU 根本不知道该运行哪个着色器。 - 顶点属性必须启用。gl.enableVertexAttribArray(location) 必须在 gl.vertexAttribPointer() 之后调用。 - 缓冲区绑定要分清目标：传递坐标得用 gl.ARRAY_BUFFER，传递索引才用 gl.ELEMENT_ARRAY_BUFFER。 - 顶点着色器里，gl_Position = ... 是强制要求。如果不赋值，相当于没有输出，GPU 会直接丢弃这个顶点。

矩阵传进去，模型还是不动，或缩成一个点

WebGL 不会理解你的意图，它只认你传进去的那 16 个浮点数。 - gl.uniformMatrix4fv() 接收的是纯数字数组，不能传对象。用 mat4.create() 创建的对象会出错，必须用 mat4.toArray() 或者直接传 Float32Array。 - 投影矩阵 × 视图矩阵 × 模型矩阵 的乘法顺序不能颠倒。写成 model × view × projection，坐标系会全乱。 - mat4.lookAt() 第二个参数是“看向的点”，不是方向向量。第三个参数是“上方向”，如果设成 [0,0,0]，矩阵会变成奇异矩阵，结果不可预测。 - 每帧都 new Float32Array(16) 创建一个新矩阵？GC 压力大而且慢。复用同一个数组，配合 mat4.identity(dest) 重置，才是更稳定的做法。 真正卡住人的，从来不是某一行具体的代码，而是上下文之间那几处隐性的依赖关系：canvas 的状态、着色器的编译链、属性启用开关、矩阵乘法顺序。它们不会报错，但只要漏掉一个，半天就白忙活了。