Web 图形与 3D / 系统课时
GLTFLoader 如何异步导入模型
GLTFLoader 如何异步导入模型
本课把 glTF 2.0 模型导入可运行的 Three.js 页面,使用 GLTFLoader.loadAsync 等待资源加载和解析完成,再将模型加入场景。完成后可以读取模型层级与动画列表、播放动画,并排查路径错误和异步执行顺序问题。
学习目标
- 使用
GLTFLoader和loadAsync导入 GLB 或 glTF 模型。 - 正确读取
scene、animations,并在加载完成后挂载模型、启动动画。 - 区分文件请求、资源解析与场景渲染的执行顺序,定位常见加载失败。
准备工程与模型资源
本例使用 Three.js、Vite 和原生 JavaScript。建议安装 Node.js 20.19+ 或 22.12+,以满足当前 Vite 的运行要求。
在终端执行:
npm create vite@latest gltf-viewer -- --template vanilla
cd gltf-viewer
npm install
npm install three预期结果:生成包含 index.html、src/main.js 和 package.json 的 Vite 项目,并成功安装 Three.js。安装日志中的版本号和耗时随环境变化。
准备一个 glTF 2.0 格式的 GLB 文件,放到项目的 public/models/product.glb。可以下载 Khronos Fox.glb 示例模型,保存并重命名为 product.glb。该示例包含 Survey、Walk、Run 三段动画,适合验证加载和动画播放。
Vite 会将 public 目录中的文件作为静态资源发布。因此,默认开发环境下,public/models/product.glb 对应的请求路径是 /models/product.glb。实际开发应通过 HTTP 服务访问模型,而不是直接用 file:// 打开页面。
GLB 通常把几何数据、动画和纹理打包在一个二进制文件中。另一种格式 .gltf 是 JSON 描述文件,可能引用外部 .bin 和纹理文件;移动模型时必须保留这些依赖文件及其相对路径。
理解异步加载的执行顺序
GLTFLoader 是 Three.js 的附加模块,需要显式从 three/addons/loaders/GLTFLoader.js 导入。它负责请求和解析 glTF 2.0 资产,并把模型节点、材质和动画转换成 Three.js 对象。
调用 loadAsync(url) 后,会得到一个 Promise。资源加载与解析成功时,Promise 兑现为 glTF 结果对象;请求或解析失败时,Promise 拒绝,应使用 try/catch 处理。
主要返回属性如下:
| 属性 | 含义与用途 |
|---|---|
gltf.scene |
默认场景根节点,通常直接加入 Three.js 场景 |
gltf.scenes |
文件中包含的全部场景,类型为数组 |
gltf.animations |
动画片段数组,每项为 AnimationClip |
gltf.cameras |
模型文件内定义的相机数组 |
gltf.parser |
加载器内部解析器,可用于进一步访问模型资源 |
必须在 await loader.loadAsync(url) 完成后才能访问 gltf.scene。await 只暂停当前异步函数的后续执行,不会阻塞已经启动的浏览器渲染循环。

如果多个模型互不依赖,可以使用 Promise.all 并行等待;如果后续操作需要第一个模型的节点或尺寸,则必须先等待前一个加载结果。不要假设网络请求会按照调用顺序完成。
使用 loadAsync 导入并播放模型
将 Vite 工程中的 src/main.js 替换为以下完整代码。示例创建场景、相机、光源和渲染器,启动持续渲染后异步加载模型,再根据模型包围盒调整相机位置。如果模型包含动画,则播放第一段动画。
import * as THREE from 'three';
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
const scene = new THREE.Scene();
scene.background = new THREE.Color(0xf0f3f7);
const camera = new THREE.PerspectiveCamera(
45,
window.innerWidth / window.innerHeight,
0.01,
2000
);
const renderer = new THREE.WebGLRenderer({ antialias: true });
renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
renderer.setSize(window.innerWidth, window.innerHeight);
document.body.style.margin = '0';
document.body.appendChild(renderer.domElement);
scene.add(new THREE.HemisphereLight(0xffffff, 0x667788, 2.5));
const light = new THREE.DirectionalLight(0xffffff, 2.5);
light.position.set(3, 5, 4);
scene.add(light);
const clock = new THREE.Clock();
let mixer;
async function loadProduct() {
try {
// BASE_URL 兼容部署在子路径下的 Vite 应用
const url = `${import.meta.env.BASE_URL}models/product.glb`;
const loader = new GLTFLoader();
const gltf = await loader.loadAsync(url);
// 必须等待 Promise 完成后再访问模型场景
scene.add(gltf.scene);
// 根据已加载模型的世界包围盒调整观察位置
const box = new THREE.Box3().setFromObject(gltf.scene);
const center = box.getCenter(new THREE.Vector3());
const extent = box.getSize(new THREE.Vector3()).length();
const distance = Math.max(extent, 1) * 1.5;
camera.position.set(
center.x,
center.y + distance * 0.25,
center.z + distance
);
camera.lookAt(center);
if (gltf.animations.length > 0) {
mixer = new THREE.AnimationMixer(gltf.scene);
mixer.clipAction(gltf.animations[0]).play();
}
console.log('已挂载模型:', scene.children.includes(gltf.scene));
console.log('动画数量:', gltf.animations.length);
} catch (error) {
console.error('glTF 加载失败:', error);
}
}
function render() {
requestAnimationFrame(render);
const delta = clock.getDelta();
if (mixer) mixer.update(delta);
renderer.render(scene, camera);
}
// 渲染循环先启动,资源加载独立进行
render();
loadProduct();
window.addEventListener('resize', () => {
camera.aspect = window.innerWidth / window.innerHeight;
camera.updateProjectionMatrix();
renderer.setSize(window.innerWidth, window.innerHeight);
});预期结果:使用前面提供的 Khronos Fox.glb 示例时,浏览器控制台输出:
已挂载模型: true
动画数量: 3页面中应显示模型,第一段 Survey 动画自动播放。替换为其他 GLB 后,动画数量由实际文件决定;没有动画时,gltf.animations 是空数组,程序仍然可以显示静态模型。
这里的 AnimationMixer 负责推进动画时间,mixer.update(delta) 必须在每帧执行。只调用 clipAction(...).play() 而不更新 Mixer,动画不会随时间播放。
相机自动定位是为了让不同尺寸的示例模型更容易进入视野,不代表完成了正式资产校准。生产项目还应根据产品朝向、中心点和展示尺度确定相机参数。对于明显偏离原点或带复杂骨骼动画的模型,也需要检查包围盒与动画期间的实际空间范围。
运行验证与排查加载失败
确认 public/models/product.glb 存在,并在项目根目录启动开发服务器:
npm run dev预期输出包含本地访问地址,典型形式为:
Local: http://localhost:<PORT>/<PORT> 是实际监听端口,Vite 默认通常使用 5173,但端口被占用时可能变化。打开终端显示的真实地址,按 F12 进入浏览器开发者工具。
按以下顺序验证:
- 打开 Network 面板,筛选
product.glb,确认请求状态为200,响应内容是模型文件而非 HTML 页面。 - 查看 Console,确认打印
已挂载模型: true。使用 Fox 示例时还应看到动画数量为3。 - 检查页面能否看到模型,并确认动画持续播放;调整窗口大小后,画面比例不应变形。
- 将
product.glb临时改名,刷新页面,确认catch分支报告加载失败;恢复文件名后应重新加载成功。
常见问题及修复方法:
| 现象 | 可能原因 | 修复方法 |
|---|---|---|
| Network 返回 404 | URL 与 public 目录路径不一致 |
检查文件名大小写及 models/ 目录 |
| 请求成功但解析失败 | 返回了 HTML、文件损坏或格式不符合 glTF 2.0 | 检查响应内容并重新导出模型 |
.gltf 加载时依赖文件 404 |
.bin 或纹理路径错误 |
按 glTF 内部 URI 保留依赖文件的相对位置 |
| 远程模型出现 CORS 错误 | 资源服务器未允许跨源请求 | 使用同源静态资源或配置服务端 CORS |
| 提示缺少压缩解码器 | 模型使用 Draco 等压缩扩展 | 按扩展类型配置 DRACOLoader 等对应解码器 |
| 模型已加载但不可见 | 相机、模型比例、裁剪范围或光照不合适 | 检查包围盒尺寸、相机位置与材质显示 |
另外,GLTFLoader 不会自动播放动画,也不会自动将模型放入应用场景。加载器只负责得到解析结果,场景挂载、动画调度和加载失败时的界面反馈仍由应用代码负责。
对于产品展示项目,建议把模型加载封装为一个返回 Promise 的函数,调用方在加载完成后再绑定热点、材质切换或交互控制。这样可以避免界面先访问尚不存在的模型节点。接口细节可查阅 Three.js GLTFLoader 官方文档。