【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