glTF 与 GLB 模型加载

使用 GLTFLoader 加载 glTF 和 GLB 模型,处理进度、异常、动画、资源路径以及 Draco 和 Meshopt 压缩。

🎯 引言

学完这篇文章,你能在页面中加载真实的 glTF/GLB 模型,处理加载成功、进度和失败状态,遍历模型节点,并知道 Draco、Meshopt 和资源路径分别解决什么问题。

🧱 为什么优先使用 glTF

glTF 是面向实时渲染的三维资源格式,描述模型的节点、网格、材质、纹理和动画。.gltf 通常是一个 JSON 文件加多个外部资源,.glb 把这些内容打包成一个二进制文件,发布时更容易管理。

当前课程使用 Three.js 0.185.1,加载器属于附加模块:

import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';

const loader = new GLTFLoader();
loader.load(
    '/models/avocado.glb',
    (gltf) => {
        const model = gltf.scene;
        scene.add(model);
    },
    (event) => {
        if (event.total) {
            console.log(`加载进度:${Math.round(event.loaded / event.total * 100)}%`);
        }
    },
    (error) => {
        console.error('模型加载失败', error);
    }
);

gltf.scene 是模型的根节点,不要只把一个不确定的子节点直接加入场景。模型加入后可以像普通 Object3D 一样设置位置、缩放和名字。

下面使用真实的 Avocado 牛油果模型,果肉、果核和表皮细节来自模型自带的纹理。演示加载 /models/avocado.glb,按包围盒等比缩放并居中,再用柔和的环境光展示材质。

资源由 Microsoft 提供,收录于 Khronos glTF Sample Assets,采用 CC0 许可。你可以下载本例 GLB,放进项目的 public/models/ 目录复现。

模型加载中

📦 模型整理与自动适配

gltf.scene.name = 'avocado';
gltf.scene.traverse((object) => {
    if (!object.isMesh) return;
    object.castShadow = true;
    object.receiveShadow = true;
    object.userData.modelId = 'avocado-01';
});

const box = new THREE.Box3().setFromObject(gltf.scene);
const size = box.getSize(new THREE.Vector3());
const maxSize = Math.max(size.x, size.y, size.z);
gltf.scene.scale.setScalar(2.8 / maxSize);

const scaledBox = new THREE.Box3().setFromObject(gltf.scene);
const center = scaledBox.getCenter(new THREE.Vector3());
gltf.scene.position.sub(center);

这段整理代码:给根节点命名,方便后续查找;给每个网格补充阴影和业务 id;用包围盒得到模型当前最大尺寸,再把它缩放到大约 2.8 个 Three.js 单位。setScalar 会同时修改 x、y、z,因此模型保持原来的长宽比例,不会被拉扁。缩放后再次计算包围盒并减去中心位置,让模型居中。

真实项目中要先确认模型的单位、朝向和原点。自动缩放前先计算包围盒,缩放后如果要重新定位,还需要再次计算包围盒。

🧰 Draco、Meshopt 与路径问题

Draco 和 Meshopt 都是模型压缩方案,作用是减少模型需要下载或解码的顶点数据。它们不是新的模型格式,而是 glTF/GLB 内部数据的压缩方式;浏览器端因此需要对应解码器:

import { DRACOLoader } from 'three/addons/loaders/DRACOLoader.js';

const dracoLoader = new DRACOLoader();
dracoLoader.setDecoderPath('/draco/');
loader.setDRACOLoader(dracoLoader);

解码器目录必须能被部署后的页面访问。Meshopt 通常通过 GLTFLoader 设置对应的 decoder,具体取决于导出工具和 Three.js 版本。遇到模型空白时,优先检查浏览器 Network 面板中的模型、纹理和解码器请求。

模型加载不会自动解决跨域问题。模型所在服务器需要允许当前页面来源访问,模型内部引用的纹理路径也必须正确。

模型文件可能来自第三方平台,平台的下载按钮和目录结构会更新。文章中的路径只表示代码组织方式,实际使用时请以项目中真实存在的模型和解码器路径为准。

🧾 小节总结

  • glTF 面向实时渲染,GLB 适合把资源打包成单个文件。
  • GLTFLoader 的成功回调中,常用入口是 gltf.scene。
  • 模型加载后可以遍历 Mesh,统一设置阴影、名称和业务数据。
  • Box3 可用于模型居中和相机适配。
  • Draco、Meshopt 能压缩资源,但必须正确配置解码器路径。
  • 模型、纹理和解码器都要检查静态路径与跨域配置。

❓ 知识问答

Q1:.gltf 和 .glb 选哪个?

.glb 发布和传输更简单,.gltf 便于拆开查看 JSON、纹理和二进制数据。项目中按资源管理方式选择即可。

Q2:模型加载成功但纹理不显示怎么办?

检查 glTF 内部引用的纹理相对路径、服务器大小写和 Network 请求状态,不要只检查模型主文件。

Q3:为什么模型看不到?

检查成功回调是否执行、是否加入场景、模型位置和缩放是否合理、相机是否看向模型,以及模型是否需要解码器。

🧪 小练习

准备一个浏览器可以访问的 /models/robot.glb,用 GLTFLoader 加载它,遍历所有网格并为它们设置 castShadow,再用 Box3 把模型移动到原点。

// 请在这里编写代码

🎉 真实模型是 Three.js 项目从练习场景走向产品页面的重要一步。下一篇让物体和模型动画真正运行起来。