Web 图形与 3D / 系统课时

用 GLTFLoader 加载 GLB 文件

用 GLTFLoader 加载 GLB 文件

把一份 GLB 模型放进 Three.js 页面,关键是等待 GLTFLoader.loadAsync() 完成后,将返回的 gltf.scene 加到已有场景。本篇用 Vite 搭建一个可运行示例,同时检查加载结果、异步时机与常见路径错误。

学习目标

  • 正确引入 GLTFLoader 并使用 loadAsync() 读取 GLB。
  • 将模型根节点加入场景,理解返回对象的主要字段。
  • 通过浏览器画面、控制台与 Network 面板判断加载是否成功。

准备工程与模型路径

示例使用支持 ES Module 的 Three.js 与 Vite。先确认已安装满足当前 Vite 要求的 Node.js,再在终端执行:

bash
# 创建原生 JavaScript 工程并安装 Three.js
npm create vite@latest glb-viewer -- --template vanilla
cd glb-viewer
npm install
npm install three

预期结果:工程中存在 index.html 和 src/main.js,依赖安装成功;index.html 的 #app 是稍后挂载画布的容器。

在项目根目录创建 public/models/,放入一份确实包含网格的有效 GLB,命名为 sample.glb。这是学习者自备的模型文件,不是由代码自动生成。Vite 会将 public/models/sample.glb 映射到开发服务器的 /models/sample.glb;不要把 public 写进浏览器请求路径。建议首次使用以原点为中心、大小约 1~2 米且未启用 Draco 或 Meshopt 压缩的简单模型。

使用 loadAsync 加入场景

用下面的完整代码替换 src/main.js。场景、相机和渲染器先建立,渲染循环立即启动;loadModel() 等待资源解析成功后,才将模型根节点加入 scene。

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

const scene = new THREE.Scene();
scene.background = new THREE.Color(0x1b2635);
const camera = new THREE.PerspectiveCamera(
  45, window.innerWidth / window.innerHeight, 0.1, 1000
);
camera.position.set(2, 2, 4);
camera.lookAt(0, 0, 0);

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.querySelector('#app').replaceChildren(renderer.domElement);

scene.add(new THREE.HemisphereLight(0xffffff, 0x444444, 2));
const light = new THREE.DirectionalLight(0xffffff, 2);
light.position.set(3, 5, 4);
scene.add(light);

// 渲染无需等待网络请求完成。
renderer.setAnimationLoop(() => renderer.render(scene, camera));

async function loadModel() {
  const loader = new GLTFLoader();
  try {
    // BASE_URL 兼容部署在网站子路径下的 Vite 工程。
    const url = `${import.meta.env.BASE_URL}models/sample.glb`;
    const gltf = await loader.loadAsync(url);
    scene.add(gltf.scene);

    // 将镜头对准模型范围,避免资源尺度或位置不同导致看不到。
    const box = new THREE.Box3().setFromObject(gltf.scene);
    if (!box.isEmpty()) {
      const sphere = box.getBoundingSphere(new THREE.Sphere());
      const d = Math.max(sphere.radius * 3, 2);
      camera.position.copy(sphere.center).add(
        new THREE.Vector3(d * 0.6, d * 0.4, d)
      );
      camera.lookAt(sphere.center);
    }

    console.log('加载成功:', gltf.scene instanceof THREE.Object3D);
    console.log('已加入场景:', gltf.scene.parent === scene);
    console.log('动画列表有效:', Array.isArray(gltf.animations));
  } catch (error) {
    console.error('GLB 加载失败:', error);
  }
}
loadModel();

window.addEventListener('resize', () => {
  camera.aspect = window.innerWidth / window.innerHeight;
  camera.updateProjectionMatrix();
  renderer.setSize(window.innerWidth, window.innerHeight);
});

对于有效 GLB,预期控制台输出:

text
加载成功: true
已加入场景: true
动画列表有效: true

页面应显示深蓝背景及模型。模型实际外观、材质和是否有动画取决于提供的 sample.glb,不会凭空生成。代码中的包围盒计算只用于把镜头朝向模型,若模型包含非常分散的对象,仍可能需要调整视角。

看懂异步时机与返回结构

loadAsync(url) 返回 Promise;await 暂停的是 loadModel() 函数后续语句,不会暂停已经启动的渲染循环。只有请求、解析和所需资源加载成功,代码才会执行 scene.add(gltf.scene)。这表示模型可加入场景,不保证该帧已经完成 GPU 渲染。

GLB 异步加载、返回对象与渲染循环的关系

返回字段 含义 这一课的用法
gltf.scene 默认 glTF 场景的 Group 根节点 交给 scene.add()
gltf.scenes 文件中定义的全部场景 需要其他场景时另行选择
gltf.animations AnimationClip 数组 后续配合 AnimationMixer 播放
gltf.cameras 文件自带的相机数组 不会自动替换当前相机

注意不要写 scene.add(gltf):整个加载结果是一个对象容器,不是 Three.js 场景节点。也不要在 await 之前访问尚未获得的 gltf.scene。

运行、验收与定位失败

代码和 GLB 都准备好后,在项目目录执行:

bash
npm run dev

预期结果:终端显示 Vite 的本地访问地址(主机、端口和启动耗时随环境变化);打开该地址后,浏览器控制台应出现前述三个 true,且模型进入画面。按 F12 打开 DevTools 的 Network,筛选 sample.glb,确认请求状态为 200,并在刷新后复查。

若失败,可按现象定位:

  1. Network 返回 404:核对文件确实在 public/models/sample.glb,以及请求 URL 是否包含正确的 BASE_URL;不要写成 /public/models/sample.glb。
  2. 请求成功但控制台报解析或解压错误:确认文件是真实的 glTF 2.0 二进制资源。若使用 KHR_draco_mesh_compression、EXT_meshopt_compression 或 KHR_texture_basisu,按所用扩展另行配置解码器或纹理加载器。
  3. 日志显示三个 true 但画面无模型:检查模型是否有网格、是否被隐藏、包围盒是否正常,以及灯光、相机近远裁剪面和材质;不能仅凭请求 200 判断模型可见。

loadAsync() 的异常进入 catch,因此实际项目还应把错误写进页面的加载状态,而非只留在控制台。官方接口可对照 GLTFLoader 文档。

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

目录与阅读设置

阅读设置

17

记录一个想法

用 GLTFLoader 加载 GLB 文件

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

登录哪都通