【three.js教程】Three.js 加载 3D 模型（Loading 3D Models）：选对格式，少踩一半坑
Three.js 加载 3D 模型（Loading 3D Models）：选对格式，少踩一半坑
原文出处：Three.js Manual – Loading 3D Models
本文基于官方手册 Loading 3D Models 章节整理，用通俗方式带你看懂：3D 模型该用什么格式、怎么加载进来、出问题怎么排查。
写在前面
前面我们一直用BoxGeometry、SphereGeometry这些内置图元，凑合着搭场景。但真实项目里，谁还手搓模型啊？你想要的明明是一个精致的角色、一台车、一座建筑——这些得靠 3D 软件（Blender、Maya、C4D…）做出来，再加载进 three.js。
可别小看"加载"这步。3D 模型有几百种文件格式，每种用途、复杂度天差地别。官方这篇手册就给了绝大多数人该走的推荐路线，以及"翻车了怎么办"的排查清单。这篇帮你一次记牢。
一、动手前先确认一件事
如果你还没跑过本地服务器，建议先看官方的 Installation（安装） 那篇。
⚠️很多"看不了模型"的报错，根源都是文件没用服务器正确托管。模型、贴图这些资源走
file://直接打开页面经常会被浏览器的安全策略拦掉。所以：先起个本地服务器，别双击 HTML 就完事。
二、推荐格式：无脑选 glTF
只要条件允许，首选 glTF（GL Transmission Format）。它的.GLB和.GLTF两个版本 three.js 都支持得很好。
为什么是它？因为 glTF 是专门为运行时资源传输设计的——体积小、加载快。而且它该有的都有：
- 网格（meshes）、材质（materials）、纹理（textures）
- 蒙皮（skins）、骨架（skeletons）、变形目标（morph targets）
- 动画（animations）、灯光（lights）、相机（cameras）
换句话说，你在 3D 软件里做好的东西，它能比较完整地搬过来。
去哪搞 glTF 文件？
- 现成的：Sketchfab 上有大量公域（public domain）模型可下载。
- 自己导出：Blender、Substance Painter、Modo、Toolbag、Houdini、Cinema 4D 都支持直接导出 glTF。
实在没 glTF 怎么办？FBX、OBJ、COLLADA 这些也是常用且有人维护的格式，可以退而求其次。
三、加载：几行代码的事
three.js 默认只内置了少数几个 Loader（比如ObjectLoader），其余的得自己单独引。glTF 用的是GLTFLoader，从 addons 引入：
import{GLTFLoader}from'three/addons/loaders/GLTFLoader.js';引完就能往场景里加模型了：
constloader=newGLTFLoader();loader.load('path/to/model.glb',function(gltf){scene.add(gltf.scene);// 加载成功，把模型加进场景},undefined,// 进度回调（可选，这里先不写）function(error){console.error(error);// 加载失败，打印错误});几个要点：
loader.load有四个参数：路径、成功回调、进度回调（可传undefined）、错误回调。- 成功回调里拿到的是
gltf对象，真正要加的是gltf.scene。 - 不同 Loader 语法不一样——换别的格式时，记得去查那个 Loader 的文档和示例，别照抄这套。
四、翻车排查清单（救命用）
你花几小时雕了个 masterpiece，一加载——扭曲了？变色了？干脆消失了？ 别慌，按这个顺序来：
- 看控制台：打开浏览器 DevTools 的 Console，看有没有报错；再确认
.load()里写了onError回调，把错误打出来。 - 换个软件看：glTF 有现成的拖拽查看器（three.js 官方查看器、Babylon.js 沙盒）。如果在别处显示正常 → 大概率是 three.js 的 bug，去提 issue；如果哪儿都显示不了→ 那是建模软件导出的问题，去找它。
- 放大/缩小 1000 倍试试：很多模型比例完全不同。万一模型巨大，相机可能直接"钻"进模型里了，自然看不见。
- 加个光源：模型可能只是藏在黑暗里。回顾下打灯那篇——没光的话
MeshStandardMaterial这类材质就是一片黑。 - 查贴图请求：在 Network 面板看有没有加载失败的纹理，比如路径长这样
"C:\Path\To\Model\texture.jpg"。这是绝对路径惹的祸——改成相对路径，比如images/texture.jpg。必要时用文本编辑器改一下模型文件里的路径。
五、真的搞不定？怎么问才有人理
如果上面都试了还不行，去 three.js 论坛 发帖。问得对，解决才快：
- 尽量附上你的模型（或一个有同样问题的简化版），以及你能拿到的所有格式
- 给足别人能复现问题的信息——最好能直接扔一个在线 demo 链接
总结
| 环节 | 关键点 |
|---|---|
| 格式选择 | 首选 glTF（.glb/.gltf），不行再 FBX/OBJ/COLLADA |
| 前置条件 | 用本地服务器托管文件，别file://双击 |
| 加载 | 自行 import Loader（如GLTFLoader），gltf.scene才是要加的对象 |
| 常见翻车 | 比例太大/太小、没打光、贴图绝对路径 |
| 求助姿势 | 论坛发帖 + 附模型 + 可复现 demo |
记住一句：模型加载的坑，八成出在格式选错、文件托管、或者比例/光照——按上面清单走一遍，基本都能解决。
延伸阅读
- Installation（本地服务器/安装）
- GLTFLoader 文档
- glTF 官方查看器
- three.js 论坛