活动 ZIP 分包与公共清单

金字塔、黄金矿工和百人赛统一接入。构建扩展位于 packages/activity-bundles，接入名单为 bundles.json：pyramid、coin_madness、art、matching、stage1、stage2、stage3。公共清单只描述资源，不包含活动开放时间、玩家资格或奖励状态。保留原有加载触发时机和业务接口流程，黄金矿工不新增首页预加载。

构建与发布

重启 Creator 2.4.15，使构建扩展注册。上述七个 Bundle 配置为微信远程 Bundle、合并所有 JSON；百人赛 cloud_rise_home 仍为本地分包。其他平台配置不变。
在微信构建配置中填写 HTTPS 资源服务器地址，完整构建微信小游戏。扩展自动压缩接入名单中的每个 Bundle，生成 SHA-256、ZIP 大小及解压文件校验清单。
默认发布产物在 build/wechatgame-activities/remote/：公共 manifest.json，以及七个 <bundle>/<bundle>.<SHA-256>.zip。同样输入重复构建，ZIP 和哈希不变。旧哈希 ZIP 保留，方便旧客户端和正在运行的请求继续读取。
先上传哈希命名的 ZIP，确认文件可访问后，再更新 remote/manifest.json。清单禁用 CDN 缓存；ZIP 可长期缓存。代码包中的 remote 目录不上传到微信。ZIP 只含资源，组件脚本仍由 src/scripts/<bundle>/index.js 随微信代码包发布。
同步发布本次客户端代码。后续只改资源可更新 ZIP 和清单；修改脚本或本地依赖仍需要重新发布小游戏代码包。本工具不自动上传或发布。

已有构建目录可单独生成资源包（不编译 TypeScript，也不能替代完整构建）：

node packages/activity-bundles/pack.js build/wechatgame

资源地址取自构建产物 src/settings.js 的 server，例如 https://cdn.pay.nika4games.com/remote/manifest.json。运行时不会把业务接口域名当成资源域名。微信需配置该 CDN 的 request/downloadFile 合法域名。

公共清单严格使用以下结构，每个 Bundle 仅包含 file、hash、size。hash 是整个 ZIP 的 SHA-256，size 为 ZIP 字节数。下面省略百人赛五个同结构条目；黄金矿工保留实际 Bundle 名 coin_madness：

{
  "schemaVersion": 1,
  "bundles": {
    "pyramid": {
      "file": "pyramid/pyramid.<哈希值>.zip",
      "hash": "<ZIP文件的SHA-256>",
      "size": 123456
    },
    "coin_madness": {
      "file": "coin_madness/coin_madness.<哈希值>.zip",
      "hash": "<ZIP文件的SHA-256>",
      "size": 234567
    }
  }
}

Bundle 配置文件名、版本及逐文件校验信息存于 ZIP 内的 bundle-manifest.json，不加入公共清单。下载后先校验整个 ZIP，再校验内部清单与归档文件是否一致；本地缓存记录保存内部清单哈希，防止内部清单损坏导致完整性检查失效。

加载与缓存

ActivityBundleLoader.ensureBundle("pyramid") 接入 Cocos 的 Bundle 加载方式。微信构建扩展在 boot 前安装公共加载器，既支持该方法，也兼容既有 cc.assetManager.loadBundle(name, callback) 调用。编辑器和浏览器预览继续使用 Creator 原有加载方式。微信构建缺少加载器时明确报错，不悄悄退回远程目录下载。

首页依据活动日程、关卡门槛和已知个人完成状态预加载金字塔；未开放时不因清单而加载其他活动。打开活动复用日程，个人详情单独获取。
登录至首次首页共享一个资源检查周期；之后每次返回首页、切回前台开启新周期。一个周期内，各活动共享一个清单请求，同一 Bundle 共享加载任务。持续停留和倒计时不发起网络请求。
缓存按资源服务器地址、Bundle 名、ZIP 哈希隔离。哈希相同且每个文件的大小、SHA-256 和 Bundle 配置都正确时使用本地解压目录；缺失或损坏时重新下载。
ZIP 先下载到新的暂存目录，核对大小、实际 SHA-256 和归档路径后解压，再验证文件和配置。全部成功才更新该 Bundle 的缓存记录。失败只删除该暂存目录，不覆盖旧记录、不清除其他活动缓存。
清单请求、解析或校验失败时，允许使用本地缓存继续加载，但仍校验缓存归属、内部清单哈希及每个文件的完整性；没有有效缓存则失败，不猜测远端版本、不下载或改写缓存记录。同周期共享加载结果，下次返回首页或切回前台重新检查清单。正常清单缺少活动条目或 ZIP 加载失败时仍报错，不回退旧缓存。
活动页面与进行中的 Prefab 预加载持有资源引用。新哈希可先下载，但使用中的 Bundle 保持有效，引用释放后下次加载才切换。切换时清理本 Bundle 的旧内存资源，不调用全局清缓存。
只有一份本次客户端支持的接入名单；未来接入其他活动时添加 Bundle 名、接入其开放判断和页面引用生命周期，再完整构建。

百人赛五包作为一个依赖组：retainGroup("cloudRise") 只保留引用，不发起请求；prepareGroup 在原版本检查位置选择公共清单，不下载 ZIP。页面及在途加载持有期间固定该清单，即使返回前台也不会混用新公共美术和旧页面。所有引用释放后，下次资源检查可选新清单；依赖页先于公共美术释放，未打开的阶段仍不下载。离线时只允许使用与上次保存的组清单一致且校验通过的缓存，缺包就失败。

黄金矿工沿用点击入口、每日提醒、结算通知的加载时机。关闭页面后等待在途主面板、说明、结算 Prefab 回调结束及节点销毁，再释放引用；不自行调用 releaseAll/removeBundle。

从旧版本迁移

packages/cloud-rise-package/main.js 不再注册构建钩子；旧打包工具仅保留供维护旧发布使用。新构建会移除旧 cloud-rise-package 启动注入以及已迁移活动的旧 subpackage 声明。assets/cloud_rise/version.json 不再控制新客户端资源版本，无需递增。

首次迁移必须完整构建并发布新微信客户端，不能只在旧构建上运行 pack。服务器保留旧 remote/cloud_rise/version.json 及原目录服务旧客户端，不用新发布覆盖它们。旧 Cocos 文件缓存由引擎管理，不全局清理；新 ZIP 缓存独立保存。

业务接口请求时机

时机	activityConfig/list
登录成功	请求一次
登录后的首次首页	复用登录中的请求或已取得结果
从关卡等页面返回首页	请求一次，刷新通关后的解锁条件
后台切回前台（包括关卡内）	请求一次；首页与全局监听共享请求
抽奖、领奖、支付确认成功	不请求；金字塔刷新 pyramid/api action:info
首页持续停留、倒计时变化	不请求，按服务器校准时间本地判断
点击入口、资源预加载	复用日程，不额外请求列表

首次首页若登录查询失败或结果已失效，允许补取一次；在途请求始终合并。账号或环境变化清空个人日程，资源仍按资源服务器隔离，不按账号重复下载。

本地验证

node --test tools/test-activity-bundles.cjs tools/test-activity-resource-integration.cjs tools/test-pyramid-resource-loader.cjs
node --test tools/test-cloud-rise-bundles.cjs tools/test-cloud-rise-prefab.cjs tools/test-cloud-rise-package.cjs
node --test tools/test-activity-schedule.cjs tools/test-pyramid-entry.cjs tools/test-pyramid-home-reminder.cjs
node tools/check-pyramid-types.cjs HEAD

覆盖确定性 ZIP、SHA-256、按需下载、缓存命中及修复、下载/解压失败保留旧包、多活动/并发共享清单、环境隔离、前台新周期、旧请求延迟及活动页面持有期间更新。发布前还需在微信开发者工具与真机核对 CDN 配置和本地文件系统加载；Node 测试不能代替微信设备验证。

7.9 KiB Raw Blame History Unescape Escape