1. 项目概述与核心痛点如果你正在用CocosCreator开发一个中型或大型项目并且已经感受到了游戏启动时那令人焦虑的“白屏”或卡顿那么这篇文章就是为你准备的。我经历过不止一个项目从初期原型到内容膨胀的完整周期一个共同的、几乎无法回避的痛点就是随着resources目录下的资源越来越多首次加载时间变得越来越长用户体验直线下降。这不仅仅是“慢一点”的问题在追求“秒开”体验的今天启动卡顿直接关系到用户的留存率。问题的根源往往就藏在那个看似方便的resources目录里。CocosCreator的resources机制本质上是将所有标记为“动态加载”的资源在构建时打包进一个或几个大的资源包内。游戏启动时引擎需要先加载并解析这个庞大的资源索引文件通常是settings.json和对应的资源包才能知道如何加载后续的场景、图集、音频等。当资源量达到几百兆甚至上G时这个初始化过程会变得异常沉重尤其是在Web平台或性能有限的移动设备上。而CocosCreator提供的Bundle资源包系统正是为了解决这个问题而生的利器。它允许我们将资源按功能、场景或模块进行拆分形成多个独立的、可按需加载的AB包Asset Bundle。这不仅能实现资源的分包加载大幅削减首包体积和启动时间还能为热更新打下坚实的基础。今天我就以一个从resources迁移到自定义Bundle的实战案例手把手带你走通整个流程并附上完整的TypeScript代码让你能直接应用到自己的项目中。2. 迁移路线图整体设计与思路拆解从resources迁移到Bundle听起来像是把文件从一个文件夹挪到另一个文件夹但实际操作中它涉及到项目架构、加载逻辑和构建配置的系统性调整。盲目迁移只会带来一堆运行时错误。一个清晰的迁移路线图至关重要我将其总结为以下四个核心步骤这四步环环相扣缺一不可。2.1 第一步资源梳理与Bundle规划在动手改一行代码之前我们必须先搞清楚“有什么”和“要分成什么”。这是整个迁移过程中最需要深思熟虑的一步。首先彻底盘点你resources目录下的所有资源。打开资源管理器看看里面都放了些什么是大量的UI预制体、场景文件、独立的精灵帧还是整个图集Sprite Atlas你需要按功能模块或使用时机对它们进行归类。例如基础包包含启动场景、游戏核心逻辑脚本、所有场景公用的UI组件如通用弹窗、Loading界面、以及游戏运行必需的基础配置和字体。这个包必须在游戏启动时加载。登录/大厅包包含登录场景、角色创建、大厅界面的所有UI、背景和音效。战斗包包含战斗场景、所有英雄/怪物模型、技能特效、战斗音效和战斗专用UI。章节/关卡包如果游戏是关卡制可以按章节或大关卡来划分资源包。公共图集包将多个模块都可能用到的零散小图标打包成1-2个共享图集避免重复打包。规划的原则是高内聚低耦合。一个Bundle内的资源关联性要强不同Bundle之间的依赖要尽可能少。同时要预估每个Bundle的大小在Web平台单个Bundle建议控制在2-4MB以内以平衡加载速度和网络请求次数。2.2 第二步项目结构与配置调整规划好后就要在CocosCreator编辑器中落地。我们不再依赖唯一的resources目录而是要在assets目录下创建新的文件夹来承载我们的Bundle。创建Bundle目录在assets根目录下创建你规划好的Bundle文件夹例如assets/main、assets/login、assets/battle。你可以直接右键点击assets-新建 - 文件夹。配置Bundle属性这是关键一步。选中你新建的文件夹如assets/login在属性检查器中你会看到一个Bundle配置选项。将其Bundle Mode设置为Build并为其指定一个唯一的Bundle Name例如login。这个名称将在代码中被引用。同时可以配置Target Platform和Compression Type对于Web平台Compression Type选择合并所有Json或小游戏分包能获得更好的性能。迁移资源现在将原先resources目录下的资源按照你的规划拖拽到对应的Bundle目录中。例如把登录界面的预制体、背景图拖到assets/login下。注意拖拽操作会保持资源的UUID不变这是最安全的方式能避免资源引用丢失。千万不要在操作系统层面直接剪切粘贴。2.3 第三步代码加载逻辑的重构这是从resources.load到assetManager.loadBundle的转变。原有的加载代码需要全部重写。旧的resources加载方式// 旧代码 - 加载resources下的预制体 resources.load(prefabs/LoginPanel, Prefab, (err, prefab) { if (err) { console.error(err); return; } const node instantiate(prefab); director.getScene().addChild(node); });新的Bundle加载方式新的逻辑分为两步先加载Bundle包再从已加载的Bundle中加载具体资源。// 新代码 - 加载名为‘login’的Bundle然后加载其中的预制体 assetManager.loadBundle(login, (err, bundle) { if (err) { console.error(加载login bundle失败:, err); return; } // bundle加载成功后使用bundle对象加载资源 bundle.load(prefabs/LoginPanel, Prefab, (err, prefab) { if (err) { console.error(加载LoginPanel失败:, err); return; } const node instantiate(prefab); director.getScene().addChild(node); }); });你需要遍历所有使用resources.load的地方将其替换为上述新的模式。同时要管理好Bundle的生命周期。对于长期需要使用的Bundle如main加载后可以常驻内存。对于用完即弃的Bundle如某个一次性活动界面可以在界面关闭后调用bundle.releaseAll()来释放其占用的内存。2.4 第四步构建发布与验证代码重构完成后在构建发布时需要进行针对性配置。构建面板配置打开项目 - 项目设置 - 功能裁剪和项目 - 项目设置 - 模块设置确保没有误删引擎模块。然后打开项目 - 构建发布面板。关键配置项主包压缩类型通常选择默认或合并所有Json以减少请求数。配置LCP如果使用小游戏平台需要正确配置首屏场景和首屏资源它们会被自动打包进主包。MD5 Cache建议开启为文件添加哈希后缀有利于浏览器缓存和热更新。构建与测试点击构建。构建完成后观察输出目录。你会看到除了src代码包和assets资源包外多出了以你命名的Bundle文件夹如login、battle。用本地服务器或直接放到真机/模拟器上测试通过浏览器的开发者工具Network面板观察资源是否按预期分成了多个请求加载首屏加载时间是否显著缩短。注意迁移过程中最棘手的问题是资源引用的断裂。如果你在场景A中引用了一个图片而这个图片后来被移到了Bundle B里那么这个引用就会丢失。务必在迁移后仔细检查所有场景、预制体和动画编辑器中的资源引用是否正常属性检查器里是否有红色的缺失提示。这是一个需要耐心排查的过程。3. 核心细节解析与实操要点理解了整体路线我们深入到几个最容易出问题的核心细节。这些“坑”我几乎每一个都踩过希望你能避开。3.1 Bundle依赖管理与循环依赖陷阱当Bundle A中的资源引用了Bundle B中的资源时就产生了依赖。CocosCreator的构建系统会自动分析这种依赖关系。例如loginBundle中的一个UI预制体使用了commonBundle里的一个按钮精灵帧。构建时引擎会确保commonBundle先于或与loginBundle同时被加载。但是循环依赖是必须避免的绝对禁区。如果login依赖common同时common又依赖login构建过程可能会失败或者导致不可预知的运行时错误。在规划Bundle时就要设计清晰的依赖层级理想情况是形成一个有向无环图DAG。通常我会设计一个common或baseBundle存放最底层的共享资源其他业务Bundle都依赖它而它们之间尽量避免相互依赖。如何检查依赖在构建完成后查看构建日志或生成的settings.json文件里面会详细列出各个Bundle及其依赖关系。如果发现循环依赖必须回头调整资源规划打破这个环。3.2 图集Sprite Atlas的打包策略图集处理不当是导致Bundle失效的常见原因。在resources时代你可能习惯把一堆小图拖进一个图集里。迁移到Bundle后需要特别注意图集必须与使用它的资源在同一个Bundle内这是黄金法则。如果图集在Bundle A而使用该图集中子图的预制体在Bundle B那么Bundle B中的预制体将无法正确显示图片。构建时引擎可能会尝试将图集复制到Bundle B中但这会导致包体积膨胀更可能直接报错。规划共享图集对于多个Bundle都要用到的图标正确的做法是创建一个专门的common-atlasBundle将所有这些共享小图打包进一个或几个图集。然后让所有需要用到这些图标的业务Bundle都依赖这个common-atlasBundle。这样既保证了引用正确又避免了资源重复。自动图集配置在项目 - 项目设置 - 自动图集设置中可以为不同的Bundle目录配置不同的自动图集策略。例如为assets/login/ui单独生成一个login_ui图集实现更精细的控制。3.3 TypeScript中的异步加载与错误处理从同步思维切换到异步加载是另一个挑战。resources.load是回调assetManager.loadBundle也是回调容易陷入“回调地狱”。在实际项目中我强烈建议使用Promise或async/await对其进行封装让代码更清晰、更易于维护。以下是一个封装了错误处理和加载状态管理的Bundle加载工具类示例// BundleLoader.ts export class BundleLoader { private static loadedBundles: Mapstring, assetManager.Bundle new Map(); /** * 加载指定的Bundle * param bundleName Bundle名称 * returns PromiseassetManager.Bundle */ public static loadBundle(bundleName: string): PromiseassetManager.Bundle { return new Promise((resolve, reject) { // 检查是否已加载 if (this.loadedBundles.has(bundleName)) { resolve(this.loadedBundles.get(bundleName)!); return; } assetManager.loadBundle(bundleName, (err: Error | null, bundle: assetManager.Bundle | null) { if (err) { console.error([BundleLoader] 加载Bundle ${bundleName} 失败:, err); reject(err); return; } if (!bundle) { reject(new Error(Bundle ${bundleName} 加载后为null)); return; } this.loadedBundles.set(bundleName, bundle); console.log([BundleLoader] Bundle ${bundleName} 加载成功); resolve(bundle); }); }); } /** * 从指定Bundle中加载资源 * param bundleName Bundle名称 * param url 资源在Bundle内的路径 * param type 资源类型如Prefab, SpriteFrame, AudioClip * returns PromiseT */ public static async loadResT extends Asset(bundleName: string, url: string, type: AssetTypeT): PromiseT { try { const bundle await this.loadBundle(bundleName); return new PromiseT((resolve, reject) { bundle.load(url, type, (err: Error | null, asset: T | null) { if (err) { console.error([BundleLoader] 从Bundle ${bundleName} 加载资源 ${url} 失败:, err); reject(err); return; } if (!asset) { reject(new Error(资源 ${url} 加载后为null)); return; } resolve(asset); }); }); } catch (error) { throw new Error(加载流程失败: ${error}); } } /** * 释放指定Bundle的所有资源 * param bundleName Bundle名称 */ public static releaseBundle(bundleName: string): void { const bundle this.loadedBundles.get(bundleName); if (bundle) { bundle.releaseAll(); this.loadedBundles.delete(bundleName); console.log([BundleLoader] Bundle ${bundleName} 已释放); } } }使用这个工具类你的业务代码会变得非常简洁// 在登录场景中加载登录界面 async function loadLoginUI() { try { const loginPanelPrefab await BundleLoader.loadResPrefab(login, prefabs/LoginPanel, Prefab); const node instantiate(loginPanelPrefab); director.getScene().addChild(node); } catch (error) { // 统一的错误处理例如跳转到错误界面或重试 showErrorDialog(加载界面失败请检查网络); } }这种封装将复杂的异步回调、错误处理和缓存逻辑集中管理让业务逻辑更专注于“做什么”而不是“怎么做”。4. 实操过程从零开始迁移一个模块理论说再多不如亲手做一遍。我们以一个真实的“用户登录模块”为例将其从resources迁移到一个独立的loginBundle中。假设我们原始的assets/resources目录结构如下assets/ └── resources/ ├── textures/ │ └── login_bg.png ├── prefabs/ │ ├── LoginPanel.prefab │ └── RegisterPopup.prefab └── configs/ └── server_list.json4.1 第一步创建并配置Login Bundle在CocosCreator编辑器的资源管理器中右键点击assets目录选择新建 - 文件夹命名为login。点击新建的login文件夹在右侧的属性检查器面板中找到Bundle配置部分。将Bundle Mode从None改为Build。在Bundle Name中输入login全部小写避免后续引用问题。此时这个文件夹的图标可能会发生变化表示它已被识别为一个独立的资源包。4.2 第二步迁移资源与处理引用从resources目录中将login_bg.png、LoginPanel.prefab、RegisterPopup.prefab和server_list.json拖拽到新建的login文件夹内。确保是拖拽操作。关键检查双击打开LoginPanel.prefab。检查其上的所有组件特别是Sprite组件引用的图片、Button组件引用的精灵帧看是否有因为资源移动而变成红色的丢失状态。如果预制体内部引用了其他resources下的资源比如一个公共按钮图标你需要决定方案A将这个被引用的资源也移动到loginBundle中。适用于该资源基本只在登录模块使用方案B将这个资源移动到规划的公共Bundle如common中然后确保loginBundle依赖commonBundle。适用于该资源被多个模块共享假设我们发现LoginPanel用到了一个公共的btn_close图标这个图标在resources/ui/common下。我们选择方案B先创建commonBundle再把btn_close及相关共享UI资源移进去最后确保login预制体的引用自动更新只要UUID没变拖拽迁移通常会自动更新引用。4.3 第三步重构加载代码假设我们原来的登录逻辑写在LoginManager.ts中加载代码是这样的// 旧代码 - LoginManager.ts export class LoginManager { public static loadLoginScene(): void { // 加载背景图 resources.load(textures/login_bg, SpriteFrame, (err, spriteFrame) { // ... 设置背景 }); // 加载登录面板 resources.load(prefabs/LoginPanel, Prefab, (err, prefab) { const node instantiate(prefab); // ... 添加到场景 }); // 加载服务器列表配置 resources.load(configs/server_list, JsonAsset, (err, jsonAsset) { // ... 解析配置 }); } }现在我们使用前面封装好的BundleLoader工具类进行重构// 新代码 - LoginManager.ts import { BundleLoader } from ./BundleLoader; export class LoginManager { public static async loadLoginScene(): Promisevoid { try { // 并行加载Bundle内的多个资源提升加载效率 const [bgSpriteFrame, loginPanelPrefab, serverListJson] await Promise.all([ BundleLoader.loadResSpriteFrame(login, textures/login_bg, SpriteFrame), BundleLoader.loadResPrefab(login, prefabs/LoginPanel, Prefab), BundleLoader.loadResJsonAsset(login, configs/server_list, JsonAsset), ]); // 使用加载到的资源 // ... 设置背景 (bgSpriteFrame) const panelNode instantiate(loginPanelPrefab); // ... 添加到场景 const serverList serverListJson.json; // ... 解析配置 console.log(登录模块资源加载完成); } catch (error) { console.error(登录模块加载失败:, error); // 这里可以触发一个全局的错误处理比如显示网络错误弹窗并重试 this.retryLoad(); } } private static retryLoad(): void { // 实现重试逻辑例如3秒后重试 setTimeout(() { this.loadLoginScene(); }, 3000); } // 当离开登录场景时可以选择释放login bundle以节省内存 public static releaseLoginResources(): void { BundleLoader.releaseBundle(login); } }可以看到新的代码结构更清晰利用Promise.all实现了并行加载并且有完善的错误处理和重试机制。4.4 第四步构建与调试打开项目 - 构建发布选择目标平台如Web Mobile。在构建发布面板确保配置无误后点击构建。构建完成后用VS Code或任何HTTP服务器如http-server打开构建出的build目录。打开浏览器开发者工具切换到Network网络面板清除缓存并刷新页面。观察网络请求列表。你应该能看到除了主资源包如assets外多出了一个名为login或类似的独立文件请求。这证明我们的Bundle拆分成功了。检查控制台是否有红色报错并验证登录界面是否正常显示功能是否正常。5. 常见问题与排查技巧实录迁移过程中你几乎一定会遇到下面这些问题。我把它们和解决方案整理成了表格方便你快速排查。问题现象可能原因排查步骤与解决方案构建失败报错“资源引用丢失”1. 资源被移动到Bundle后场景或预制体中对该资源的引用路径失效。2. 图集Sprite Atlas与使用它的资源不在同一个Bundle且未正确处理依赖。1.检查红色引用打开所有场景和关键预制体在属性检查器中查找任何显示为红色或叹号的资源引用。逐一修复。2.检查图集确保每个自动图集或手动图集与其包含的所有子图都在同一个Bundle目录下。检查使用这些子图的预制体是否也在同Bundle或依赖Bundle中。运行时加载失败控制台报错“Bundle not found”1. Bundle名称拼写错误大小写敏感。2. Bundle文件夹未正确配置为Build模式。3. 构建后settings.json中未包含该Bundle的配置。1.核对名称检查代码中loadBundle(‘bundleName’)的bundleName是否与属性检查器中设置的Bundle Name完全一致。2.检查配置在编辑器中确认文件夹的Bundle Mode是否为Build。3.检查构建产物打开构建后的build/web-mobile/assets目录下的settings.json搜索你的Bundle名称看是否存在对应的配置条目。图片/纹理显示为粉色或白色1. 最常见原因Sprite引用的SpriteFrame所在的图集没有被加载。2. 资源本身加载失败。1.确认图集加载确保包含该SpriteFrame的图集Texture所在的Bundle已被成功加载。使用BundleLoader.loadRes加载该SpriteFrame本身看是否成功。2.检查资源路径确认加载路径是否正确。Bundle内路径是相对于Bundle根目录的例如Bundleui内文件icons/btn.png加载路径就是‘icons/btn’。Bundle加载成功但load单个资源时报错1. 资源在Bundle内的路径错误。2. 资源类型AssetType指定错误。1.查看Bundle内容在代码中加载Bundle成功后可以打印bundle.dir查看其虚拟根目录或通过bundle.getInfoWithPath()等方法探查内部结构确认资源的确切路径。2.核对类型Prefab、SpriteFrame、AudioClip等类型要传对。对于JSON、文本等使用JsonAsset、TextAsset类型。内存占用过高1. Bundle加载后没有在适当时机释放。2. 资源被重复加载。1.实施生命周期管理为每个游戏模块如登录、战斗、设置定义清晰的资源加载和释放时机。在模块关闭时如切换场景后调用bundle.releaseAll()。可以使用assetManager.bundles查看当前已加载的所有Bundle。2.使用缓存像前面的BundleLoader一样对已加载的Bundle进行缓存避免同一Bundle被多次loadBundle。热更新时自定义Bundle更新失败1. 服务器上Bundle文件的MD5与本地project.manifest中的记录不符。2. Bundle有依赖关系但未按顺序更新。1.确保manifest正确热更新服务器上的project.manifest必须由构建过程正确生成并包含所有Bundle的最新版本信息。2.处理依赖在热更新检查逻辑中需要递归检查并更新目标Bundle所依赖的所有其他Bundle。更新时建议先更新底层依赖包如common再更新业务包。除了上述问题还有一些从实践中得来的技巧善用“构建日志”构建面板下方有“构建日志”输出里面包含了资源打包、依赖分析的详细信息。遇到构建问题第一眼看这里往往能快速定位到是哪个资源出了问题。开发阶段临时方案在迁移过渡期你可能想部分资源用Bundle部分还用resources。这不是好习惯但如果你必须这么做记得resources和bundle.load是两套不同的查找路径互不干扰。但长远看应尽快完成全部迁移。性能分析迁移完成后一定要用真机进行性能测试。重点关注首次启动时间、内存峰值和不同场景切换的流畅度。对比迁移前后的数据你会看到明显的提升这也是对你迁移工作最好的回报。
CocosCreator项目资源加载优化：从resources迁移到Bundle的完整实战指南
发布时间：2026/7/13 12:43:24
1. 项目概述与核心痛点如果你正在用CocosCreator开发一个中型或大型项目并且已经感受到了游戏启动时那令人焦虑的“白屏”或卡顿那么这篇文章就是为你准备的。我经历过不止一个项目从初期原型到内容膨胀的完整周期一个共同的、几乎无法回避的痛点就是随着resources目录下的资源越来越多首次加载时间变得越来越长用户体验直线下降。这不仅仅是“慢一点”的问题在追求“秒开”体验的今天启动卡顿直接关系到用户的留存率。问题的根源往往就藏在那个看似方便的resources目录里。CocosCreator的resources机制本质上是将所有标记为“动态加载”的资源在构建时打包进一个或几个大的资源包内。游戏启动时引擎需要先加载并解析这个庞大的资源索引文件通常是settings.json和对应的资源包才能知道如何加载后续的场景、图集、音频等。当资源量达到几百兆甚至上G时这个初始化过程会变得异常沉重尤其是在Web平台或性能有限的移动设备上。而CocosCreator提供的Bundle资源包系统正是为了解决这个问题而生的利器。它允许我们将资源按功能、场景或模块进行拆分形成多个独立的、可按需加载的AB包Asset Bundle。这不仅能实现资源的分包加载大幅削减首包体积和启动时间还能为热更新打下坚实的基础。今天我就以一个从resources迁移到自定义Bundle的实战案例手把手带你走通整个流程并附上完整的TypeScript代码让你能直接应用到自己的项目中。2. 迁移路线图整体设计与思路拆解从resources迁移到Bundle听起来像是把文件从一个文件夹挪到另一个文件夹但实际操作中它涉及到项目架构、加载逻辑和构建配置的系统性调整。盲目迁移只会带来一堆运行时错误。一个清晰的迁移路线图至关重要我将其总结为以下四个核心步骤这四步环环相扣缺一不可。2.1 第一步资源梳理与Bundle规划在动手改一行代码之前我们必须先搞清楚“有什么”和“要分成什么”。这是整个迁移过程中最需要深思熟虑的一步。首先彻底盘点你resources目录下的所有资源。打开资源管理器看看里面都放了些什么是大量的UI预制体、场景文件、独立的精灵帧还是整个图集Sprite Atlas你需要按功能模块或使用时机对它们进行归类。例如基础包包含启动场景、游戏核心逻辑脚本、所有场景公用的UI组件如通用弹窗、Loading界面、以及游戏运行必需的基础配置和字体。这个包必须在游戏启动时加载。登录/大厅包包含登录场景、角色创建、大厅界面的所有UI、背景和音效。战斗包包含战斗场景、所有英雄/怪物模型、技能特效、战斗音效和战斗专用UI。章节/关卡包如果游戏是关卡制可以按章节或大关卡来划分资源包。公共图集包将多个模块都可能用到的零散小图标打包成1-2个共享图集避免重复打包。规划的原则是高内聚低耦合。一个Bundle内的资源关联性要强不同Bundle之间的依赖要尽可能少。同时要预估每个Bundle的大小在Web平台单个Bundle建议控制在2-4MB以内以平衡加载速度和网络请求次数。2.2 第二步项目结构与配置调整规划好后就要在CocosCreator编辑器中落地。我们不再依赖唯一的resources目录而是要在assets目录下创建新的文件夹来承载我们的Bundle。创建Bundle目录在assets根目录下创建你规划好的Bundle文件夹例如assets/main、assets/login、assets/battle。你可以直接右键点击assets-新建 - 文件夹。配置Bundle属性这是关键一步。选中你新建的文件夹如assets/login在属性检查器中你会看到一个Bundle配置选项。将其Bundle Mode设置为Build并为其指定一个唯一的Bundle Name例如login。这个名称将在代码中被引用。同时可以配置Target Platform和Compression Type对于Web平台Compression Type选择合并所有Json或小游戏分包能获得更好的性能。迁移资源现在将原先resources目录下的资源按照你的规划拖拽到对应的Bundle目录中。例如把登录界面的预制体、背景图拖到assets/login下。注意拖拽操作会保持资源的UUID不变这是最安全的方式能避免资源引用丢失。千万不要在操作系统层面直接剪切粘贴。2.3 第三步代码加载逻辑的重构这是从resources.load到assetManager.loadBundle的转变。原有的加载代码需要全部重写。旧的resources加载方式// 旧代码 - 加载resources下的预制体 resources.load(prefabs/LoginPanel, Prefab, (err, prefab) { if (err) { console.error(err); return; } const node instantiate(prefab); director.getScene().addChild(node); });新的Bundle加载方式新的逻辑分为两步先加载Bundle包再从已加载的Bundle中加载具体资源。// 新代码 - 加载名为‘login’的Bundle然后加载其中的预制体 assetManager.loadBundle(login, (err, bundle) { if (err) { console.error(加载login bundle失败:, err); return; } // bundle加载成功后使用bundle对象加载资源 bundle.load(prefabs/LoginPanel, Prefab, (err, prefab) { if (err) { console.error(加载LoginPanel失败:, err); return; } const node instantiate(prefab); director.getScene().addChild(node); }); });你需要遍历所有使用resources.load的地方将其替换为上述新的模式。同时要管理好Bundle的生命周期。对于长期需要使用的Bundle如main加载后可以常驻内存。对于用完即弃的Bundle如某个一次性活动界面可以在界面关闭后调用bundle.releaseAll()来释放其占用的内存。2.4 第四步构建发布与验证代码重构完成后在构建发布时需要进行针对性配置。构建面板配置打开项目 - 项目设置 - 功能裁剪和项目 - 项目设置 - 模块设置确保没有误删引擎模块。然后打开项目 - 构建发布面板。关键配置项主包压缩类型通常选择默认或合并所有Json以减少请求数。配置LCP如果使用小游戏平台需要正确配置首屏场景和首屏资源它们会被自动打包进主包。MD5 Cache建议开启为文件添加哈希后缀有利于浏览器缓存和热更新。构建与测试点击构建。构建完成后观察输出目录。你会看到除了src代码包和assets资源包外多出了以你命名的Bundle文件夹如login、battle。用本地服务器或直接放到真机/模拟器上测试通过浏览器的开发者工具Network面板观察资源是否按预期分成了多个请求加载首屏加载时间是否显著缩短。注意迁移过程中最棘手的问题是资源引用的断裂。如果你在场景A中引用了一个图片而这个图片后来被移到了Bundle B里那么这个引用就会丢失。务必在迁移后仔细检查所有场景、预制体和动画编辑器中的资源引用是否正常属性检查器里是否有红色的缺失提示。这是一个需要耐心排查的过程。3. 核心细节解析与实操要点理解了整体路线我们深入到几个最容易出问题的核心细节。这些“坑”我几乎每一个都踩过希望你能避开。3.1 Bundle依赖管理与循环依赖陷阱当Bundle A中的资源引用了Bundle B中的资源时就产生了依赖。CocosCreator的构建系统会自动分析这种依赖关系。例如loginBundle中的一个UI预制体使用了commonBundle里的一个按钮精灵帧。构建时引擎会确保commonBundle先于或与loginBundle同时被加载。但是循环依赖是必须避免的绝对禁区。如果login依赖common同时common又依赖login构建过程可能会失败或者导致不可预知的运行时错误。在规划Bundle时就要设计清晰的依赖层级理想情况是形成一个有向无环图DAG。通常我会设计一个common或baseBundle存放最底层的共享资源其他业务Bundle都依赖它而它们之间尽量避免相互依赖。如何检查依赖在构建完成后查看构建日志或生成的settings.json文件里面会详细列出各个Bundle及其依赖关系。如果发现循环依赖必须回头调整资源规划打破这个环。3.2 图集Sprite Atlas的打包策略图集处理不当是导致Bundle失效的常见原因。在resources时代你可能习惯把一堆小图拖进一个图集里。迁移到Bundle后需要特别注意图集必须与使用它的资源在同一个Bundle内这是黄金法则。如果图集在Bundle A而使用该图集中子图的预制体在Bundle B那么Bundle B中的预制体将无法正确显示图片。构建时引擎可能会尝试将图集复制到Bundle B中但这会导致包体积膨胀更可能直接报错。规划共享图集对于多个Bundle都要用到的图标正确的做法是创建一个专门的common-atlasBundle将所有这些共享小图打包进一个或几个图集。然后让所有需要用到这些图标的业务Bundle都依赖这个common-atlasBundle。这样既保证了引用正确又避免了资源重复。自动图集配置在项目 - 项目设置 - 自动图集设置中可以为不同的Bundle目录配置不同的自动图集策略。例如为assets/login/ui单独生成一个login_ui图集实现更精细的控制。3.3 TypeScript中的异步加载与错误处理从同步思维切换到异步加载是另一个挑战。resources.load是回调assetManager.loadBundle也是回调容易陷入“回调地狱”。在实际项目中我强烈建议使用Promise或async/await对其进行封装让代码更清晰、更易于维护。以下是一个封装了错误处理和加载状态管理的Bundle加载工具类示例// BundleLoader.ts export class BundleLoader { private static loadedBundles: Mapstring, assetManager.Bundle new Map(); /** * 加载指定的Bundle * param bundleName Bundle名称 * returns PromiseassetManager.Bundle */ public static loadBundle(bundleName: string): PromiseassetManager.Bundle { return new Promise((resolve, reject) { // 检查是否已加载 if (this.loadedBundles.has(bundleName)) { resolve(this.loadedBundles.get(bundleName)!); return; } assetManager.loadBundle(bundleName, (err: Error | null, bundle: assetManager.Bundle | null) { if (err) { console.error([BundleLoader] 加载Bundle ${bundleName} 失败:, err); reject(err); return; } if (!bundle) { reject(new Error(Bundle ${bundleName} 加载后为null)); return; } this.loadedBundles.set(bundleName, bundle); console.log([BundleLoader] Bundle ${bundleName} 加载成功); resolve(bundle); }); }); } /** * 从指定Bundle中加载资源 * param bundleName Bundle名称 * param url 资源在Bundle内的路径 * param type 资源类型如Prefab, SpriteFrame, AudioClip * returns PromiseT */ public static async loadResT extends Asset(bundleName: string, url: string, type: AssetTypeT): PromiseT { try { const bundle await this.loadBundle(bundleName); return new PromiseT((resolve, reject) { bundle.load(url, type, (err: Error | null, asset: T | null) { if (err) { console.error([BundleLoader] 从Bundle ${bundleName} 加载资源 ${url} 失败:, err); reject(err); return; } if (!asset) { reject(new Error(资源 ${url} 加载后为null)); return; } resolve(asset); }); }); } catch (error) { throw new Error(加载流程失败: ${error}); } } /** * 释放指定Bundle的所有资源 * param bundleName Bundle名称 */ public static releaseBundle(bundleName: string): void { const bundle this.loadedBundles.get(bundleName); if (bundle) { bundle.releaseAll(); this.loadedBundles.delete(bundleName); console.log([BundleLoader] Bundle ${bundleName} 已释放); } } }使用这个工具类你的业务代码会变得非常简洁// 在登录场景中加载登录界面 async function loadLoginUI() { try { const loginPanelPrefab await BundleLoader.loadResPrefab(login, prefabs/LoginPanel, Prefab); const node instantiate(loginPanelPrefab); director.getScene().addChild(node); } catch (error) { // 统一的错误处理例如跳转到错误界面或重试 showErrorDialog(加载界面失败请检查网络); } }这种封装将复杂的异步回调、错误处理和缓存逻辑集中管理让业务逻辑更专注于“做什么”而不是“怎么做”。4. 实操过程从零开始迁移一个模块理论说再多不如亲手做一遍。我们以一个真实的“用户登录模块”为例将其从resources迁移到一个独立的loginBundle中。假设我们原始的assets/resources目录结构如下assets/ └── resources/ ├── textures/ │ └── login_bg.png ├── prefabs/ │ ├── LoginPanel.prefab │ └── RegisterPopup.prefab └── configs/ └── server_list.json4.1 第一步创建并配置Login Bundle在CocosCreator编辑器的资源管理器中右键点击assets目录选择新建 - 文件夹命名为login。点击新建的login文件夹在右侧的属性检查器面板中找到Bundle配置部分。将Bundle Mode从None改为Build。在Bundle Name中输入login全部小写避免后续引用问题。此时这个文件夹的图标可能会发生变化表示它已被识别为一个独立的资源包。4.2 第二步迁移资源与处理引用从resources目录中将login_bg.png、LoginPanel.prefab、RegisterPopup.prefab和server_list.json拖拽到新建的login文件夹内。确保是拖拽操作。关键检查双击打开LoginPanel.prefab。检查其上的所有组件特别是Sprite组件引用的图片、Button组件引用的精灵帧看是否有因为资源移动而变成红色的丢失状态。如果预制体内部引用了其他resources下的资源比如一个公共按钮图标你需要决定方案A将这个被引用的资源也移动到loginBundle中。适用于该资源基本只在登录模块使用方案B将这个资源移动到规划的公共Bundle如common中然后确保loginBundle依赖commonBundle。适用于该资源被多个模块共享假设我们发现LoginPanel用到了一个公共的btn_close图标这个图标在resources/ui/common下。我们选择方案B先创建commonBundle再把btn_close及相关共享UI资源移进去最后确保login预制体的引用自动更新只要UUID没变拖拽迁移通常会自动更新引用。4.3 第三步重构加载代码假设我们原来的登录逻辑写在LoginManager.ts中加载代码是这样的// 旧代码 - LoginManager.ts export class LoginManager { public static loadLoginScene(): void { // 加载背景图 resources.load(textures/login_bg, SpriteFrame, (err, spriteFrame) { // ... 设置背景 }); // 加载登录面板 resources.load(prefabs/LoginPanel, Prefab, (err, prefab) { const node instantiate(prefab); // ... 添加到场景 }); // 加载服务器列表配置 resources.load(configs/server_list, JsonAsset, (err, jsonAsset) { // ... 解析配置 }); } }现在我们使用前面封装好的BundleLoader工具类进行重构// 新代码 - LoginManager.ts import { BundleLoader } from ./BundleLoader; export class LoginManager { public static async loadLoginScene(): Promisevoid { try { // 并行加载Bundle内的多个资源提升加载效率 const [bgSpriteFrame, loginPanelPrefab, serverListJson] await Promise.all([ BundleLoader.loadResSpriteFrame(login, textures/login_bg, SpriteFrame), BundleLoader.loadResPrefab(login, prefabs/LoginPanel, Prefab), BundleLoader.loadResJsonAsset(login, configs/server_list, JsonAsset), ]); // 使用加载到的资源 // ... 设置背景 (bgSpriteFrame) const panelNode instantiate(loginPanelPrefab); // ... 添加到场景 const serverList serverListJson.json; // ... 解析配置 console.log(登录模块资源加载完成); } catch (error) { console.error(登录模块加载失败:, error); // 这里可以触发一个全局的错误处理比如显示网络错误弹窗并重试 this.retryLoad(); } } private static retryLoad(): void { // 实现重试逻辑例如3秒后重试 setTimeout(() { this.loadLoginScene(); }, 3000); } // 当离开登录场景时可以选择释放login bundle以节省内存 public static releaseLoginResources(): void { BundleLoader.releaseBundle(login); } }可以看到新的代码结构更清晰利用Promise.all实现了并行加载并且有完善的错误处理和重试机制。4.4 第四步构建与调试打开项目 - 构建发布选择目标平台如Web Mobile。在构建发布面板确保配置无误后点击构建。构建完成后用VS Code或任何HTTP服务器如http-server打开构建出的build目录。打开浏览器开发者工具切换到Network网络面板清除缓存并刷新页面。观察网络请求列表。你应该能看到除了主资源包如assets外多出了一个名为login或类似的独立文件请求。这证明我们的Bundle拆分成功了。检查控制台是否有红色报错并验证登录界面是否正常显示功能是否正常。5. 常见问题与排查技巧实录迁移过程中你几乎一定会遇到下面这些问题。我把它们和解决方案整理成了表格方便你快速排查。问题现象可能原因排查步骤与解决方案构建失败报错“资源引用丢失”1. 资源被移动到Bundle后场景或预制体中对该资源的引用路径失效。2. 图集Sprite Atlas与使用它的资源不在同一个Bundle且未正确处理依赖。1.检查红色引用打开所有场景和关键预制体在属性检查器中查找任何显示为红色或叹号的资源引用。逐一修复。2.检查图集确保每个自动图集或手动图集与其包含的所有子图都在同一个Bundle目录下。检查使用这些子图的预制体是否也在同Bundle或依赖Bundle中。运行时加载失败控制台报错“Bundle not found”1. Bundle名称拼写错误大小写敏感。2. Bundle文件夹未正确配置为Build模式。3. 构建后settings.json中未包含该Bundle的配置。1.核对名称检查代码中loadBundle(‘bundleName’)的bundleName是否与属性检查器中设置的Bundle Name完全一致。2.检查配置在编辑器中确认文件夹的Bundle Mode是否为Build。3.检查构建产物打开构建后的build/web-mobile/assets目录下的settings.json搜索你的Bundle名称看是否存在对应的配置条目。图片/纹理显示为粉色或白色1. 最常见原因Sprite引用的SpriteFrame所在的图集没有被加载。2. 资源本身加载失败。1.确认图集加载确保包含该SpriteFrame的图集Texture所在的Bundle已被成功加载。使用BundleLoader.loadRes加载该SpriteFrame本身看是否成功。2.检查资源路径确认加载路径是否正确。Bundle内路径是相对于Bundle根目录的例如Bundleui内文件icons/btn.png加载路径就是‘icons/btn’。Bundle加载成功但load单个资源时报错1. 资源在Bundle内的路径错误。2. 资源类型AssetType指定错误。1.查看Bundle内容在代码中加载Bundle成功后可以打印bundle.dir查看其虚拟根目录或通过bundle.getInfoWithPath()等方法探查内部结构确认资源的确切路径。2.核对类型Prefab、SpriteFrame、AudioClip等类型要传对。对于JSON、文本等使用JsonAsset、TextAsset类型。内存占用过高1. Bundle加载后没有在适当时机释放。2. 资源被重复加载。1.实施生命周期管理为每个游戏模块如登录、战斗、设置定义清晰的资源加载和释放时机。在模块关闭时如切换场景后调用bundle.releaseAll()。可以使用assetManager.bundles查看当前已加载的所有Bundle。2.使用缓存像前面的BundleLoader一样对已加载的Bundle进行缓存避免同一Bundle被多次loadBundle。热更新时自定义Bundle更新失败1. 服务器上Bundle文件的MD5与本地project.manifest中的记录不符。2. Bundle有依赖关系但未按顺序更新。1.确保manifest正确热更新服务器上的project.manifest必须由构建过程正确生成并包含所有Bundle的最新版本信息。2.处理依赖在热更新检查逻辑中需要递归检查并更新目标Bundle所依赖的所有其他Bundle。更新时建议先更新底层依赖包如common再更新业务包。除了上述问题还有一些从实践中得来的技巧善用“构建日志”构建面板下方有“构建日志”输出里面包含了资源打包、依赖分析的详细信息。遇到构建问题第一眼看这里往往能快速定位到是哪个资源出了问题。开发阶段临时方案在迁移过渡期你可能想部分资源用Bundle部分还用resources。这不是好习惯但如果你必须这么做记得resources和bundle.load是两套不同的查找路径互不干扰。但长远看应尽快完成全部迁移。性能分析迁移完成后一定要用真机进行性能测试。重点关注首次启动时间、内存峰值和不同场景切换的流畅度。对比迁移前后的数据你会看到明显的提升这也是对你迁移工作最好的回报。
