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,再在终端执行:
# 创建原生 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。
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,预期控制台输出:
加载成功: true
已加入场景: true
动画列表有效: true页面应显示深蓝背景及模型。模型实际外观、材质和是否有动画取决于提供的 sample.glb,不会凭空生成。代码中的包围盒计算只用于把镜头朝向模型,若模型包含非常分散的对象,仍可能需要调整视角。
看懂异步时机与返回结构
loadAsync(url) 返回 Promise;await 暂停的是 loadModel() 函数后续语句,不会暂停已经启动的渲染循环。只有请求、解析和所需资源加载成功,代码才会执行 scene.add(gltf.scene)。这表示模型可加入场景,不保证该帧已经完成 GPU 渲染。

| 返回字段 | 含义 | 这一课的用法 |
|---|---|---|
gltf.scene |
默认 glTF 场景的 Group 根节点 |
交给 scene.add() |
gltf.scenes |
文件中定义的全部场景 | 需要其他场景时另行选择 |
gltf.animations |
AnimationClip 数组 |
后续配合 AnimationMixer 播放 |
gltf.cameras |
文件自带的相机数组 | 不会自动替换当前相机 |
注意不要写 scene.add(gltf):整个加载结果是一个对象容器,不是 Three.js 场景节点。也不要在 await 之前访问尚未获得的 gltf.scene。
运行、验收与定位失败
代码和 GLB 都准备好后,在项目目录执行:
npm run dev预期结果:终端显示 Vite 的本地访问地址(主机、端口和启动耗时随环境变化);打开该地址后,浏览器控制台应出现前述三个 true,且模型进入画面。按 F12 打开 DevTools 的 Network,筛选 sample.glb,确认请求状态为 200,并在刷新后复查。
若失败,可按现象定位:
- Network 返回 404:核对文件确实在
public/models/sample.glb,以及请求 URL 是否包含正确的BASE_URL;不要写成/public/models/sample.glb。 - 请求成功但控制台报解析或解压错误:确认文件是真实的 glTF 2.0 二进制资源。若使用
KHR_draco_mesh_compression、EXT_meshopt_compression或KHR_texture_basisu,按所用扩展另行配置解码器或纹理加载器。 - 日志显示三个
true但画面无模型:检查模型是否有网格、是否被隐藏、包围盒是否正常,以及灯光、相机近远裁剪面和材质;不能仅凭请求200判断模型可见。
loadAsync() 的异常进入 catch,因此实际项目还应把错误写进页面的加载状态,而非只留在控制台。官方接口可对照 GLTFLoader 文档。