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 的运行要求。

在终端执行:

bash
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 只暂停当前异步函数的后续执行,不会阻塞已经启动的浏览器渲染循环。

GLTFLoader异步请求解析与场景挂载时序

如果多个模型互不依赖,可以使用 Promise.all 并行等待;如果后续操作需要第一个模型的节点或尺寸,则必须先等待前一个加载结果。不要假设网络请求会按照调用顺序完成。

使用 loadAsync 导入并播放模型

将 Vite 工程中的 src/main.js 替换为以下完整代码。示例创建场景、相机、光源和渲染器,启动持续渲染后异步加载模型,再根据模型包围盒调整相机位置。如果模型包含动画,则播放第一段动画。

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 示例时,浏览器控制台输出:

text
已挂载模型: true
动画数量: 3

页面中应显示模型,第一段 Survey 动画自动播放。替换为其他 GLB 后,动画数量由实际文件决定;没有动画时,gltf.animations 是空数组,程序仍然可以显示静态模型。

这里的 AnimationMixer 负责推进动画时间,mixer.update(delta) 必须在每帧执行。只调用 clipAction(...).play() 而不更新 Mixer,动画不会随时间播放。

相机自动定位是为了让不同尺寸的示例模型更容易进入视野,不代表完成了正式资产校准。生产项目还应根据产品朝向、中心点和展示尺度确定相机参数。对于明显偏离原点或带复杂骨骼动画的模型,也需要检查包围盒与动画期间的实际空间范围。

运行验证与排查加载失败

确认 public/models/product.glb 存在,并在项目根目录启动开发服务器:

bash
npm run dev

预期输出包含本地访问地址,典型形式为:

text
Local: http://localhost:<PORT>/

<PORT> 是实际监听端口,Vite 默认通常使用 5173,但端口被占用时可能变化。打开终端显示的真实地址,按 F12 进入浏览器开发者工具。

按以下顺序验证:

  1. 打开 Network 面板,筛选 product.glb,确认请求状态为 200,响应内容是模型文件而非 HTML 页面。
  2. 查看 Console,确认打印 已挂载模型: true。使用 Fox 示例时还应看到动画数量为 3。
  3. 检查页面能否看到模型,并确认动画持续播放;调整窗口大小后,画面比例不应变形。
  4. 将 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 官方文档。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

GLTFLoader 如何异步导入模型

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通