PIXI.js 7 + Webpack加载大量资源包时Asset类加载停滞问题

核心问题表现 #

• 调用PIXI.Asset.init初始化资源清单后，资源可正常写入缓存，但loadBundle返回的Promise始终不resolve，无报错、进度回调停止触发
• 加载14个资源包（含约110个不同尺寸图集）时必现停滞；单包仅含5个资源时加载正常；即使将单包资源数降至3个，问题仍存在
• 旧版PIXI加载器可正常处理同量级资源

可能原因与解决思路 #

1. 并发加载阈值冲突 #

PIXI.js Asset类默认有并发加载上限，大量资源同时发起请求可能触发浏览器或加载器内部队列阻塞：

• 手动调整并发数：通过setLoaderOptions降低并行请求数量，避免队列溢出

  PIXI.Asset.setLoaderOptions({ maxParallel: 8 });
  

2. 图集解析隐性异常 #

Texture Packer生成的JSON图集可能存在格式细节问题（如重复资源key、异常尺寸值），大量解析时触发无报错的阻塞：

• 逐个验证资源包：单独加载每个包，定位是否有特定图集导致卡停
• 全局捕获加载错误：添加错误监听，捕获Asset内部未抛出的异常

  PIXI.Asset.on('error', (err) => {
    console.error('Asset加载/解析错误:', err);
  });
  

3. Webpack打包路径歧义 #

自研引擎搭配Webpack时，资源路径可能被打包规则篡改，导致Asset虽能找到资源，但解析时存在隐性依赖未完成：

• 检查Webpack资源模块配置：确保asset-modules或file-loader正确映射图集JSON与纹理图片的相对路径
• 统一资源基础路径：在Asset.init时指定basePath参数，避免路径解析混乱

  PIXI.Asset.init({
    basePath: '/assets/',
    bundles: [...]
  });
  

4. 加载队列状态不一致 #

大量资源加载时，Asset内部缓存或队列可能出现状态异常，导致Promise无法触发resolve：

• 拆分加载批次：分批次调用loadBundle，前一批加载完成后再启动下一批

  const bundleList = ['bundle-1', 'bundle-2', ..., 'bundle-14'];
  async function batchLoad() {
    for (const bundle of bundleList) {
      await PIXI.Asset.loadBundle(bundle);
    }
  }
  

• 重置Asset状态：加载前调用PIXI.Asset.reset()清空缓存，避免旧状态干扰

社区已知情况 #

已有PIXI.js 7.x版本用户遇到同类问题，多数案例通过调整并发数、排查异常图集解决，核心是避免一次性触发超出加载器处理能力的资源请求量。

内容的提问来源于stack exchange，提问作者Tyro Kitsune