---

name: threejs-loaders description: Three.js 资源加载——GLTF、纹理、图片、模型、异步模式。在加载 3D 模型、纹理、HDR 环境或管理加载进度时使用。 risk: unknown source: community

Three.js 加载器

何时使用

• 你需要在 Three.js 中加载模型、纹理、HDR 资源或其他外部资源。
• 任务涉及 GLTFLoader、TextureLoader、加载进度或异步资源编排。
• 你在管理场景资源而非直接编写几何体或着色器。

快速开始

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

// Load GLTF model
const loader = new GLTFLoader();
loader.load("model.glb", (gltf) => {
  scene.add(gltf.scene);
});

// Load texture
const textureLoader = new THREE.TextureLoader();
const texture = textureLoader.load("texture.jpg");

LoadingManager

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

const manager = new THREE.LoadingManager();

// Callbacks
manager.onStart = (url, loaded, total) => {
  console.log(`Started loading: ${url}`);
};

manager.onLoad = () => {
  console.log("All assets loaded!");
  startGame();
};

manager.onProgress = (url, loaded, total) => {
  const progress = (loaded / total) * 100;
  console.log(`Loading: ${progress.toFixed(1)}%`);
  updateProgressBar(progress);
};

manager.onError = (url) => {
  console.error(`Error loading: ${url}`);
};

// Use manager with loaders
const textureLoader = new THREE.TextureLoader(manager);
const gltfLoader = new GLTFLoader(manager);

// Load assets
textureLoader.load("texture1.jpg");
textureLoader.load("texture2.jpg");
gltfLoader.load("model.glb");
// onLoad fires when ALL are complete

纹理加载

TextureLoader

const loader = new THREE.TextureLoader();

// Callback style
loader.load(
  "texture.jpg",
  (texture) => {
    // onLoad
    material.map = texture;
    material.needsUpdate = true;
  },
  undefined, // onProgress - not supported for image loading
  (error) => {
    // onError
    console.error("Error loading texture", error);
  },
);

// Synchronous (returns texture, loads async)
const texture = loader.load("texture.jpg");
material.map = texture;

纹理配置

const texture = loader.load("texture.jpg", (tex) => {
  // Color space (important for color accuracy)
  tex.colorSpace = THREE.SRGBColorSpace; // For color/albedo maps
  // tex.colorSpace = THREE.LinearSRGBColorSpace;  // For data maps (normal, roughness)

  // Wrapping
  tex.wrapS = THREE.RepeatWrapping;
  tex.wrapT = THREE.RepeatWrapping;
  // ClampToEdgeWrapping, RepeatWrapping, MirroredRepeatWrapping

  // Repeat/offset
  tex.repeat.set(2, 2);
  tex.offset.set(0.5, 0.5);
  tex.rotation = Math.PI / 4;
  tex.center.set(0.5, 0.5);

  // Filtering
  tex.minFilter = THREE.LinearMipmapLinearFilter; // Default
  tex.magFilter = THREE.LinearFilter; // Default
  // NearestFilter - pixelated
  // LinearFilter - smooth
  // LinearMipmapLinearFilter - smooth with mipmaps

  // Anisotropic filtering (sharper at angles)
  tex.anisotropy = renderer.capabilities.getMaxAnisotropy();

  // Flip Y (usually true for standard textures)
  tex.flipY = true;

  tex.needsUpdate = true;
});

CubeTextureLoader

用于环境贴图和天空盒。

const loader = new THREE.CubeTextureLoader();

// Load 6 faces
const cubeTexture = loader.load([
  "px.jpg", "nx.jpg",
  "py.jpg", "ny.jpg",
  "pz.jpg", "nz.jpg"
]);

scene.background = cubeTexture;
scene.environment = cubeTexture;

GLTF 加载

GLTFLoader

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

// Optional: Draco compression support
const dracoLoader = new DRACOLoader();
dracoLoader.setDecoderPath("/draco/");

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

loader.load("model.glb", (gltf) => {
  const model = gltf.scene;
  scene.add(model);

  // Access animations
  const mixer = new THREE.AnimationMixer(model);
  gltf.animations.forEach((clip) => {
    mixer.clipAction(clip).play();
  });

  // Access specific objects
  const mesh = model.getObjectByName("MyMesh");
});

异步/Promise 模式

// Using loadAsync (returns Promise)
const gltf = await new GLTFLoader().loadAsync("model.glb");
scene.add(gltf.scene);

// Parallel loading
const [model, texture, hdr] = await Promise.all([
  new GLTFLoader().loadAsync("model.glb"),
  new THREE.TextureLoader().loadAsync("texture.jpg"),
  new RGBELoader().loadAsync("environment.hdr")
]);

最佳实践

• 使用 LoadingManager 协调多个资源的加载进度
• 对 GLTF 模型使用 Draco 压缩减小文件大小
• 使用 loadAsync 和 Promise.all 并行加载资源
• 为纹理设置正确的 colorSpace（颜色贴图用 sRGB，数据贴图用 Linear）
• 使用各向异性过滤提高倾斜角度的纹理清晰度
• 加载完成后释放不需要的资源（texture.dispose()）