WebGL是OpenGL ES的JavaScript绑定，不内置3D概念，所有3D效果需手动实现MVP变换、光照等；常见黑屏问题多因相机设置、像素比、光源或单位不匹配所致。
WebGL 本身不是 3D 渲染，它是底层图形 API；你写不写 3D 渲染逻辑，它都只管执行你给的 GPU 指令。
WebGL 本质是 OpenGL ES 2.0/3.0 的 JavaScript 绑定
它不内置“3D”概念——没有矩阵栈、没有光照模型、没有相机抽象。所有 gl.drawArrays() 或 gl.drawElements() 调用，渲染什么完全取决于你传的顶点数据和着色器代码。
- 画一个 2D 正方形？只要顶点是四角归一化设备坐标（NDC），
vertexShader直接输出position，就是纯 2D - 想实现 3D 效果？必须自己写 MVP 矩阵变换、法线变换、片元光照计算，或引入
gl-matrix这类数学库辅助 - 浏览器里跑 WebGL 不等于自动启用 3D 加速——如果用户禁用硬件加速，或显卡驱动异常，
gl.getContext('webgl')可能返回null
常见“以为在用 3D”但实际没生效的坑
很多初学者把 Three.js 示例复制过来却只看到黑屏或白板，问题往往不在 WebGL 本身，而在 3D 渲染链路断了一环：
-
camera位置和scene中物体重合或反向：导致裁剪体（frustum）没包住任何东西，renderer.render()什么也不画 - 忘记调用
renderer.setPixelRatio(window.devicePixelRatio)：高 DPI 屏幕下 canvas 缓冲区分辨率不足，3D 模型边缘模糊甚至消失 - 材质用了
MeshStandardMaterial却没加DirectionalLight或AmbientLight：PBR 渲染路径无光即全黑，不是 bug 是预期行为 - 加载 glTF 模型后直接渲染，但模型单位是厘米而相机 near/far 是 0.1 / 1000：z-fighting 或被裁掉，需用
model.scale.set(100, 100, 100)对齐单位
不用 Three.js 也能做轻量 3D 渲染
如果你只需要旋转立方体、带简单光照的球体，或 UI 中嵌入可交互 3D 图标，手写 WebGL 更可控、体积更小（
立即学习“前端免费学习笔记（深入）”；
- 顶点着色器里用
uniform mat4 uMVPMatrix接收 CPU 计算好的模型-视图-投影矩阵，别在 shader 里重复算 - 法线变换必须用
inverseTranspose(uModelMatrix)（或等价的mat3运算），否则缩放会导致光照方向歪斜 - 开启深度测试：
gl.enable(gl.DEPTH_TEST)，且确保gl.clearDepth(1.0)和gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT)配套使用 - 避免每帧重建 buffer：用
gl.bufferData()初始化，后续用gl.bufferSubData()更新局部顶点（如动画骨骼）
真正卡住人的从来不是 WebGL 是否支持 3D，而是矩阵乘法顺序、坐标系约定（OpenGL 是右手还是左手？Three.js 默认是右手，但 WebGPU 已转向左手）、以及 depth buffer 的清空时机——这些细节一旦错位，模型就“消失”得毫无征兆。
