94 lines
6.2 KiB
Markdown
94 lines
6.2 KiB
Markdown
# 百人赛远程资源：简单版本检查与按需缓存
|
||
|
||
## 目录与版本
|
||
|
||
cloud_rise_home 保留在主包。art、matching、stage1、stage2、stage3 为五个独立远程 Bundle，父目录 assets/cloud_rise 是普通目录。源 assets/cloud_rise/version.json 只保存一个共同的版本号：
|
||
|
||
~~~json
|
||
{"version":"1.0.0"}
|
||
~~~
|
||
|
||
修改资源时递增这个版本，然后完整构建。远程服务器使用固定目录，没有 ZIP、版本子目录或 manifest.json：
|
||
|
||
~~~text
|
||
remote/cloud_rise/
|
||
version.json
|
||
art/
|
||
config.json
|
||
import/...
|
||
native/...
|
||
matching/
|
||
config.json
|
||
import/...
|
||
native/...
|
||
stage1/...
|
||
stage2/...
|
||
stage3/...
|
||
~~~
|
||
|
||
各 Bundle 仅包含实际需要的 import/native 目录。构建扩展将 Creator 的配置入口统一为 config.json，并在其中写入 cloudRiseVersion，用来识别 CDN 错误地返回其他版本配置的情况。资源 UUID、依赖与图片/预制体文件名保持不变，不需要手动编辑配置文件。
|
||
|
||
## 运行流程
|
||
|
||
1. 活动需要准备资源时，集中请求 version.json，和同一 CDN 地址的本地版本记录对比。
|
||
2. 同版本使用相同资源地址和缓存键；没有缓存的文件才下载。
|
||
3. 版本不同，后续文件请求改用新版本参数，旧缓存不再命中。资源按需下载并由 Cocos 缓存；不清空其他玩法缓存，也不一次性下载三个 stage。
|
||
4. 版本查询失败时，有本地成功版本记录则尝试复用对应缓存；没有则报错，允许下次重试。
|
||
5. 同次游戏启动固定所选版本，避免正在匹配或切阶段时更换资源。下次冷启动重新检查。
|
||
|
||
例如请求地址：
|
||
|
||
~~~text
|
||
https://cdn.pay.nika4games.com/remote/cloud_rise/version.json?_t=时间戳
|
||
https://cdn.pay.nika4games.com/remote/cloud_rise/art/config.json?v=1.0.0
|
||
https://cdn.pay.nika4games.com/remote/cloud_rise/art/native/...png?v=1.0.0
|
||
https://cdn.pay.nika4games.com/remote/cloud_rise/stage1/import/...json?v=1.0.0
|
||
~~~
|
||
|
||
参数不仅添加到 version.json 或配置文件，也覆盖百人赛的合并 JSON、预制体与图片等资源。其他玩法 URL 不变。
|
||
|
||
本地 cloud_rise_bundle_version_v2 保存 baseUrl、version，在 Bundle 配置成功加载并校验版本后写入。它代表当前可用的资源版本，不代表五个 Bundle 已全部下载。版本检查不触发报名。
|
||
|
||
Cocos 原生 cacheManager 管理磁盘缓存，资源的完整 URL 是缓存键。版本变化后旧缓存逻辑失效，旧文件交给引擎缓存管理，不手动删除全部游戏缓存。缓存由引擎异步写入，用户清理缓存或容量清理后可能重新下载。Bundle/Prefab 在本次运行内另外复用 Service 的加载任务；失败清除对应任务，允许重试。
|
||
|
||
## 页面加载时机
|
||
|
||
- 活动可参与时，先准备 home 和版本信息，再准备 art、matching。
|
||
- 点击开始时，同时准备 matching 和目标 stage；匹配页准备好就显示。
|
||
- 匹配页显示后立即加入一个随机默认头像，此后每 0.4 秒加入一个模拟头像，人数最多到 99/100。目标 stage 就绪后请求 prepare_match；响应成功后保留模拟头像，从真实对手中补足剩余人数，confirm_match 成功才显示 100/100，等待点击继续。模拟资料只用于页面展示，不写入比赛数据。
|
||
- 匹配网络请求沿用 POST 的 5 秒超时，网络错误最多重试 5 次、间隔 3 秒，保持原 matchId。重试耗尽后关闭首页活动弹窗或从局内返回 HomeScene；未确认操作保留在原同步队列中供后续恢复。业务拒绝不做网络重试。
|
||
- 查看进行中的挑战或结算时，只准备当前 stage；结算已包含在 stage 内。
|
||
- loadBundle 加载配置和本地脚本，预制体及其图片随后按依赖加载，不等于下载该目录的所有文件。
|
||
|
||
依赖加载顺序仍为 home → art → 目标页面。胜负结算和活动接口逻辑不变。
|
||
|
||
## 构建与上传
|
||
|
||
1. 修改资源后递增 assets/cloud_rise/version.json。不要用同一版本发布不同内容。
|
||
2. 重启 Creator，使构建扩展生效；五个子 Bundle 的微信配置保持远程、合并所有 JSON，父目录不勾选 Bundle。
|
||
3. 开启 MD5 Cache，完整构建微信小游戏。扩展不需要安装 ZIP 依赖。
|
||
4. 常规构建的发布目录是 build/wechatgame-cloud-rise/remote/cloud_rise/。
|
||
5. 将 art、matching、stage1、stage2、stage3 上传到服务器相同目录，确认可访问后，最后上传 version.json。扩展只生成文件，不执行上传。
|
||
6. 更新微信代码包并测试。构建目录中的 remote 和旧百人赛 subpackages 已排除出微信代码上传；本地 src/scripts/<bundle>/index.js 和 ccRequire.js 必须保留。
|
||
|
||
version.json 应禁用 CDN 缓存。资源 CDN 缓存键需要包含 v 参数；固定 config.json 被覆盖时也应刷新其 CDN 缓存。参数不能替代服务器正确的缓存配置。
|
||
|
||
固定目录覆盖不保留服务器历史版本。正在运行的旧会话可以继续使用已缓存内容；若还未加载的 Bundle 已被服务器替换，会因版本不一致而报错，重新启动后使用新版本。发布时先资源、后 version.json，可缩短这一窗口；本方案不提供多版本同时服务或跨客户端兼容发布。
|
||
|
||
只更新 version.json 而没有上传对应资源时，加载器会拒绝版本不符的配置并移除该错误缓存，服务器资源修正后可以重试。图片等文件仍保留 Creator 的 MD5 文件名。
|
||
|
||
组件脚本、home、公共字体或其他本地依赖变化时，需要同时发布新的小游戏代码包；远程 Bundle 只提供资源。
|
||
|
||
## 代码与验证
|
||
|
||
- packages/cloud-rise-package/pack.js：生成固定发布目录与配置。
|
||
- packages/cloud-rise-package/runtime.js：版本检查、请求参数、缓存版本记录。
|
||
- assets/Script/module/Config/CloudRiseService.ts：活动预加载、Bundle 依赖顺序与任务复用。
|
||
- assets/cloud_rise_home/scripts/CloudRisePanel.ts：匹配页面和目标阶段的准备时机。
|
||
|
||
~~~powershell
|
||
node --test tools/test-cloud-rise-package.cjs tools/test-cloud-rise-bundles.cjs tools/test-cloud-rise.cjs
|
||
~~~
|
||
|
||
发布后检查首次加载、同版本缓存、修改版本后的 JSON/图片更新、stage 独立加载、断网缓存复用及下载失败重试。
|