首页 / three.js / API 文档

GLTFLoader

先看结论

glTF 模型加载器。读取 .glb 或 .gltf，返回场景、动画片段与相机，是三维资产进入 three.js 的主通道。

最后验证 2026-11-03 · three.js 0.160.0 · 更新 2026-10-29 · 引用本文

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

构造参数

参数	说明
`manager`	可选的 `LoadingManager`，统一管理进度与纹理路径

方法

方法	返回	说明
`load(url, onLoad, onProgress, onError)`	—	加载完成后把结果传给 `onLoad`
`loadAsync(url, onProgress)`	Promise<Object>	加载完成后 resolve 结果对象
`parse(data, path, onLoad, onError)`	—	解析 ArrayBuffer 或 JSON 字符串，不发起请求
`setDRACOLoader(loader)`	this	启用 Draco 压缩网格支持
`setKTX2Loader(loader)`	this	启用 KTX2 压缩纹理支持
`setMeshoptDecoder(decoder)`	this	启用 meshopt 压缩支持

结果对象

字段	说明
`scene`	默认场景，直接 `scene.add(gltf.scene)` 即可显示
`scenes`	文件中的全部场景
`animations`	`AnimationClip` 数组，交给 `AnimationMixer` 播放
`cameras`	文件里定义的相机
`asset`	glTF 元信息，含生成器与版本
`parser`	底层解析器，访问原始数据时使用

示例

const loader = new GLTFLoader();

const gltf = await loader.loadAsync('/models/building.glb', function (event) {
  if (event.lengthComputable) {
    console.log('加载进度', (event.loaded / event.total * 100).toFixed(1) + '%');
  }
});

const model = gltf.scene;

// 统一开启阴影与材质修正
model.traverse(function (obj) {
  if (obj.isMesh) {
    obj.castShadow = true;
    obj.receiveShadow = true;

    if (obj.material && obj.material.map) {
      obj.material.map.anisotropy = renderer.capabilities.getMaxAnisotropy();
    }
  }
});

scene.add(model);

// 播放动画
if (gltf.animations.length) {
  const mixer = new THREE.AnimationMixer(model);
  mixer.clipAction(gltf.animations[0]).play();
  mixers.push(mixer);
}

压缩资产要配解码器

使用 Draco 压缩网格的文件，不设置 setDRACOLoader 会直接报错「缺少 Draco 解码器」。KTX2 纹理同理。两个解码器的文件都要从 three/addons 或 node_modules/three/examples/jsm 拷贝到部署目录， CDN 场景下需要确认路径可访问。

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

const draco = new DRACOLoader();
draco.setDecoderPath('/wasm/draco/');

const ktx2 = new KTX2Loader()
  .setTranscoderPath('/wasm/basis/')
  .detectSupport(renderer);

loader.setDRACOLoader(draco);
loader.setKTX2Loader(ktx2);

模型位置与尺寸

glTF 使用米制、Y 轴向上，原点由建模软件决定，常见的是模型中心或地面中心。导入后先用 Box3.setFromObject 量出实际尺寸与最低点，再决定缩放与放置高度，比目测调整可靠。

加载后不要忘记释放。频繁切换模型时，旧模型的几何与纹理不会自动回收。移除节点后调用 geometry.dispose()、 material.map.dispose()，否则显存会持续增长。

引用本文

经纬志（2026）。《GLTFLoader》。https://www.jingweizhi.com/three/api/gltf-loader.html（访问日期 2026-11-03）。