three.js ImageLoader 图片加载器完全指南：API、缓存机制与纹理管线实践

图片是 three.js 场景中最基础、最高频的异步资源类型——无论是 MeshBasicMaterial 的贴图、CubeTexture 的环境映射，还是粒子系统的 Sprite 纹理，最终都要经历「加载图片数据 → 交由 GPU 上传」的过程。THREE.ImageLoader 正是承载这一入口的专用加载器：它以浏览器原生 HTML Image API 为底层，封装了 URL 解析、CORS 处理、跨加载器缓存与失败回调等完整逻辑。阅读完本文，你将掌握 ImageLoader 的构造函数与全部方法签名、它与 Loader/LoadingManager/Cache 的协作原理、图片缓存与并发去重的实现细节，以及如何通过 TextureLoader 将图片无缝接入材质渲染管线。

ImageLoader 定位：基于 HTML Image API 的图片加载器

从文档定义可以明确 ImageLoader 的性质：它并不使用 fetch 或 XMLHttpRequest，而是直接依赖浏览器内置的 Image 对象（即 HTML <img> 元素）来完成解码。对应源码位于 src/loaders/ImageLoader.js，其类声明如下：

import { Cache } from './Cache.js';
import { Loader } from './Loader.js';
import { createElementNS } from '../utils.js';

class ImageLoader extends Loader {
	constructor( manager ) {
		super( manager );
	}
	// ...
}

两个值得注意的设计细节：

1. 构造函数只做一件事——透传 manager 给父类 Loader。ImageLoader 本身没有额外初始化逻辑，它继承自 src/loaders/Loader.js 中定义的抽象基类 Loader，因此天然具备 manager、path、crossOrigin、resourcePath、requestHeader 等属性和对应的链式 setter 方法。
2. 内部图片元素通过 createElementNS 创建（见 src/utils.js），它调用 document.createElementNS( 'http://www.w3.org/1999/xhtml', 'img' ) 显式命名空间创建 <img> 节点，而非简写形式的 new Image()，以保证在 SVG 等不同 XML 命名空间上下文中的行为一致性。加载完成后，该 Image 对象可直接被 Texture 使用。

兼容性提醒（自 r84 起）：官方文档与源码注释均明确指出，ImageLoader 自 r84 起已不再支持 onProgress 进度事件。如需带进度反馈的图片加载器，需自行封装（官方 issue 讨论中提供了带进度事件的实现思路），标准版请以本文介绍的回调模型为准。

快速上手：两种加载写法

ImageLoader 的用法与 three.js 所有加载器保持一致，核心代码示例（源自官方文档）如下：

const loader = new THREE.ImageLoader();

// 写法一：Promise 风格（推荐）
const image = await loader.loadAsync( 'image.png' );

// 写法二：回调风格
const image = loader.load(
	'image.png',
	function ( img ) { /* 加载完成，img 即 HTMLImageElement */ },
	undefined,          // onProgress 不支持，传 undefined 占位
	function ( err ) { /* 加载出错 */ }
);

loadAsync( url ) 是由 Loader.js 提供的通用异步包装：它返回一个 Promise，内部把 resolve 作为 onLoad、reject 作为 onError 传入 load()，因此你可以配合 async/await 编写线性、易读的加载流程，也便于与 Promise.all 组合并发加载多张图片。

Constructor：构造函数参数详解

new ImageLoader( manager : LoadingManager )

构造一个新的图片加载器。参数如下：

参数	类型	说明
manager	LoadingManager	加载管理器。可选参数，省略时自动使用全局单例 DefaultLoadingManager。

父类 Loader 构造函数中有一段容易被忽略的关键逻辑（src/loaders/Loader.js）：

this.manager = ( manager !== undefined ) ? manager : DefaultLoadingManager;
this.crossOrigin = 'anonymous';
this.withCredentials = false;
this.path = '';
this.resourcePath = '';
this.requestHeader = {};

即 ImageLoader 实例默认具备：

• crossOrigin = 'anonymous'——CORS 模式下以匿名身份请求跨域图片；
• path = ''——基础路径，可为空，用于拼接相对资源地址。

传入自定义 LoadingManager 的典型场景是「对象模型与贴图使用不同的加载进度统计」。例如（参照 LoadingManager.js 的类注释）：

const textureManager = new THREE.LoadingManager();
textureManager.onLoad = () => console.log( '所有贴图加载完成!' );

const loader = new THREE.ImageLoader( textureManager );

核心方法：.load() 深入剖析

.load( url, onLoad, onProgress, onError ) : Image

这是 ImageLoader 唯一自己实现的公共方法（src/loaders/ImageLoader.js）。它从指定 URL 开始加载，把解码完成的图片传给 onLoad 回调，同时同步返回一个新的 Image 对象——你可以在图片尚未加载完成时就把它交给纹理系统，当加载完成后纹理会在场景中「突然出现」，这正是文档描述的「texture may pop up in your scene」现象。

参数说明如下：

参数	类型	说明
url	string	要加载的文件路径/URL，也支持 data: URI。会先拼接 loader.path，再经过 manager.resolveURL() 归一化处理。
onLoad	function(Image)	加载成功完成后执行，参数为解码好的 Image 对象。
onProgress	onProgressCallback	本加载器不支持（r84 起移除），直接忽略即可。
onError	onErrorCallback	加载出错时执行，参数为错误事件对象。

返回类型：Image（即 HTMLImageElement）。

方法整体遵循回调契约，重写（Override）自 Loader#load。值得注意的是它没有调用 super.load()，而是完全自定义了实现——这与大多数基于 FileLoader 的三维模型加载器（如 GLTFLoader）有本质区别：ImageLoader 不走 XHR/fetch 通道，也就无法携带自定义请求头（requestHeader 对 ImageLoader 不生效）。

内部实现逐段拆解

load( url, onLoad, onProgress, onError ) {
	if ( this.path !== undefined ) url = this.path + url;   // ① 拼接基础路径
	url = this.manager.resolveURL( url );                    // ② URL 归一化（NFC + urlModifier）
	const scope = this;
	const cached = Cache.get( `image:${url}` );              // ③ 查询图片缓存
	// ...
	const image = createElementNS( 'img' );                   // ④ 创建 <img>
	image.addEventListener( 'load', onImageLoad, false );
	image.addEventListener( 'error', onImageError, false );
	if ( url.slice( 0, 5 ) !== 'data:' ) {
		if ( this.crossOrigin !== undefined ) image.crossOrigin = this.crossOrigin;  // ⑤ CORS
	}
	Cache.add( `image:${url}`, image );                       // ⑥ 先入缓存再设 src
	scope.manager.itemStart( url );                           // ⑦ 通知 LoadingManager
	image.src = url;                                          // ⑧ 触发真正的网络请求
	return image;
}

各步要点：

• ① 路径拼接：loader.setPath( basePath ) 设置的路径会在此前置拼接到 URL 前；
• ② URL 归一化：调用 LoadingManager.resolveURL，内部先执行 url.normalize('NFC') 处理 Unicode URI 的 RFC 3987 百分号编码，再交由 setURLModifier 注册的变换回调处理（见 LoadingManager.js）——这使图片也可以来自 blob: URL 或拖拽/解压等自定义数据源；
• ③⑥ 缓存读写：缓存键统一为 `image:${url}` 前缀格式；
• ④ 事件挂载：先绑定 load/error 监听器，再设置 src，避免漏掉同步完成的事件（缓存命中时使用 setTimeout(..., 0) 异步派发，见下文）；
• ⑤ CORS 处理：仅对非 data: URI 设置 crossOrigin——data: URI 同源，无需也不应携带 CORS 属性；默认值 anonymous 来自父类 Loader，可由 loader.setCrossOrigin() 覆盖；
• ⑦ LoadingManager 生命周期：itemStart/itemEnd 会更新管理器内部的已加载计数 itemsLoaded 与总数 itemsTotal，用于触发 onStart/onProgress/onLoad 全局回调。

错误处理路径

当 error 事件触发时，源码执行了相当完整的清理工作（src/loaders/ImageLoader.js）：

function onImageError( event ) {
	removeEventListeners();
	if ( onError ) onError( event );            // ① 通知本次调用的调用方
	Cache.remove( `image:${url}` );             // ② 从缓存移除失败条目
	// ③ 逐一分发同批等待中的回调
	const callbacks = _loading.get( this ) || [];
	for ( let i = 0; i < callbacks.length; i ++ ) {
		if ( callbacks[ i ].onError ) callbacks[ i ].onError( event );
	}
	_loading.delete( this );
	scope.manager.itemError( url );             // ④ 触发 LoadingManager.onError
	scope.manager.itemEnd( url );
}

失败图片会立即从缓存中清除，保证下次 load() 同 URL 会重新发起网络请求，而不是拿到坏缓存。

缓存机制：Cache 与并发请求去重（WeakMap 协作）

ImageLoader 的缓存行为完整依赖 src/loaders/Cache.js 中的静态 Cache 对象。Cache 默认 enabled = false，启用后以 files 字典保存条目，并提供 add/get/remove/clear 四个方法，且对 blob: URL 一律跳过缓存。

需要强调的是：Cache 默认关闭，需要应用主动开启：

THREE.Cache.enabled = true;   // 需在应用启动时开启一次，对所有使用该缓存的加载器全局生效

两个缓存分支

开启缓存后，若 Cache.get(`image:${url}`) 命中（src/loaders/ImageLoader.js），源码区分两种情况：

1. cached.complete === true：图片早已下载完成。此时仍调用 manager.itemStart(url) 记录一次加载事务，再用 setTimeout(..., 0) 异步触发 onLoad。这种设计保证回调不会同步执行、卡住调用栈，同时 LoadingManager 的计数不会因完全命中缓存而失衡。
2. 图片仍在加载中（complete 为假）：说明存在对同一 URL 的并发请求。此时通过模块级 WeakMap（const _loading = new WeakMap()）以正在加载的 Image 对象为键，把后续请求的 { onLoad, onError } 回调追加到一个等待数组中，而非再次发起网络请求。这样，当首个请求完成时，onImageLoad 会遍历并逐个派发所有等待中的回调（src/loaders/ImageLoader.js）：

function onImageLoad() {
	removeEventListeners();
	if ( onLoad ) onLoad( this );
	const callbacks = _loading.get( this ) || [];
	for ( let i = 0; i < callbacks.length; i ++ ) {
		if ( callback.onLoad ) callback.onLoad( this );
	}
	_loading.delete( this );
	scope.manager.itemEnd( url );
}

可见 ImageLoader 具备**请求合并（request coalescing）**能力：多个加载器同时请求同一张图片时，底层只发生一次网络请求，其余调用方共享结果——这对「一个 glTF 模型内多处引用同一贴图」的场景尤为有用，且错误与成功路径都会完整广播到所有等待者。

与父类 Loader 的关系：可链式调用的配置 API

ImageLoader 继承自 Loader.js 中抽象的 Loader，除 manager 之外还继承了整套链式 setter 与默认属性。以下配置项对 ImageLoader 均直接有效，推荐采用链式写法：

const loader = new THREE.ImageLoader()
	.setPath( 'textures/' )            // 设置资源基础路径
	.setCrossOrigin( 'anonymous' );    // 覆盖默认的 CORS 模式

// 等价写法：
// loader.path = 'textures/';
// loader.crossOrigin = 'anonymous';

方法	对应属性	默认值	说明
setPath( path )	path	''	基础路径，拼接在 load(url) 的 url 之前，用于集中管理资源根目录
setCrossOrigin( value )	crossOrigin	'anonymous'	CORS 模式字符串；仅在非 data: URL 上生效
setResourcePath( url )	resourcePath	''	依赖资源基础路径（本例中不直接使用）
setRequestHeader( obj )	requestHeader	{}	注意：ImageLoader 走 HTML Image 通道而非 XHR，自定义请求头不生效
setWithCredentials( bool )	withCredentials	false	同上，对 ImageLoader 无实际效果

其中 path 与 crossOrigin 是 ImageLoader 最常用的两个配置。TextureLoader 在内部创建 ImageLoader 时就会透传这两个值（见下文）。

真实场景：TextureLoader 如何调用 ImageLoader

文档虽聚焦 ImageLoader 本身，但它的最典型应用是作为 TextureLoader 的底层图片获取器（见 src/loaders/TextureLoader.js）：

load( url, onLoad, onProgress, onError ) {
	const texture = new Texture();
	const loader = new ImageLoader( this.manager );
	loader.setCrossOrigin( this.crossOrigin );   // 透传 CORS 配置
	loader.setPath( this.path );                 // 透传基础路径
	loader.load( url, function ( image ) {
		texture.image = image;                   // 把 HTMLImageElement 赋给纹理
		texture.needsUpdate = true;              // 通知渲染器需要重新上传 GPU
		if ( onLoad !== undefined ) onLoad( texture );
	}, onProgress, onError );
	return texture;
}

它演示了完整的接线方式：Texture 的 .image 属性就是 ImageLoader 返回的 HTMLImageElement。加载完成回调里把图片赋给 texture.image 并置 needsUpdate = true，渲染器便会在下一帧把图像数据上传至 GPU。这也解释了本文最开头的标准用法：

const texture = await new THREE.TextureLoader().loadAsync( 'textures/land_ocean_ice_cloud_2048.jpg' );
const material = new THREE.MeshBasicMaterial( { map: texture } );

进阶用户也可自行把裸 ImageLoader 产出的图片喂给 CubeTexture、CanvasTexture 等其他纹理类型，从而绕开 TextureLoader 的固定流程。

用图片素材直接创作纹理（进阶用法）

由于 ImageLoader 返回的是标准 HTMLImageElement，你也可以完全掌控加载生命周期，例如在 HUD 或 UI 场景中把图片绘制到 2D canvas 再生成纹理，甚至先用 createImageBitmap 解码再上传。而一旦拥有图片引用，最简单的方式是直接构造纹理：

const loader = new THREE.ImageLoader();
const img = await loader.loadAsync( 'sprite.png' );

// 直接把图片对象交给纹理系统
const texture = new THREE.Texture( img );
texture.needsUpdate = true;

// 之后即可创建 sprite 或材质
const material = new THREE.SpriteMaterial( { map: texture } );
const sprite = new THREE.Sprite( material );

结合前文的 CORS 规则，加载跨域 CDN 图片时需要保证服务端返回 Access-Control-Allow-Origin 头，且加载器使用默认的 'anonymous' 模式——否则图片虽可显示，但会因被浏览器标记为「被污染」而无法用于 WebGLTexture 上传或像素读取。

实践要点与边界条件

综合文档与源码，实际项目中的关键经验总结如下：

1. 进度回调不可用：load() 的第三个参数 onProgress 自 r84 起被移除，请勿依赖；需要进度时考虑 CDN 侧或自行基于 XHR 封装带进度的版本。
2. 缓存需显式开启：THREE.Cache.enabled = true 生效后，缓存键以 image: 为前缀（即 Cache.get(`image:${url}`)），同 URL 请求自动去重合并；失败条目会被清除以便重试。
3. data: URI 特判：crossOrigin 只在非 data: 前缀时写入 <img> 属性（src/loaders/ImageLoader.js），因此用 data URI 内联小图不会引发 CORS 问题。
4. 请求头等 XHR 特性不适用：ImageLoader 基于 HTML Image，requestHeader、withCredentials 等与 XHR 相关的设置对它没有效果，请改用支持这些配置的加载路径。
5. 图片缓存与几何资源共用：Cache 是全局静态对象（src/loaders/Cache.js），图片条目以 image: 前缀与其他资源隔离，互不冲突。
6. 单元测试基线：仓库测试 test/unit/src/loaders/ImageLoader.tests.js 验证了 ImageLoader 的实例化能力及其对 Loader 的继承关系，可作为自行扩展时保持行为一致性的参照。

总结

ImageLoader 是 three.js 中唯一直接操作 HTML Image API 的专用图片加载器：它继承 Loader 获得 manager、path、crossOrigin 等可链式配置能力，通过 load() 完成「路径拼接 → URL 归一化 → 缓存查询 → 事件绑定 → CORS 写入 → 入缓存 → 通知管理器 → 设置 src」的完整异步流程，并提供基于 Cache + WeakMap 的同 URL 并发合并机制。理解它的实现，你便掌握了 three.js 贴图资源从「URL 到 HTMLImageElement 再到 Texture」的第一公里——无论是直接使用、配合 TextureLoader，还是为加载失败与缓存策略做精细控制，都能做到心中有数。