webgl纹理黑屏或纯色的主因是图像未就绪即调用gl.teximage2d，需确保img.complete为true且naturalwidth>0；跨域图片须设crossorigin=”anonymous”并配服务端响应头；npot尺寸需禁用mipmap或升至webgl 2.0；多纹理须正确绑定不同纹理单元。
WebGL纹理加载黑屏或纯色：检查 gl.texImage2D 的图像就绪状态
canvas 或 <img alt="html5WebGL纹理贴图出错_html5三维模型材质加载失败排查攻略【详解】" > 作为纹理源时，如果没等图片加载完成就调用 gl.texImage2D，WebGL 会静默失败——纹理变黑、模型全灰，控制台也不报错。这不是显卡问题，是时序踩空。
- 必须确认
img.complete === true且img.naturalWidth > 0，否则传给gl.texImage2D就是无效像素源 - 推荐用
img.onload回调（而非addEventListener）确保执行时机；若用 promise 封装，记得 catchimg.onerror - 注意：通过
URL.createObjectURL()创建的 blob URL，也要等load，不能直接赋值后立刻上传
Cross-Origin 图片被拒绝：gl.texImage2D 报错 “Tainted canvases may not be exported”
从其他域名加载的图片（比如 CDN 上的贴图），若未显式声明跨域策略，即使渲染到 canvas 里，WebGL 也会拒绝读取其像素——这是浏览器安全限制，不是 WebGL 自己设的卡。
-
<img alt="HTML5WebGL纹理贴图出错_HTML5三维模型材质加载失败排查攻略【详解】" >标签必须设置crossOrigin="anonymous"，且服务端需返回access-Control-Allow-Origin响应头 - 避免漏掉：Vue/React 中动态创建
img元素时，要用img.crossOrigin = "anonymous"，而不是只写 HTML 属性 - 本地开发时若用
file://协议，所有图片都会触发跨域拦截，必须起一个本地 server（如npx serve）
纹理尺寸非 2 的幂（NPOT）导致材质异常
部分老旧设备或 WebGL 1.0 环境下，若贴图宽高不是 2 的整数次幂（如 300×200、513×513），gl.generateMipmap() 会直接失败，mipmap 层全空，采样时返回 (0,0,0,0) —— 表现为模型突然变透明或发灰。
- 优先用 256×256、512×512、1024×1024 等尺寸；若必须用 NPOT，得禁用 mipmap：
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR) - 检查是否误开了
gl.NEAREST_MIPMAP_NEAREST这类依赖 mipmap 的滤波器 - WebGL 2.0 默认支持 NPOT + mipmap，但需确认浏览器实际启用的是 WebGL 2（
canvas.getContext("webgl2")返回非 NULL）
纹理单位绑定混乱：多个贴图只显示最后一个
同一个着色器里用了 uniform sampler2D uDiffuse 和 uniform sampler2D uNormal，但忘了用 gl.activeTexture() 切换纹理单元，结果两个 uniform 都指向了同一张图。
立即学习“前端免费学习笔记（深入）”；
- 每个
sampler2D必须对应唯一纹理单元，比如：gl.activeTexture(gl.TEXTURE0)→ 绑定漫反射图 →gl.uniform1i(uDiffuseLoc, 0) - 常见错误：重复使用
gl.TEXTURE0，或忘记调用gl.uniform1i设置 uniform 值 - 调试技巧：在 draw call 前加
console.log(gl.getParameter(gl.ACTIVE_TEXTURE))，确认当前激活单元是否符合预期
WebGL 纹理问题的根因往往不在着色器或模型本身，而在资源加载链路的某个微小断点——图没载完、头没跨好、尺寸没对齐、单元没切准。这些地方不报红，只悄悄让画面“不对劲”，排查时容易反复怀疑材质逻辑，其实该先盯住 img 和 gl.activeTexture。