首页 / three.js / API 文档

TextureLoader

先看结论

二维贴图加载器。读取图片并返回 Texture，可直接赋给材质的 map、normalMap 等贴图槽。

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

new THREE.TextureLoader(manager)

构造参数

参数	说明
`manager`	可选的 `LoadingManager`，用于统一管理加载进度

方法

方法	返回	说明
`load(url, onLoad, onProgress, onError)`	Texture	立即返回贴图对象，图片到达后填充并回调
`loadAsync(url, onProgress)`	Promise<Texture>	加载完成后 resolve
`setCrossOrigin(value)`	this	设置跨域属性，默认 `'anonymous'`
`setPath(path)`	this	设置基础路径
`setRequestHeader(header)`	this	附加请求头
`setWithCredentials(value)`	this	是否携带凭据

示例

const loader = new THREE.TextureLoader();
loader.setCrossOrigin('anonymous');

// 回调方式
const colorMap = loader.load(
  '/textures/facade.jpg',
  function (texture) {
    texture.colorSpace = THREE.SRGBColorSpace;
    texture.anisotropy = renderer.capabilities.getMaxAnisotropy();
    console.log('贴图就绪', texture.image.width, texture.image.height);
  },
  undefined,
  function (error) {
    console.error('贴图加载失败', error);
  }
);

const material = new THREE.MeshStandardMaterial({
  map: colorMap,
  roughness: 0.7
});

// Promise 方式
const normalMap = await loader.loadAsync('/textures/facade-normal.jpg');
normalMap.wrapS = normalMap.wrapT = THREE.RepeatWrapping;
normalMap.repeat.set(4, 4);

颜色贴图要声明 sRGB

颜色贴图（map、emissiveMap）保存的是 sRGB 数据，需要把 colorSpace 设为 THREE.SRGBColorSpace，否则渲染结果整体偏暗。法线贴图、粗糙度贴图、AO 贴图属于数据贴图，保持默认的线性空间，不要改。

加载是异步的

load 同步返回的是空贴图，图片到达前渲染会使用 1x1 占位像素。首帧出现纯色材质属于正常现象。需要等资源齐备再渲染时，用 LoadingManager.onLoad 或 loadAsync。跨域未授权会直接失败，控制台报 CORS 错误，材质保持占位色。

常见设置

属性	用途
`wrapS` / `wrapT`	平铺模式，重复贴图需设为 `RepeatWrapping`
`repeat`	平铺次数，配合 `RepeatWrapping` 使用
`anisotropy`	各向异性过滤，斜视地面时显著改善清晰度
`minFilter` / `magFilter`	缩放过滤方式，像素风贴图用 `NearestFilter`
`flipY`	默认 true，从数据生成的贴图通常要改为 false

贴图尺寸尽量取 2 的幂。非 2 的幂贴图在部分设备上无法使用重复平铺与 mipmap，three.js 会退化为裁剪或拉伸。 512、1024、2048 这类尺寸最稳妥。

引用本文

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