1. 项目概述：当小游戏包体成为“甜蜜的负担”

“构建成功，包体大小：45MB。” 在Cocos Creator 3.x的构建面板上看到这个数字，我的心里“咯噔”一下。对于微信小游戏、抖音小游戏这类平台，主包大小通常被严格限制在4MB、8MB或16MB以内，超出的部分要么无法上传，要么会严重影响用户的首次加载体验，导致用户流失。这个45MB的包，显然已经远远超出了安全线。这几乎是每一个从Cocos Creator 2.x升级到3.x，或者初次尝试3D/复杂2D小游戏开发的团队都会遇到的“拦路虎”。包体过大，本质上是我们把所有资源——场景、脚本、纹理、动画、音效、字体——一股脑儿全塞进了初始包（主包）里。用户打开游戏前，必须把这几十兆的东西全部下载完，这在移动网络环境下是不可接受的。手动分包，就是解决这个问题的核心手术刀。它不是框架的自动魔法，而是开发者基于对项目结构的深度理解，进行的一次精细化资源调度规划。其目标非常明确：将游戏启动所必需的、最核心的代码和资源（我们称之为“首包”或“主包”）体积压缩到平台限制以内，确保用户能“秒开”游戏；同时，将非必需的大型资源（如大型场景、关卡资源、角色皮肤、过场动画）剥离出来，放在独立的“子包”中，在游戏运行过程中按需异步加载。今天，我就结合自己多次“瘦身手术”的经验，拆解Cocos Creator 3.x下小游戏手动分包的全流程、核心原理与那些容易踩坑的细节。

2. 核心思路与架构设计：化整为零的艺术

手动分包不是简单地把文件挪个位置，它背后是一套完整的资源加载与依赖管理逻辑的重构。在动手之前，我们必须先建立清晰的认知框架。

2.1 理解Cocos Creator的资源系统与构建流程

Cocos Creator采用基于UUID和依赖关系的资源管理系统。在编辑器中，每个资源（图片、预制体、场景、脚本）都有一个唯一的UUID。当你构建项目时，引擎会分析所有场景、脚本中引用的资源，形成一个庞大的依赖图。默认情况下，所有被直接或间接引用到的资源，都会被收集并打包进主包。

构建输出的目录结构通常如下：

build/ └── wechatgame/ (以微信小游戏为例) ├── game.js (主包入口逻辑) ├── game.json (小游戏配置文件) ├── src/ (压缩后的脚本代码) ├── assets/ (主包资源，包括图集、纹理、JSON等) └── remote/ (标记为“远程”的资源，不打包，需自行部署CDN)

我们的目标，就是在assets之外，创建新的、独立的资源包，并让游戏逻辑知道如何按需加载它们。

2.2 分包策略设计：什么该留，什么该走？

制定分包策略是成功的第一步。一个通用的原则是：“启动即用”的资源进主包，“按需所用”的资源进子包。

主包（首包）应包含：

1. 游戏启动场景：第一个加载的场景及其直接依赖的所有资源（UI、基础角色模型、初始背景）。
2. 核心框架脚本：游戏管理器、音频管理器、网络模块、配置表加载器等全局性、初始化就必须存在的脚本。
3. 基础公共资源：所有场景都可能用到的公共UI图集、通用按钮音效、默认字体。
4. 引擎最小化运行时：这部分由Cocos Creator构建时自动处理，但我们要确保没有把不必要的引擎模块（如3D物理、粒子高级功能）打包进来，可以通过“项目设置”中的“模块裁剪”进行优化。

子包候选资源：

1. 大型关卡/场景资源：每个关卡独有的地形、建筑、NPC模型和贴图。
2. 角色皮肤/时装资源：高品质的模型、骨骼动画和特效。
3. 剧情动画资源：视频、序列帧动画及其音效。
4. 非核心玩法系统：如家园系统、图鉴系统的专属界面和资源。
5. 本地化资源：其他语言的语音包、文字图片。

注意：分包不是越细越好。每个子包在加载时都有独立的网络请求开销。如果子包过多、过碎，可能会导致玩家在游戏过程中频繁遇到加载提示，影响体验。通常，可以按功能模块或关卡批次来划分子包。

2.3 技术方案选型：官方方案 vs 自定义方案

Cocos Creator 3.x 主要提供了两种分包方式：

1. 基于配置的“小游戏分包”：在project.json中配置subpackages。这是微信小游戏等平台原生支持的分包机制，子包下载后平台会管理其生命周期，访问子包内资源路径与主包一致，体验较好。这是我们的首选方案。
2. 资源包的动态加载：使用assetManager.loadBundle加载独立的资源包（Bundle）。这种方式更灵活，不依赖平台特性，可以用于加载远程服务器上的资源（类似“热更新”），但需要手动管理Bundle的加载、释放和资源路径。

本文将重点讲解第一种——基于配置的小游戏分包，因为它是解决包体超标问题最直接、最标准的方法。第二种方案更适合资源热更或超大型资源库的管理。

3. 手动分包实操全流程解析

理论清晰后，我们进入实战环节。我将以一个假设的“冒险小游戏”为例，它有一个主城场景和三个独立关卡场景。

3.1 第一步：项目结构与资源规划

在动手分包前，先在编辑器中科学地组织资源目录。我建议的目录结构如下：

assets/ ├── main/ # 主包资源 │ ├── scenes/ # 启动场景：MainCity.fire │ ├── scripts/ # 核心脚本 │ ├── textures/ # 公共UI图集、图标 │ └── sounds/ # 背景音乐、通用音效 ├── level1/ # 关卡1子包资源 │ ├── scene/ # Level1.fire │ ├── prefabs/ # 关卡专属预制体 │ └── textures/ # 关卡专属贴图 ├── level2/ # 关卡2子包资源 │ └── ... # 结构同level1 └── level3/ # 关卡3子包资源 └── ... # 结构同level1

这样划分，物理隔离清晰，便于后续配置。

3.2 第二步：配置project.json实现分包

这是最关键的一步。打开项目根目录下的project.json文件（如果没有，请参考Cocos Dashboard中的项目配置）。

我们需要在其中添加或修改subpackages字段。这是一个数组，每个元素代表一个子包。

{ "name": "your-game", "orientation": "portrait", // ... 其他配置 ... "subpackages": [ { "name": "Level1", "root": "assets/level1/" }, { "name": "Level2", "root": "assets/level2/" }, { "name": "Level3", "root": "assets/level3/" } ] }

• name: 子包的名字，后续加载时会用到，建议用英文。
• root: 该子包对应的资源目录路径，相对于assets目录。

配置完成后，必须重启Cocos Creator编辑器，配置才能生效。

3.3 第三步：构建验证与主包体积检查

配置好后，进行构建（以微信小游戏平台为例）。构建完成后，查看build/wechatgame目录：

build/wechatgame/ ├── game.js ├── game.json ├── assets/ # 主包资源，里面应该没有level1/2/3的内容 └── Level1/ # 子包目录！平台自动生成 ├── Level1.js └── assets/ # 子包资源

你会看到多出了Level1,Level2,Level3这样的文件夹，这就是构建出来的子包。同时，检查主包assets目录，确认其中不再包含已配置为子包的资源。

如何精确查看包体大小？

1. 直接查看构建输出文件夹的属性。
2. 使用微信开发者工具上传代码，在“上传”面板会清晰显示主包、各子包的大小。
3. 关注构建日志，Cocos Creator 3.x后期版本会在日志末尾输出各包大小概览。

此时，如果主包体积仍然超标，就需要回到第2.2节，进一步分析主包里还有什么“大家伙”，可能是某张未压缩的巨大图集，或者一个引用了太多资源的公共预制体。

3.4 第四步：在游戏中异步加载子包场景

主包体积达标后，我们需要修改代码，实现子包场景的按需加载。不能再使用director.loadScene(‘Level1’)这种同步方式了。

假设玩家在主城点击了“进入关卡1”的按钮，加载逻辑如下：

// 在某个脚本中，例如 LevelManager.ts import { _decorator, Component, director, Label } from 'cc'; const { ccclass, property } = _decorator; @ccclass('LevelManager') export class LevelManager extends Component { @property(Label) tipLabel: Label | null = null; // 用于显示加载提示的Label async onEnterLevel1() { this.showTip('正在加载关卡资源，请稍候...'); try { // 1. 加载子包 await this.loadSubPackage('Level1'); // 2. 子包加载成功后，再加载子包内的场景 director.loadScene('Level1'); // 注意：此时场景名路径与之前相同 this.showTip(''); // 清除提示 } catch (error) { console.error('加载关卡失败:', error); this.showTip('资源加载失败，请检查网络'); // 这里可以增加重试逻辑 } } // 封装加载子包的函数 loadSubPackage(packageName: string): Promise<void> { return new Promise((resolve, reject) => { // 判断平台，微信小游戏环境使用 wx.loadSubpackage if (typeof wx !== 'undefined' && wx.loadSubpackage) { const task = wx.loadSubpackage({ name: packageName, success: () => { console.log(`子包 ${packageName} 加载成功`); resolve(); }, fail: (res) => { console.error(`子包 ${packageName} 加载失败`, res); reject(new Error(`加载子包${packageName}失败`)); } }); // 可以监听加载进度（可选） task.onProgressUpdate((res) => { console.log(`加载进度: ${res.progress}%`); this.showTip(`加载中 ${res.progress}%...`); }); } else { // 非微信小游戏环境（如浏览器预览），我们假设资源已在主包，或做兼容处理 console.warn(`非小游戏环境，跳过子包 ${packageName} 加载`); resolve(); } }); } showTip(text: string) { if (this.tipLabel) { this.tipLabel.string = text; } } }

关键点解析：

• 平台API：wx.loadSubpackage是微信小游戏平台提供的API。其他平台（如字节跳动小游戏）可能有类似的API，如tt.loadSubpackage。代码中需要做平台判断。
• 异步操作：加载是网络IO操作，必须使用异步（这里用了async/await）或回调，避免阻塞主线程。
• 错误处理：网络可能不稳定，必须捕获加载失败的情况，并给用户友好的提示或重试选项。
• 进度反馈：onProgressUpdate可以提供进度反馈，极大提升用户体验。

4. 分包过程中的疑难杂症与深度优化

实际操作绝不会一帆风顺。下面是我踩过坑后总结出的核心问题和解决方案。

4.1 依赖分析与“包体泄露”

问题：明明把assets/level1/配置成了子包，但构建后发现主包里仍然包含该关卡的部分纹理或预制体。

根因：隐性依赖。主包里的某个资源（比如一个通用按钮预制体）引用了子包里的资源（比如一个关卡专属图标）。构建器在分析依赖时，发现主包资源依赖了子包资源，为了确保主包能独立运行，它会将被依赖的子包资源“提升”到主包中。

排查与解决：

1. 使用构建日志：在Cocos Creator的“构建”面板，勾选“显示构建日志”。构建完成后，仔细查看日志，搜索“asset”、“dependency”等关键词，构建器会输出资源依赖信息。
2. 检查资源引用：在编辑器中，选中疑似导致泄露的主包资源（如那个通用按钮），在“属性检查器”最下方查看“依赖资源”列表。如果里面出现了子包路径下的资源，就是问题所在。
3. 解决方案：
   • 重构资源：将产生跨包依赖的资源（如那个图标）复制一份到公共目录，或者修改设计，避免这种依赖。
   • 使用动态加载：如果必须引用，可以考虑将这种引用改为运行时动态加载。即，按钮不直接引用图标，而是在代码中判断，如果需要，则先加载子包，再从子包中加载该图标SpriteFrame。

4.2 子包加载失败与路径问题

问题：调用wx.loadSubpackage成功，但后续director.loadScene(‘Level1’)却报错找不到场景。

根因：场景加载路径理解错误。子包加载成功后，其内部的资源路径对于游戏运行时来说是“可见”的，你不需要在场景名或资源路径前添加子包名。

正确认知：

• 加载前：子包Level1内的场景Level1.fire，对游戏逻辑是不可见的。
• 加载后：Level1子包内的资源被映射到了根目录下。此时，assets/level1/Level1.fire这个路径就生效了。而director.loadScene的参数，正是这个相对于assets的路径（在构建时，.fire扩展名已被处理）。所以，你依然调用director.loadScene(‘Level1’)即可，前提是你的场景文件就放在assets/level1/根目录下。如果场景在子目录，如assets/level1/scenes/Level1.fire，则调用director.loadScene(‘scenes/Level1’)。

最佳实践：为每个子包维护一个资源索引文件或配置类，明确定义包内重要资源的路径，避免硬编码字符串散落在代码各处。

4.3 包体体积的极限压缩技巧

分包是第一步，压缩是第二步。两者结合才能将主包体积压到极致。

1. 纹理优化：

   • 压缩格式：在Cocos Creator的“资源管理器”中选中图片，在“属性检查器”中设置合适的压缩格式。对于小游戏，WebP(Android) /PVRTC(iOS) 通常是好选择，能大幅减少纹理内存和包体。可以勾选“使用Alpha通道分离”来进一步优化带透明通道的图片。
   • 图集（Sprite Atlas）：将大量小图打包成图集，能减少文件数量和小图存储开销。但要注意，一个图集是整体加载的。如果图集里混入了主包和子包都要用的图片，它就会被完整地打进主包。因此，要按包来规划图集。
   • 合理尺寸：确保图片尺寸是2的幂次方（如128, 256, 512），并且没有不必要的留白。

2. 音频优化：

   • 将背景音乐（BGM）从.mp3转换为更小的.ogg或.m4a格式。
   • 短音效可以使用.wav但需注意采样率，或使用压缩比更高的格式。

3. 引擎模块裁剪：

   • 打开“项目设置 -> 功能裁剪”，去掉你游戏用不到的功能模块。例如，纯2D游戏可以去掉3D物理、3D粒子等；不需要物理的游戏可以去掉整个物理引擎。

4. 脚本压缩与合并：

   • 构建时，确保开启了“压缩纹理”和“合并图集”选项。
   • 对于脚本，Cocos Creator默认会进行压缩和混淆（在“构建发布”面板勾选相应选项），这能有效减小代码体积。

4.4 子包的内存管理与释放

问题：玩家从关卡1切换到关卡2后，关卡1的资源还留在内存中，可能导致内存过高。

解决方案：Cocos Creator的资源释放是引用计数式的。但对于整个子包，微信小游戏平台提供了wx.removeSubpackage的实验性接口（请查阅最新官方文档确认），可以尝试移除子包。更通用的做法是：

1. 释放子包内具体资源：在离开一个子包对应的场景前，手动释放该场景不再需要的资源。

   // 在离开Level1场景时 resources.release(‘Level1/textures/boss’); // 释放特定纹理 assetManager.releaseAsset(someSpriteFrame); // 释放通过loadBundle加载的资源

2. 设计资源生命周期：明确哪些资源是全局常驻的（如UI图集），哪些是场景级别的，在场景切换时统一清理场景级资源。

5. 进阶：大型项目的分包架构与自动化

对于超大型项目，手动管理project.json和资源目录会变得繁琐。此时可以考虑一些半自动化或架构化的方案。

5.1 基于Bundle的模块化架构

除了平台分包，可以结合使用Cocos Creator的Asset Bundle功能进行更细粒度的资源管理。你可以将“核心框架”、“公共UI”、“角色系统”、“音效库”分别打成不同的Bundle。主包只包含启动和加载逻辑，所有功能Bundle都远程存放，实现真正的“微端”和动态更新。

// 动态加载一个远程资源包 assetManager.loadBundle('https://your-cdn.com/game-bundles/ui', (err, bundle) => { if (err) { /*处理错误*/ return; } // 从bundle中加载资源 bundle.load('prefabs/shopPanel', Prefab, (err, prefab) => { instantiate(prefab); }); });

5.2 自动化分包脚本

可以编写一个构建后处理脚本（例如使用Node.js），基于某些规则（如目录大小、资源类型）自动分析assets目录，并生成或更新project.json中的subpackages配置。这需要较深的工程化能力，但能极大提升团队协作效率。

5.3 监控与数据分析

上线后，需要关注子包的加载成功率和加载时长。可以在wx.loadSubpackage的成功和失败回调中埋点，将数据上报到自己的统计平台。分析哪些子包加载慢、失败率高，进而优化资源或考虑调整分包策略。

手动分包是Cocos Creator 3.x小游戏开发中一项必备的、略带“手艺”性质的技能。它没有一键解决的银弹，需要开发者深入理解自己的项目结构，在用户体验（加载速度）、开发效率（资源管理）和包体限制（平台规则）之间找到最佳平衡点。每一次成功的分包优化，都意味着你的游戏向更多用户流畅打开的大门又迈进了一步。