webgl本身不强制3d渲染，仅执行着色器和顶点数据；黑屏主因是mvp变换、深度测试、光照或单位配置缺失，而非不支持3d。
WebGL 本身不“要求”3D 渲染，它根本不管你是画 2D 还是 3D——它只执行你写的着色器和传的顶点数据。所谓“3D 渲染”，是你自己用矩阵、深度测试、光照模型拼出来的，WebGL 只提供底层指令通道。
WebGL 初始化失败就别谈 3D 了
常见现象：getContext('webgl') 返回 null，控制台静默无报错或只有一句 WebGL not supported。这不是代码写错了，而是环境卡在第一关。
- Canvas 元素必须有明确的
width和height属性值（不是仅靠 CSS 设置），否则缓冲区创建失败 - 浏览器禁用了硬件加速（比如某些企业策略锁死 GPU）——可检查
chrome://gpu中WebGL和Hardware acceleration状态是否为Enabled - 页面刚加载时 Canvas 还在
display: none或父容器不可见，getContext会失败；需等元素挂载并可见后再初始化 - 部分旧版 Safari 或 iOS WebView 需显式传参：
canvas.getContext('webgl', { alpha: false, depth: true, stencil: false })，漏掉depth: true会导致后续无法启用深度测试
黑屏？大概率是 3D 链路断在 MVP 或光源上
WebGL 黑屏从不因为“不支持 3D”，而总因某一个 3D 必要环节缺失：相机没看到东西、深度没开、光没打上去、单位严重错位。
-
gl.enable(gl.DEPTH_TEST)必须调用，且每帧gl.clear()要包含gl.DEPTH_BUFFER_BIT，否则 z-fighting 或全黑 - 相机位置和模型重合（
camera.position.set(0,0,0)而模型也在原点）→ 裁剪体里啥都没有 → 渲染空白 - 使用
MeshStandardMaterial却没加任何DirectionalLight或AmbientLight→ PBR 计算结果全黑，不是 bug 是设计如此 - 模型单位是米，但
camera.near = 0.1、far = 100，而模型实际在 z=500 处 → 直接被裁掉；得统一缩放或改 camera 参数 - 忘记调用
renderer.setPixelRatio(window.devicePixelRatio)→ 高 DPI 屏幕下缓冲区太小，模型糊成一片甚至消失
纹理跨域不设 crossOrigin 就是静默黑块
从 CDN 或非同源地址加载纹理图片时，若没配 crossOrigin，WebGL 会拒绝读取该纹理——不报错、不警告，只渲染成纯黑或默认灰块。这是最常被忽略的“黑屏元凶”。
- 加载图片时必须设：
textureImage.crossOrigin = 'anonymous' - Three.js 中创建
TextureLoader后，加载前需手动 patch：loader.setCrossOrigin('anonymous') - 服务端未返回
Access-Control-Allow-Origin响应头，前端设了也白搭；CDN 需确认已开启 CORS 支持 - 本地开发用
file://协议直接打开 HTML？所有跨域规则失效，但 WebGL 仍会因安全限制拒绝纹理 —— 必须起本地 server（如npx serve）
真正难的从来不是“能不能跑 3D”，而是矩阵乘法顺序、深度缓冲清空时机、着色器精度声明、以及跨域纹理这种连错误都不报的静默失败。这些地方一错，画面就停在黑屏，而调试器里什么线索都没有。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
