threejs-syntax-loaders

threejs-syntax-loaders

快速参考

加载器架构

所有 Three.js 加载器都继承 Loader 基类，并共享两种加载模式：

// Callback style
loader.load(url, onLoad, onProgress, onError);

// Promise style (preferred)
const result = await loader.loadAsync(url, onProgress);

导入路径

加载器	导入
TextureLoader	import { TextureLoader } from 'three';
CubeTextureLoader	import { CubeTextureLoader } from 'three';
GLTFLoader	import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
DRACOLoader	import { DRACOLoader } from 'three/addons/loaders/DRACOLoader.js';
KTX2Loader	import { KTX2Loader } from 'three/addons/loaders/KTX2Loader.js';
FBXLoader	import { FBXLoader } from 'three/addons/loaders/FBXLoader.js';
OBJLoader	import { OBJLoader } from 'three/addons/loaders/OBJLoader.js';
MTLLoader	import { MTLLoader } from 'three/addons/loaders/MTLLoader.js';
RGBELoader	import { RGBELoader } from 'three/addons/loaders/RGBELoader.js';
MeshoptDecoder	import { MeshoptDecoder } from 'three/addons/libs/meshopt_decoder.module.js';

格式建议

始终优先使用 glTF/GLB，而非其他 3D 格式。glTF 是 Three.js 推荐的格式。它支持在单个文件中包含 PBR 材质、动画、摄像机、灯光和场景层级。若要以单文件形式分发，请使用 .glb（二进制 glTF）。

重要警告

绝不要在 requestAnimationFrame 或任何渲染循环中调用 loader.load()。应在初始化时加载资源，并缓存结果。

绝不要忘记在加载 Draco 压缩模型前设置 DRACOLoader 解码器路径。该路径必须指向包含 draco_decoder.wasm 的目录。

绝不要在调用 loadAsync 时跳过错误处理。始终使用 try/catch 包装调用。加载失败且没有错误处理程序时，程序会无声崩溃。

绝不要在移除模型时忘记释放已加载的模型。GLTF 模型包含网格、材质和纹理，所有这些都需要释放。

始终为漫反射/颜色纹理（map、emissiveMap）设置 texture.colorSpace = THREE.SRGBColorSpace。绝不要为数据纹理（normalMap、roughnessMap、metalnessMap、aoMap）设置 SRGBColorSpace。

始终在所有 Draco 压缩模型加载完成后调用 dracoLoader.dispose()，以释放 WASM 解码器内存。

---

Loader 基类

每个加载器都继承了 Loader 的以下方法：

方法	签名	用途
load	(url, onLoad, onProgress, onError)	基于回调的加载
loadAsync	(url, onProgress) => Promise	基于 Promise 的加载
setPath	(path: string)	为所有加载设置基础 URL 前缀
setResourcePath	(path: string)	设置资源解析路径
setCrossOrigin	(value: string)	设置 CORS 模式
setWithCredentials	(value: boolean)	启用跨源凭据
setRequestHeader	(header: object)	设置自定义 HTTP 标头

---

LoadingManager

协调多个加载器并跟踪整体进度。

import * as THREE from 'three';

const manager = new THREE.LoadingManager(
  () => { console.log('All assets loaded'); },
  (url, loaded, total) => { console.log(`Progress: ${loaded}/${total}`); },
  (url) => { console.error(`Failed to load: ${url}`); }
);

// Pass manager to any loader
const textureLoader = new THREE.TextureLoader(manager);
const gltfLoader = new GLTFLoader(manager);

管理器回调

回调	签名	时机
onStart	(url, itemsLoaded, itemsTotal)	第一个项目开始加载时
onLoad	()	所有项目加载完成时
onProgress	(url, itemsLoaded, itemsTotal)	每个项目完成时
onError	(url)	项目加载失败时

管理器方法

方法	用途
itemStart(url)	手动注册加载项目
itemEnd(url)	手动标记项目已加载
itemError(url)	手动标记项目加载失败
resolveURL(url)	通过修改器解析 URL
setURLModifier(callback)	自定义 URL 重写（blob URL、服务工作线程）

---

GLTFLoader

用于加载 3D 模型的主要加载器。glTF 2.0 支持网格、PBR 材质、动画、摄像机、灯光和场景层级。

使用 Draco 压缩进行设置

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

const dracoLoader = new DRACOLoader();
dracoLoader.setDecoderPath('https://www.gstatic.com/draco/versioned/decoders/1.5.6/');

const gltfLoader = new GLTFLoader();
gltfLoader.setDRACOLoader(dracoLoader);

使用 KTX2 纹理进行设置

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

const ktx2Loader = new KTX2Loader();
ktx2Loader.setTranscoderPath('/basis/');
ktx2Loader.detectSupport(renderer); // MUST pass renderer instance

gltfLoader.setKTX2Loader(ktx2Loader);

使用 Meshopt 解码器进行设置

import { MeshoptDecoder } from 'three/addons/libs/meshopt_decoder.module.js';

await MeshoptDecoder.ready;
gltfLoader.setMeshoptDecoder(MeshoptDecoder);

加载模型

try {
  const gltf = await gltfLoader.loadAsync('model.glb');
  scene.add(gltf.scene);
} catch (error) {
  console.error('Failed to load model:', error);
}

GLTF 结果对象

{
  scene: THREE.Group,                    // Root scene node -- add this to your scene
  scenes: THREE.Group[],                 // All scenes in the file
  cameras: THREE.Camera[],              // Embedded cameras
  animations: THREE.AnimationClip[],    // Animation data for AnimationMixer
  asset: { generator: string, version: string },  // File metadata
  parser: GLTFParser,                    // Internal parser (advanced use)
  userData: {}                           // Custom glTF extensions
}

GLTFLoader 方法

方法	签名	用途
load	(url, onLoad, onProgress, onError)	使用回调加载
loadAsync	(url, onProgress) => Promise<GLTF>	使用 Promise 加载
parse	(data, path, onLoad, onError)	直接解析 ArrayBuffer 或 JSON
setDRACOLoader	(dracoLoader: DRACOLoader)	启用 Draco 解压
setKTX2Loader	(ktx2Loader: KTX2Loader)	启用 KTX2 纹理解压
setMeshoptDecoder	(decoder)	启用 meshopt 解压
register	(plugin)	注册 glTF 扩展插件
unregister	(plugin)	注销 glTF 扩展插件

---

DRACOLoader

解码 Draco 压缩的几何体。可将网格文件大小减少 80-90%。

方法	签名	用途
setDecoderPath	(path: string)	包含 WASM 解码器的目录路径
setDecoderConfig	(config: object)	{ type: 'js' | 'wasm' } —— WASM 为默认选项，速度更快
preload	()	首次使用前预取解码器 WASM
dispose	()	释放 WASM 解码器内存

务必在加载完所有 Draco 压缩模型后调用 dracoLoader.dispose()。

---

TextureLoader

将 2D 纹理（PNG、JPG、WebP）加载到 THREE.Texture 中。

const loader = new THREE.TextureLoader();
const texture = await loader.loadAsync('diffuse.jpg');
texture.colorSpace = THREE.SRGBColorSpace; // ALWAYS for color textures
texture.wrapS = THREE.RepeatWrapping;
texture.wrapT = THREE.RepeatWrapping;
material.map = texture;

---

CubeTextureLoader

将六张图像加载为立方体贴图，用于天空盒或环境反射。

const cubeLoader = new THREE.CubeTextureLoader();
cubeLoader.setPath('/textures/cube/');
const cubeTexture = cubeLoader.load([
  'px.jpg', 'nx.jpg',  // positive-x, negative-x
  'py.jpg', 'ny.jpg',  // positive-y, negative-y
  'pz.jpg', 'nz.jpg'   // positive-z, negative-z
]);
scene.background = cubeTexture;
scene.environment = cubeTexture;

---

RGBELoader

加载 Radiance .hdr 格式的 HDR 环境贴图。

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

const rgbeLoader = new RGBELoader();
rgbeLoader.load('environment.hdr', (texture) => {
  texture.mapping = THREE.EquirectangularReflectionMapping;
  scene.environment = texture; // PBR environment lighting
  scene.background = texture;  // Optional: visible HDR background
});

RGBELoader 会自动设置色彩空间。切勿手动覆盖 HDR 纹理的色彩空间。

---

FBXLoader

加载 Autodesk FBX 模型。支持网格、材质和骨骼动画。

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

const fbxLoader = new FBXLoader();
const model = await fbxLoader.loadAsync('character.fbx');
scene.add(model);

---

OBJLoader + MTLLoader

加载 Wavefront OBJ 几何体，可选使用 MTL 材质文件。

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

const mtlLoader = new MTLLoader();
const materials = await mtlLoader.loadAsync('model.mtl');
materials.preload();

const objLoader = new OBJLoader();
objLoader.setMaterials(materials);
const model = await objLoader.loadAsync('model.obj');
scene.add(model);

务必先加载 MTL 文件，然后在加载 OBJ 文件前将材质传递给 OBJLoader。

---

释放已加载的模型

移除已加载的模型时，务必遍历并释放所有资源：

function disposeModel(model) {
  model.traverse((child) => {
    if (child.isMesh) {
      child.geometry.dispose();
      if (Array.isArray(child.material)) {
        child.material.forEach((mat) => {
          disposeMaterial(mat);
        });
      } else {
        disposeMaterial(child.material);
      }
    }
  });
  model.removeFromParent();
}

function disposeMaterial(material) {
  for (const key of Object.keys(material)) {
    const value = material[key];
    if (value && typeof value === 'object' && 'dispose' in value) {
      value.dispose(); // Disposes textures
    }
  }
  material.dispose();
}

---

参考链接

• references/methods.md —— 所有加载器的完整 API 签名
• references/examples.md —— 常见加载场景的可运行代码示例
• references/anti-patterns.md —— 加载资源时的错误做法

官方来源

• https://threejs.org/docs/#api/en/loaders/Loader
• https://threejs.org/docs/#api/en/loaders/LoadingManager
• https://threejs.org/docs/#api/en/loaders/TextureLoader
• https://threejs.org/docs/#examples/en/loaders/GLTFLoader
• https://threejs.org/docs/#examples/en/loaders/DRACOLoader
• https://threejs.org/docs/#examples/en/loaders/KTX2Loader
• https://threejs.org/docs/#examples/en/loaders/FBXLoader
• https://threejs.org/docs/#examples/en/loaders/OBJLoader
• https://threejs.org/docs/#examples/en/loaders/RGBELoader