cocos-creator-bundle

Cocos Creator 分包与 AssetBundle

何时用

• 项目首屏加载慢、初始包体过大，需要按场景/功能拆分资源加载时。
• 使用远程资源服务器动态下发资源，需要管理 bundle 版本与缓存时。
• 多个 bundle 之间存在共用贴图、字体、音频等公共资源，担心重复打包导致体积膨胀时。
• 切换场景后内存异常偏高，怀疑已卸载的 bundle 资源仍驻留时。

核心规则

1. 合理分包：按场景/功能/共享拆分，主包瘦身首屏快

规则： 把非首屏所需的场景、UI、音频拆入独立 bundle；所有 bundle 共用的基础资源（公共 UI 图集、角色骨架、音效库）单独放一个 shared bundle 先行加载；主包只保留启动脚本和 Loading 界面资源。

为什么： AI 生成项目结构时最常见的做法是"把所有资源都放 resources 目录"，结果主包体积随着项目增长无节制膨胀，冷启动时间在中低端安卓机上轻松超过 10 秒。具体误区：把战斗场景的 1024×1024 角色图集和大厅场景的 BGM 全部打进主包——用户可能只是点了一下广告入口，根本不会进战斗场景，却已经把战斗资源全下载了。resources 目录下的所有资源会强制进主包，这是另一个常踩的坑。

怎么做：

• 在编辑器 Asset 面板右键目录 → 「创建 Bundle」，配置 Bundle Name 和优先级。
• 首屏仅需的资源留在 resources 或主包；战斗、副本、活动等按功能各建一个 bundle。
• 公共资源建 shared bundle，设置优先级最高，在游戏初始化阶段最先加载。
• 用 Build 面板检查 「Asset Bundle」标签，确认各 bundle 包含资源列表符合预期。

---

2. 加载与释放：loadBundle → bundle.load，用完正确释放防泄漏

规则： 通过 assetManager.loadBundle 获取 AssetBundle 对象，再用 bundle.load 加载具体资源；资源用完后调用 bundle.release(path, type) 或 bundle.releaseAll() 释放；bundle 本身用 assetManager.removeBundle(bundle) 卸载，两步缺一不可。

为什么： 只调用 bundle.releaseAll() 而不调用 assetManager.removeBundle 是高频错误：资源引用计数归零了，但 assetManager 内部仍缓存着这个 bundle 的实例，下次 loadBundle 同名 bundle 时直接返回缓存对象而不重新下载——如果服务器上 bundle 已更新，客户端却拿到旧的缓存，就会出现内容错误但不报任何错的诡异 bug。反过来，只调用 removeBundle 而不先 releaseAll，bundle 内资源引用计数不归零，纹理内存永远不释放。

怎么做：

// 加载 bundle
assetManager.loadBundle("battle", (err, bundle) => {
    if (err) { console.error(err); return; }
    // 加载具体资源
    bundle.load("prefabs/Enemy", Prefab, (err, prefab) => {
        if (err) { console.error(err); return; }
        prefab.addRef();          // 手动管理引用计数
        this._enemyPrefab = prefab;
    });
});

// 离开战斗场景时释放
leaveBattle() {
    if (this._enemyPrefab) {
        this._enemyPrefab.decRef();
        this._enemyPrefab = null;
    }
    const bundle = assetManager.getBundle("battle");
    if (bundle) {
        bundle.releaseAll();                    // 先释放 bundle 内所有资源引用计数
        assetManager.removeBundle(bundle);      // 再移除 bundle 缓存
    }
}