pixijs-assets

Assets API 是 PixiJS 的资源加载器、解析器和缓存，集于一个单例中。使用它加载纹理、视频、精灵表、字体、JSON 和其他资源，并支持格式检测、分辨率切换、资源包分组、进度跟踪和 GPU 清理。

快速开始

await Assets.init({ basePath: "/static/" });

const texture = await Assets.load("bunny.png");
const sprite = new Sprite(texture);
app.stage.addChild(sprite);

const [hero, enemy] = await Assets.load(["hero.png", "enemy.png"]);

await Assets.load({
  alias: "logo",
  src: "logo.webp",
});

const logo = new Sprite(Assets.get("logo"));

Assets.init() 是可选的，但建议用于设置 basePath、texturePreference 或清单。初始化后，调用 Assets.load() 并传入 URL、别名、数组或 UnresolvedAsset；解析后的资源会被缓存，并由 Assets.get() 重新解析。

支持的文件类型

类型	扩展名	解析器 ID	加载器
纹理	.png、.jpg、.jpeg、.webp、.avif	texture	loadTextures
SVG	.svg	svg	loadSvg（参见 references/svg.md）
视频纹理	.mp4、.m4v、.webm、.ogg、.ogv、.h264、.avi、.mov	video	loadVideoTextures（参见 references/video.md）
精灵表	.json（Spritesheet 格式）	spritesheet	spritesheetAsset（参见 references/spritesheet.md）
位图字体	.fnt、.xml	bitmap-font	loadBitmapFont（默认可加载；渲染 BitmapText 需要 'pixi.js/text-bitmap'；参见 references/fonts.md）
Web 字体	.ttf、.otf、.woff、.woff2	web-font	loadWebFont（参见 references/fonts.md）
JSON	.json	json	loadJson
文本	.txt	text	loadTxt
压缩纹理	.basis、.dds、.ktx、.ktx2	basis、dds、ktx、ktx2	参见 references/compressed-textures.md
动态 GIF	.gif	gif	需要 'pixi.js/gif'；返回 GifSource（参见 references/gif.md）

解析器 ID 列的值可传给资源描述符顶层的 parser 字段，以指定特定加载器。参见下文“强制指定解析器”。

使用 parser 强制指定解析器

默认情况下，PixiJS 会根据文件扩展名或 MIME 类型选择加载器。当 URL 不含扩展名（CDN 签名 URL、blob URL、API 端点、内容哈希路径）时，解析器无法判断该使用哪个加载器。在资源描述符的顶层设置 parser 字段，即可强制指定特定加载器：

// Signed CDN URL with no extension
const texture = await Assets.load({
  src: "https://cdn.example.com/signed/abc123?token=xyz",
  parser: "texture",
});

// API endpoint that returns JSON
const data = await Assets.load({
  alias: "config",
  src: "https://api.example.com/v1/config",
  parser: "json",
});

// Extension-less font URL with explicit family
await Assets.load({
  src: "https://cdn.example.com/fonts/hero-v2",
  parser: "web-font",
  data: { family: "Hero", weights: ["400", "700"] },
});

// Video stream without a file extension
const clipTexture = await Assets.load({
  src: "https://cdn.example.com/stream/xyz",
  parser: "video",
  data: { mime: "video/mp4", muted: true, playsinline: true },
});

parser 字段位于资源描述符的顶层（与 src 和 data 同级），而不是 data 内部。它可以使用上方“支持的文件类型”表格中的任意解析器 ID：

• 'texture'、'svg'、'video'：图像、SVG 和视频纹理
• 'json'、'text'：JSON 和纯文本
• 'web-font'、'bitmap-font'：Web 字体和位图字体
• 'spritesheet'：纹理图集 JSON
• 'gif'：动画 GIF（需要 'pixi.js/gif'）
• 'basis'、'dds'、'ktx'、'ktx2'：压缩纹理（每种格式都需要导入其副作用模块）

何时需要使用

• CDN 签名 URL：https://cdn.example.com/get?id=abc123 没有可供加载器检测的扩展名。
• Blob 或 ObjectURL：URL.createObjectURL(blob) 会生成不含扩展名的 blob:... URL。
• 自定义路由：/api/assets/hero-v2，由服务器决定内容类型。
• 不带后缀的内容哈希路径：有些构建流水线会生成 /static/abc123def 这样的名称，而不是 /static/abc123def.png。

如果 URL 确实 带有扩展名，就不需要 parser；让自动检测正常工作即可。仅在无法检测时设置 parser。

loadParser 已弃用

v7 的 loadParser 字段仍可使用，但会发出弃用警告。新代码请使用 parser。

// Old (deprecated)
await Assets.load({ src: "...", loadParser: "loadTextures" });

// New
await Assets.load({ src: "...", parser: "texture" });

主题

每种资源工作流都在相应的参考文件中有说明。请根据问题选择对应文件：

主题	参考资料	适用场景
纹理图集和动画	references/spritesheet.md	使用 AnimatedSprite 加载精灵图
视频纹理	references/video.md	.mp4、.webm、自动播放、循环播放、移动端
Web 字体和位图字体	references/fonts.md	.woff2、.fnt、字体系列、SDF 字体
动画 GIF	references/gif.md	.gif、GifSprite、播放控制
按功能对资源分组	references/bundles.md	addBundle、loadBundle、unloadBundle
预先声明所有内容	references/manifests.md	Assets.init({ manifest }) 工作流
缓存查找与清理	references/caching.md	Assets.get、Assets.unload、Cache
预加载后续资源	references/background.md	backgroundLoad、backgroundLoadBundle
加载界面	references/progress.md	onProgress、LoadOptions 进度
GPU 压缩格式	references/compressed-textures.md	.ktx2、.basis、.dds、.ktx
矢量 SVG 与栅格 SVG	references/svg.md	parseAsGraphicsContext、纹理模式
Retina 和格式检测	references/resolution.md	@{1,2}x、format 偏好

决策指南

• 需要加载单张图片？ 使用 Assets.load(url)。无需任何设置。
• 需要按关卡／场景分组加载多个资源？ 使用资源包。请参阅 references/bundles.md。
• 构建时已知所有资源？ 在 Assets.init 中使用清单。请参阅 references/manifests.md。
• 需要加载进度条？ 将进度回调传给 Assets.load。请参阅 references/progress.md。
• 需要在关卡之间平滑过渡？ 在后台加载下一关。请参阅 references/background.md。
• 内存预算很重要？ 使用压缩纹理，并在切换屏幕时调用 Assets.unload。请参阅 references/compressed-textures.md 和 references/caching.md。
• 需要任意尺寸下都清晰的 SVG 图标？ 将其作为 Graphics 而非纹理加载。请参阅 references/svg.md。
• 需要 Retina + WebP/AVIF？ 配置 texturePreference 并使用格式模式。请参阅 references/resolution.md。

加载选项与错误处理

加载资源时，有两种不同的“选项”概念：

1. LoadOptions：Assets.load/loadBundle 的第二个参数。控制整个加载过程中的错误恢复、重试、进度和完成回调。
2. data：每个资源描述符上的一个字段。将解析器专属选项（缩放模式、分辨率、字体系列、自动播放标记等）转发给该资源对应的加载器。

LoadOptions（每次调用）

await Assets.load(["hero.png", "enemy.png"], {
  onProgress: (p) => updateBar(p),
  onError: (err, url) => {
    const src = typeof url === "string" ? url : url.src;
    console.warn("failed:", src, err);
  },
  strategy: "retry",
  retryCount: 3,
  retryDelay: 250,
});

• onProgress(progress)：随着本次调用中的资源完成，进度值在 [0, 1] 之间。
• onError(error, url)：url 的类型为 string | ResolvedAsset。读取 .src 前请先进行类型检查；当 url 为字符串时，.src 为 undefined。
• strategy: 'throw' | 'skip' | 'retry' — 默认值为 'throw'。'skip' 会在部分资源加载成功时返回这些资源；'retry' 会重新尝试加载失败的资源。
• retryCount — 默认值为 3，当 strategy 为 'retry' 时，每个资源的重试次数。
• retryDelay — 重试之间的默认间隔为 250 ms。

全局默认值设置在 Loader.defaultOptions 上，也可以将 loadOptions 传给 Assets.init()。

data 选项（每个资源）

每个加载器的解析器都会从资源描述符的 data 字段读取自身选项。请使用下表为每种资源类型选择合适的选项：

资源类型	data 形状	关键选项	参考文档
纹理（图像）	TextureSourceOptions	resolution、scaleMode、alphaMode、autoGenerateMipmaps、antialias、addressMode	references/resolution.md
SVG	{ parseAsGraphicsContext?, resolution? }	Graphics 模式使用 parseAsGraphicsContext；使用 resolution 获得更清晰的栅格图像	references/svg.md
视频	VideoSourceOptions	autoPlay、loop、muted、playsinline、preload、updateFPS、crossorigin、mime	references/video.md
Web 字体	LoadFontData	family、weights、style、display、unicodeRange、featureSettings	references/fonts.md
位图字体	（无；自动配置）	距离场检测会设置缩放模式和 mipmap	references/fonts.md
精灵图集	{ texture?, imageFilename?, ignoreMultiPack?, textureOptions?, cachePrefix? }	textureOptions 会将 TextureSourceOptions（例如 scaleMode）传递给图集图像；使用 texture 跳过图像加载；使用 imageFilename 覆盖所引用的图像；使用 ignoreMultiPack 跳过后续的多图集加载；使用 cachePrefix 为帧设置命名空间	references/spritesheet.md
GIF	GifBufferOptions	fps、scaleMode、resolution、autoGenerateMipmaps	references/gif.md
压缩纹理	TextureSourceOptions	scaleMode、addressMode、autoGenerateMipmaps	references/compressed-textures.md
JSON / 文本	（无）	按原样返回	—
结合 LoadOptions 和 data 的示例：

await Assets.load(
  {
    alias: "hero",
    src: "hero.png",
    data: { scaleMode: "nearest", resolution: 2 },
  },
  { strategy: "retry", retryCount: 3 },
);

在清单或资源包中，每个条目都可以携带自己的 data：

await Assets.init({
  manifest: {
    bundles: [
      {
        name: "level1",
        assets: [
          { alias: "tiles", src: "tiles.png", data: { scaleMode: "nearest" } },
          { alias: "font", src: "hero.woff2", data: { family: "Hero" } },
          {
            alias: "clip",
            src: "intro.mp4",
            data: { autoPlay: false, muted: true },
          },
        ],
      },
    ],
  },
});

运行时配置

Assets.init(options) 除了接受 basePath 和 manifest，还接受：

• defaultSearchParams — 字符串或 Record<string, any>，会追加到每个解析后的 URL。适用于缓存破坏。
• skipDetections: boolean — 跳过浏览器格式检测，以加快初始化。需要显式设置 texturePreference.format。
• bundleIdentifier: BundleIdentifierOptions — 自定义资源包键的解析方式，使同一别名可以存在于多个资源包中。
• loadOptions: Partial<LoadOptions> — 为后续每次 Assets.load 调用设置默认的 strategy、retryCount、retryDelay 和回调。
• preferences: Partial<AssetsPreferences> — crossOrigin、preferWorkers、preferCreateImageBitmap、parseAsGraphicsContext。

初始化后，仍可调整偏好设置：

Assets.setPreferences({
  crossOrigin: "anonymous",
  preferCreateImageBitmap: false,
});

for (const detection of Assets.detections) {
  console.log(detection.extension);
}

Assets.reset();

• Assets.setPreferences(preferences) — 将新的偏好设置推送给所有支持这些设置的解析器。
• Assets.detections — getter，公开已注册的 FormatDetectionParser 列表；检查当前环境声明支持哪些格式时可使用。
• Assets.reset() — 内部完整重置（解析器 + 加载器 + 缓存）。用于测试，以便运行全新的 Assets.init。

常见错误

[CRITICAL] 使用 Texture.from(url) 加载

错误：

const texture = Texture.from("https://example.com/image.png");

正确：

const texture = await Assets.load("https://example.com/image.png");

在 v8 中，Texture.from() 只会读取缓存，不会从 URL 获取内容。请先使用 Assets.load()；其返回值就是纹理本身。

[HIGH] 使用位置参数形式的 Assets.add

错误：

Assets.add("bunny", "bunny.png");

正确：

Assets.add({ alias: "bunny", src: "bunny.png" });

v8 已移除位置参数形式 Assets.add(key, url)。请使用包含 alias 和 src 属性的选项对象。

[HIGH] 切换关卡时不卸载纹理

Assets.load() 会无限期缓存纹理。对于关卡类游戏或资产集各不相同的屏幕，请在切换时调用 Assets.unloadBundle() 以释放 GPU 内存。

API 参考

• Assets
• Loader
• Resolver
• Cache
• LoadOptions
• AssetInitOptions
• AssetsManifest
• AssetsBundle
• BackgroundLoader
• Spritesheet