首包、分包、远程资源与加载状态
适用:Cocos Creator 3.8.8 + TypeScript,原理通用于游戏资源分发。资料核查:2026-11-17。已读取微信分包加载、独立分包与加载接口的官方原文。下列限额是核查日文档规则,特殊构建模式须另核专属说明;未进行账号后台或真机验证。
首次可玩由依赖关键路径决定
包体小不一定启动快。一个很小的主包如果串行请求多个清单、字体、图集和远程配置,仍可能长时间黑屏;一个较大的包若能快速展示可交互内容,体验反而更好。先定义首帧、首个可交互界面和首个可玩局的时点,再从这些时点倒推必需依赖。下载、校验、解析、解码、上传 GPU 和场景实例化都可能成为阻塞点。
画出依赖图比先切包更有效。启动 UI 只依赖少量字体、图形与错误界面;第一关依赖首关规则、角色与敌人资源;后续章节、美术图鉴和非必要音频可以延迟。静态引用会把依赖跨目录拉进来,所以“文件放在 chapter2 目录”并不保证首关不加载它。最后要检查构建产物与加载记录,而不是只检查源码结构。
Bundle 与平台分包职责不同
Cocos Asset Bundle 定义引擎资源的模块边界,包含加载清单及资源关系;微信分包定义平台如何分发代码或资源。一个合理的 Bundle 可以按目标配置为不同分发方式,但不是任何 Bundle 都自动成为微信分包。主包、分包与远程资源的选择,需要结合脚本规则、平台支持、离线能力和版本管理,不能把网页上可远程加载脚本的做法直接用于小游戏。
平台限额是发布时必须核查的硬约束,性能预算则是产品自己的目标,二者分开记录。微信分包加载指南在核查日明确列出以下限制,单位沿用原文的 M:
| 对象 | 官方限制 |
|---|---|
| 主包与所有分包合计 | 不超过 30M |
| 主包 | 不超过 4M |
| 单个普通分包 | 不限制单包大小,仍受 30M 总量约束 |
| 单个独立分包 | 不超过 4M |
该页未给出分包数量上限,不据此补猜。发布时重新核对规则和实际构建报告;此表不外推至另有规定的特殊构建模式。即使包体合规,也可能因为首关纹理太大而内存不足;把资源搬到 CDN 只改变分发位置,不会自动减少解码后的内存。
普通分包通过 game.json 的 subpackages 配置。wx.loadSubpackage 下载完成后会执行分包代码;基础库 3.4.9 起的 wx.preDownloadSubpackage 只预下载,之后仍需调用 wx.loadSubpackage 执行。这与引擎的资源解码、加载场景和实例化不是同一个完成信号,不能在代码包下载结束时就宣称关卡可玩。
独立分包可从其配置路径冷启动而不先下载主包,要求微信客户端至少 7.0.13、基础库至少 2.12.1。它不能依赖主包或其他分包的代码与资源;普通运行中的页面切换不会自动获得这种冷启动收益。是否采用它,应先确认目标引擎构建流程和独立入口的真实依赖。
按生命周期组织资源边界
公共 UI、首关、后续关卡、活动资源可以各自拥有加载和卸载时机。共享大图集不总是节省:首关只用其中两个小图,却可能被迫加载整张纹理。将资源放进共享包的收益要同时计算重复下载与额外常驻。相反,过度拆成大量小包会增加请求、清单和管理成本。以“何时同时使用、何时同时释放”为首要分组依据。
import { assetManager, AssetManager } from 'cc';
const loading = new Map<string, Promise<AssetManager.Bundle>>();
export function ensureBundle(name: string) {
let task = loading.get(name);
if (task) return task;
task = new Promise<AssetManager.Bundle>((resolve, reject) => {
assetManager.loadBundle(name, (err, bundle) =>
err ? reject(err) : resolve(bundle));
});
loading.set(name, task);
void task.catch(() => {
if (loading.get(name) === task) loading.delete(name);
});
return task;
}
示例合并并发加载,并允许失败后重试。它没有完整的卸载协议;若移除 Bundle,应同步清除此映射,避免返回已失效对象。加载 Bundle 完成也不代表所有资源都已实例化,后续还要 load 目标场景或资源。把这些阶段显示成一个永远停在九成的假进度,不能帮助定位真实瓶颈。
加载流程必须可以失败和离开
为一次入关分配 generation:下载 Bundle、加载资源、创建场景都带同一世代;玩家返回首页后,旧流程的回调不能再次切进战斗。部分平台任务可能无法真正取消,但仍能取消其业务效果。资源若因旧流程加载完成,应交还正确的资源所有者,而不是无条件释放可能已被新流程复用的对象。
进度显示优先用可测阶段:连接与清单、下载、资源准备、场景创建。只有同一量纲才能合并百分比;字节进度不能直接代表 CPU 解码耗时。设置超时、有限重试、手动重试与返回入口。弱网下允许玩家明确结束等待,网络恢复后也不能悄悄把已经关闭的流程重新弹出。
远程版本必须作为一个整体发布
客户端脚本、资源清单和实际文件需要一致。先上传不可变版本资源并校验,再切换引用该版本的配置或发布客户端;不要覆盖同名文件让缓存随机混用。资源路径带版本或内容哈希,可以更明确地区分新旧。清理旧资源前统计仍运行旧包的会话,否则旧客户端重连时会找不到自己需要的文件。
规则表也是内容依赖。新规则如果引用旧包不认识的敌人或特效,应有最低客户端版本和可用范围。远程配置不能随意改变代码预期的结构,也不应成为绕过平台审核要求的通道。发布合法性由当前平台规范核验;课程只说明版本一致性与回退原理。
缓存命中也需要验证
冷启动、热缓存启动、缓存损坏和版本更新要分别测。热缓存掩盖了下载和首次解码问题;清缓存后一次成功也不能证明升级路径正确。构建清单应能说明哪些资源属于首包、分包或远程,并关联其大小、版本和用途。记录失败 URL 时注意不输出带长期凭据的链接。
遇到首关等待长,先比较下载结束与首帧之间的时间:若间隔大,问题可能是解析和实例化;若下载字节异常,查静态引用和图集归属;若只有更新后失败,查清单与文件版本。内存峰值发生在切关时,则检查是否新旧场景同时持有大资源,而不是继续切小压缩文件。
公共依赖要经过一次真实收集检查
假设大厅和第二章都引用同一个角色图集,将它划入公共 Bundle 后,观察首关是否因此下载整张图集,第二章是否重复携带副本,以及切关后谁仍持有它。仅凭“公共资源统一管理”的命名不能证明节省。对大资源建立使用者清单,记录同时使用的时段,才能决定共享、拆分或复制哪个更合算。
加载错误界面本身必须属于可靠的最小依赖。若错误提示字体和重试按钮也放在失败的远程包里,弱网时连恢复入口都显示不出来。启动包至少保留可读的错误、返回与重试能力,错误码对应具体阶段,便于区分下载失败和场景创建失败。
交给 AI 的任务与验收
可复制任务:“将首关与后续关卡按加载生命周期划为 Bundle,列出静态依赖和分发方式。实现单次入关状态机、并发加载合并、失败重试和世代过滤;生成冷缓存与升级测试步骤。按本章官方限额表检查实际产物,区分下载、执行、资源准备与可玩时点;发布前重核规则,不填推测数字。”
验收首关不加载后续大图集;同时点击入关只创建一次加载;返回后旧回调不切场景;断网可重试;新旧资源版本不会混合。真实包体合规与真机耗时分别由工具报告和设备记录证明。
官方来源与边界
- Cocos 3.8 Asset Bundle:Bundle 加载、移除与平台分包区别。
- 微信官方 game.json与加载示例:分包配置与调用形态,示例不是当前限额依据。
- 微信分包加载:已核对包体限制、配置、加载与预下载;网页标注最后编辑于 2026-04-09。
- 微信独立分包:已核对最低版本、冷启动和依赖边界。
- wx.loadSubpackage:已核对下载后执行代码及任务回调,不能替代引擎资源与真机验收。