Estella微信小游戏与可玩广告导出详解:包体优化、内容缓存与热更新实战
Estella微信小游戏与可玩广告导出详解:包体优化、内容缓存与热更新实战
Estella 是一个快速 2D/3D 游戏引擎:TypeScript SDK + C++/WebAssembly 核心 + 可视化编辑器,同一个项目可导出到 Web、桌面、微信小游戏、可玩广告与 Android/iOS 原生。本文聚焦三条实战主线——微信小游戏导出的包体优化、内容寻址的内容缓存、以及基于 CDN 的热更新,帮你把主包压进 4 MB、让关卡资源边下边玩,并用单文件 index.html 交付可玩广告。
Estella 的核心理念是「play == ship」:导出用的是你在编辑器里 Play 的同一套运行时,编辑器里测过的就是最终交付的产物。
一次编写,多端导出
一个 Estella 项目对应六个目标:Web、Desktop、WeChat MiniGame、单文件 Playable Ad、Android 与 iOS。小游戏平台(微信 wx、抖音 tt 等)API 高度相似——没有 DOM、打包式文件系统、分包、键值存储——Estella 把这套模型只实现一次,每个厂商用 profile 数据描述,因此微信不是特例,只是家族中的一个 profile。
📖 多端导出总览:docs/astro/src/content/docs/publishing/overview.mdx;微信专项指南:docs/astro/src/content/docs/publishing/wechat.mdx
微信小游戏导出:三步完成打包
一键导出步骤:
- Settings → Project → Build and modules → Packaging → WeChat 填入 AppID;屏幕方向在 Game → Display → Orientation 全局设置一次;
- 打开 Build → Package Project…,在左侧平台列表选择「微信小游戏」,核对「构建包含的场景」,点击打包。Estella 会 cook 资源、把 SDK + 你的脚本打包成 CommonJS(via esbuild)、转换场景,输出独立小游戏包;
- 用微信开发者工具打开输出目录即可编译、测试、提审。
输出目录结构一目了然:game.js(入口)、game-bundle.js(SDK + 脚本)、game.json / project.config.json、asset-manifest.json、scenes/<name>.json,以及 wasm/ 目录——里面只有场景真正用到的侧模块,未使用的模块不增加包体。
侧模块需要一次性构建,用到什么建什么:
node build-tools/cli.js build -t wechat # 引擎核心
node build-tools/cli.js build -t physics-wechat # 物理
node build-tools/cli.js build -t spine-wechat # Spine 动画
⚠️ 缺少运行时会直接让导出失败(而非警告),报错会精确给出该执行的构建命令。别手动改
game.js或挪动wasm/下的文件——启动序列精确实例化这些文件,改名必坏。
包体优化:把主包压进 4 MB 的四个关键开关
引擎 .wasm 是小游戏包里最大的单个文件,微信主包又有 4 MB 硬限制。打包对话框提供了四件武器:
| 开关 | 效果 | 注意事项 |
|---|---|---|
| Compress textures | PNG → KTX2 压缩纹理,包体减重 + 首载更快,最大单项收益 | 自动把 .ktx2 存为 .ktx2.bin(白名单后缀),并生成 packOptions.include 规则 |
| Compress wasm binaries | 引擎与侧模块全部 .wasm.br,体积约 1/3 |
需基础库 2.14.0+,记得在微信后台设置最低基础库 |
| Engine in a subpackage | 引擎二进制移入启动分包,不再计入主包 | 启动时下载,进度条可见 |
| Render through EmscriptenGLX | GL 调用在 wasm 内批量执行,约千次 draw call 场景 Android 渲染耗时 -12% | 构建一次 build -t wechat-glx(约 +310 KB),Android 需基础库 3.8.12+,iOS 需高性能+模式,其他环境自动回退 WebGL2 |
💡 微信开发者工具里
bigPackageSizeSupport允许超限包预览,但上传时 4 MB 上限强制执行——别拿预览成功当通行证。💡 玩法中提前
loadGroup预载下一关资源组,避免分包下载卡住场景切换。
分包与按需加载:懒加载资源组 → 微信分包
Estella 的懒加载资产组会直接映射为 game.json 里的 subPackages。运行时 assets.loadGroup('level2') 会在底层触发 wx.loadSubpackage——关卡按需下载,而不是撑大首包。
资产按文件夹划分「交付组」(delivery group),三种模式:
| 模式 | 包内行为 | 角标 | 适用场景 |
|---|---|---|---|
| Local | 启动时加载 | — | 游戏核心资产 |
| Subpackage | 包内按需加载 | PKG(紫) |
大体积可选内容 / 微信分包 |
| Remote | 从 CDN 交付 | CDN(蓝) |
上线后要热更的一切内容 |
右键文件夹 → Delivery → Remote (CDN / hot-update) 即完成整个作者侧配置,决策写入 .esengine/asset-groups.json:
{
"groups": {
"cdn": { "folder": "assets/cdn", "mode": "remote" },
"pack": { "folder": "assets/pack", "mode": "subpackage" }
}
}
内容缓存与热更新:内容寻址 + CDN 四步机制
热更新的价值:游戏提审上线后,改一张贴图、一段音频、一个 prefab,直接走 CDN 换字节——无需重下包、无需重新提审。
Estella 的资源是内容寻址的:每个 cooked 资产以 <contentHash>.<ext> 交付——不可变、永久可缓存的 URL。改一个字节就是新 URL,旧文件只会被弃用、永不被覆盖,缓存天然不会过期。热更新因此只有四步:
- 拉取 CDN 上的
asset-manifest.json; - 按 content hash diff 出与运行版本的差异;
- 只下载 hash 变化的资产并逐一校验完整性;
- 原子切换活动 manifest,引用立即解析到新 URL。
游戏侧只需两次调用:
const plan = await assets.checkForUpdate({ manifestUrl, remoteRoot });
if (plan.hasUpdate) { // 先看 N 个文件 / K KB,再决定
const result = await assets.applyUpdate((loaded, total) => progress(loaded / total));
}
这套机制的工程细节非常扎实:
- 零代码重绑定:
applyUpdate成功后,内置 rebinder 会自动把新纹理换进所有声明了assetFields的字段(Sprite.texture、UIVisual.texture等),画面自己变——覆盖不到的手动绑定可用onInvalidate订阅自行重绑; - 两阶段原子提交:先下载校验、后提交。任何失败整体回滚,不存在半更新状态;
- 离线与持久化:
persistUpdateKey让下次启动直接跑在已更新内容上;有磁盘缓存的平台(含微信小游戏,托管于宿主用户数据目录)更新后无需联网即可读取。缓存预算可用cleanDiskCache(budget)管理,详见 docs/CACHE_BUDGET.md; - DLC 模式:远程组同时是下载通道,
loadGroup('world2')拉整组、releaseGroup('world2')释放,引用计数保证共享资产安全。
完整 API 与平台支持矩阵见 docs/astro/src/content/docs/publishing/hot-update.mdx。
💡 仓库里的 examples/hot-update-demo/ 把整个循环做成了可交互的「热更新中心」:
检查更新按钮 diff 本地更新通道(updates/v2-manifest.json),applyUpdate下载 v2 纹理、校验 contentHash,背景图由绿变红——游戏代码零行。
可玩广告导出:单文件 index.html 与各广告网络限制
Playable 目标把一切内联进单个自包含 index.html——无外部请求,这正是广告网络的要求。且 Playable 只带启动场景(单文件有体积上限)。
各网络对同一份单文件的限制与跳转方式:
| 广告网络 | 体积限制 | 点击跳转 |
|---|---|---|
| Generic | 2 MB | 无 |
| Meta(Facebook / Instagram) | index.html ≤ 2 MB |
FbPlayableAd.onCTAClick() |
| Google Ads | 5 MB | ExitApi.exit() |
| MRAID / Unity Ads / AppLovin | 5 MB | mraid.open() |
| Mintegral | 5 MB | window.install() |
| TikTok / Pangle | ZIP < 5 MB | window.openAppStore() |
自动资产优化:Asset optimization 设为 Auto 时,导出器先尊重 PNG Max Size 与 WAV 码率,若仍超目标则依次尝试无损 WebP、128 → 96 kbps 音频、WebP 质量 90/80——像素画、位图字体页等只走无损编码,语义绝不破坏。游戏代码永远只调用一次 playableCta(),导出器负责安装对应网络的桥接与 <head> 里的宿主 SDK。
examples/playable-ad/README.md 提供了带 mintegral、tiktok、pangle 等命名 profile 的完整起步项目,以及本地 mock 容器预览与 headless 校验流程。
实战清单:模板、示例与发布前检查
- 微信小游戏起步模板:templates/wechat-minigame/README.md —— CC0 舰队小游戏,含登录码/服务端换会话钩子、分享、激励视频与本地积分,其
wechatprofile 已启用引擎分包 + wasm.br 压缩,src/config.ts里填自己的广告单元与服务端; - 广告与分享服务:
Ads/Share/Recorder/Leaderboard统一封装各宿主差异(广告期间自动暂停时钟、挂起音频、全路径恢复),详见 docs/astro/src/content/docs/publishing/ads-sharing.mdx; - ✅ 纹理压缩打开(最大单项收益),主包控制在 4 MB 内,按需内容全部分包或 CDN 化;
- ✅ 用微信开发者工具而非浏览器测试——文件系统、存储、socket 后端都不同;
- ✅ 发布前核对导出体积报告中的首包 / 分包字节分配,并在真机测量冷启动;
- ✅ 热更内容单独放文件夹并标记 Remote,核心游戏保持 Local,保证无网也能启动。
掌握包体优化、内容缓存与热更新这三件事,你的 Estella 项目就具备了从微信小游戏到可玩广告完整上线的商业能力——一次编写,处处交付。



