WebGL是底层GPU API，需手动编写着色器、绑定缓冲、调用绘制；初始化须用兜底获取上下文并检查null；顶点着色器必须赋值gl_Position为vec4；传矩阵需列主序且缓存uniform位置；清屏前须正确设置viewport和调用clear。
WebGL 不是“开箱即用”的 3D 引擎，它本质是一套底层图形 API，直接操作 GPU；想画个立方体，得自己写 vertexShader、fragmentShader、传 uniform、绑定 buffer、调用 drawArrays——没有封装就等于没有“3D 图形编程”的捷径。
怎么初始化 WebGL 上下文并检查失败原因
很多初学者卡在第一步：getContext('webgl') 返回 null，但没意识到这是硬性失败，不是“稍等一下”。浏览器可能禁用硬件加速、用户关闭了 WebGL、或页面没走 HTTPS（某些新版 Chrome 对本地文件 file:// 拒绝启用 WebGL）。
实操建议：
- 永远用
const gl = canvas.getContext('webgl') || canvas.getContext('experimental-webgl')兜底（旧 Safari 需要后者） - 加判断：
if (!gl) { console.error('WebGL not supported'); return; } - 在 Chrome 中访问
chrome://gpu确认WebGL和WebGL2状态是否为Hardware accelerated
为什么顶点着色器里必须写 gl_Position，且必须是 vec4
这是 WebGL 渲染管线的强制约定：顶点着色器输出的裁剪空间坐标 gl_Position 决定该顶点最终是否被光栅化。漏写、类型写成 vec3 或赋值为 undefined，会导致整个图元（如三角形）被剔除，屏幕一片黑，控制台却无报错。
立即学习“Java免费学习笔记（深入）”；
常见错误现象：
- 只画出部分三角形（某些顶点
gl_Position.w为 0，导致除零或无效裁剪） - 模型整体缩在左下角（忘记把
vec3坐标手动扩展为vec4(position, 1.0)） - 着色器编译成功但渲染空白（
gl_Position被写成其他变量名，比如outPos）
最小合法顶点着色器示例：
attribute vec3 a_position;
void main() {
gl_Position = vec4(a_position, 1.0); // 必须！w=1.0 表示常规齐次坐标
}怎样传入旋转/缩放矩阵到着色器（uniform mat4）
JavaScript 里矩阵是普通数组（长度 16 的 Float32Array），但 WebGL 要求按列主序（column-major）布局；而多数数学库（如 gl-matrix）默认生成列主序矩阵，可直接传——这点极易混淆，因为手算矩阵乘法时人习惯行主序。
实操关键点：
- 先用
gl.getUniformLocation(program, 'u_matrix')获取 uniform 位置 - 调用
gl.uniformMatrix4fv(loc, false, matrix)；第二个参数false表示“不转置”，即传入的就是列主序（若传入行主序矩阵才填true） - 确保着色器里声明匹配：
uniform mat4 u_matrix;，且在main()中用gl_Position = u_matrix * vec4(a_position, 1.0); - 别在每帧重复调用
getUniformLocation——它很慢，应缓存结果
为什么清屏后什么都看不见？检查 gl.viewport 和 gl.clearColor
gl.clearColor(0, 0, 0, 1) 只设置颜色值，不真正清屏；gl.clear(gl.COLOR_BUFFER_BIT) 才执行清除。但更隐蔽的问题是：如果 gl.viewport 尺寸和 canvas 实际像素尺寸不一致（比如 CSS 放大了 canvas），所有顶点会被缩放错位甚至裁剪出界。
务必做这两件事：
- 在每次 canvas 尺寸变化后（包括首次初始化），同步设置：
gl.viewport(0, 0, canvas.width, canvas.height)（注意是canvas.width，不是canvas.clientWidth） - 确认
canvas.width和canvas.height是整数且大于 0（DOM 加载完成前读取可能为 0）
一个典型陷阱：用 CSS 设置 canvas { width: 100%; height: 100vh; }，但没重设 canvas.width/canvas.height 属性——此时绘图会拉伸、模糊甚至完全不可见。
