Three.js 里 GLB 加载失败怎么办？常见原因和排查顺序

GLB 在 Three.js 里加载失败，不一定是 Three.js 本身的问题。文件可能不完整，压缩扩展没有 decoder，部署路径错了，被 CORS 拦住，MIME 类型不对，或者模型太大导致浏览器撑不住。

排查时先把“模型问题”和“运行环境问题”分开。把同一个文件放进浏览器本地的 3D 模型查看 里测试。如果那里也打不开，先查模型本身。如果本地查看能打开，但你的 Three.js 页面打不开，问题多半在加载器配置、部署路径或场景设置。

1. 文件路径不对

这是最常见也最容易忽略的原因。开发环境里路径能访问，部署后因为 base path、静态目录、构建产物位置或 CDN 路径变化，模型请求失败。

先打开浏览器 Network 面板，看这些信息：

• .glb 或 .gltf 请求是不是 200？
• 返回的是模型文件，还是一个 HTML 页面？
• 部署后路径有没有变？
• 请求是否被重定向、鉴权或 404 拦住？

如果请求根本没有拿到模型字节，就不要继续调材质和灯光。先修部署路径。

2. glTF 引用了缺失资源

.gltf 文件本身是 JSON，它可能引用外部 .bin 文件和贴图。JSON 文件加载成功，并不代表模型完整。如果 .bin 或图片缺失，模型可能失败、缺材质或显示不完整。

网页交付想省事，优先导出自包含 GLB。如果必须使用文件夹形式的 glTF，就要把所有被引用资源一起部署，并保持相对路径不变。

3. Draco 或 meshopt decoder 没配置

压缩过的 glTF/GLB 需要对应 decoder。Three.js 的 GLTFLoader 支持 glTF 格式，但 Draco、meshopt 等压缩扩展需要额外配置。可以参考 Three.js GLTFLoader 文档 检查扩展和 loader 设置。

如果未压缩 GLB 能加载，压缩 GLB 不能加载，重点检查：

• DRACOLoader 的 decoder 路径。
• meshopt decoder 是否设置。
• decoder 文件是否真的被部署。
• 服务器能否正确提供 WASM 或 JS decoder。
• 目标运行时是否支持该压缩扩展。

压缩只有在运行时能解码时才有意义。

4. CORS 或 MIME 类型问题

如果模型、贴图或 decoder 放在另一个域名上，响应头必须允许浏览器跨域读取。否则文件存在，浏览器也会拒绝交给加载器。

MIME 类型也要检查。普通静态托管通常能处理 .glb，但自定义服务器可能把模型当成文本、HTML 或下载附件。加载器报 parse 错误时，不要只看代码，也要看 response headers 和实际返回内容。

5. 模型加载了，但画布是空的

有时 GLB 已经加载成功，只是你看不到。常见原因包括：

• 相机没有对准模型。
• 模型比例极小或极大。
• 模型原点离可见网格很远。
• 没有灯光，或灯光太弱。
• 材质透明、全黑，或受色彩管理影响。
• near/far 裁剪面把模型截掉。

可以先用 bounding box 帮助器或自动适配相机。如果缩放很远之后模型才出现，问题通常在比例、原点或边界尺寸。

6. 用最小复现缩小范围

不要一开始就拿完整生产模型排查。更稳的办法是准备三个文件：一个确定能加载的官方或示例 GLB，一个未压缩的小模型，一个当前失败的模型。把三者放到同一段加载代码里测试。

如果示例模型能打开，小模型也能打开，只有生产模型失败，问题基本在资产本身或压缩扩展。如果三个都失败，优先查路径、CORS、loader 引入和渲染初始化。如果未压缩版本可以打开，压缩版本不能打开，就集中看 Draco 或 meshopt decoder。

最小复现还能避免把问题误判成框架问题。很多时候，真正的原因只是某个 .bin 文件没部署、模型路径返回了 HTML、或压缩 decoder 没被复制到静态目录。

7. 浏览器内存或 GPU 限制

模型合法，不代表所有浏览器都能稳定加载。超大贴图、高面数、过多网格和复杂材质，都可能让标签页卡死或 WebGL 上下文丢失。移动端和旧电脑更容易遇到。

先看文件大小、三角面、顶点、贴图预算。如果模型太重，可以用 3D 模型压缩 生成一个更轻的测试版本，再比较加载表现。

推荐排查顺序

1. 先在已知可用的查看器里测试文件。
2. 看 Network 面板是否有失败请求。
3. 确认 .gltf 的外部资源是否齐全。
4. 检查 Draco 或 meshopt decoder 设置。
5. 检查 CORS 和 response headers。
6. 用 bounds 自动适配相机。
7. 测试较小或未压缩版本。

一句话总结

Three.js 里 GLB 加载失败时，先确认模型本身能不能在其他查看器打开，再查路径、外部资源、Draco 或 meshopt decoder、CORS、MIME、相机视角、比例和浏览器内存。很多问题来自部署和资产假设，不是渲染循环本身。