cocos-creator-hotupdate

Cocos Creator 热更新

何时用

• 需要在不重新发版到应用商店的前提下更新游戏脚本、资源或配置时。
• 配置 CDN 服务器上的 project.manifest / version.manifest，或排查热更新失败/资源不一致问题时。
• 热更新后游戏仍加载旧资源，或搜索路径设置不当导致热更内容无法生效时。
• 热更异常导致本地热更目录数据损坏，需要实现回滚兜底方案时。

核心规则

1. manifest 配置：版本号与资源 MD5 必须与实际文件一致

规则： project.manifest 里每个资源条目的 MD5 值必须与服务器上实际文件的 MD5 对应；version.manifest 的版本号在每次发布热更时必须递增；两个 manifest 文件本身不得被 CDN 长期缓存（Cache-Control: no-cache 或极短 TTL）。

为什么： 手写或脚本生成 manifest 时最常见的错误是"构建后忘记重新生成 manifest"——资源 MD5 还是上一次构建的值，与服务器实际文件不匹配。AssetsManager 对比 MD5 时发现一致，认为不需要更新，结果新资源从未被下载，玩家看到的是旧内容但没有任何报错，开发者以为热更成功。另一个陷阱：CDN 把 version.manifest 缓存了 24 小时，服务器上版本号已经更新，客户端拿到的还是旧版本号，不触发更新流程，线上问题持续数小时才被发现。

怎么做：

• 构建流程集成 jsb-link/res 目录的 MD5 计算脚本，每次构建自动生成 manifest，禁止手写。
• Creator 官方提供了 version-generator.js 工具（位于引擎目录），CI/CD 流程在构建后自动调用。
• CDN 配置：project.manifest 和 version.manifest 设置 Cache-Control: no-store 或 max-age=60。
• 发布前用 curl -I https://cdn.example.com/version.manifest 确认响应头无长期缓存。
• 版本号使用时间戳或语义化版本，绝不复用旧版本号（热更服务器有旧版本号缓存时会跳过更新）。

---

2. 用 AssetsManager 走引擎热更流程，监听全部关键事件

规则： 必须监听 UPDATE_PROGRESSION（进度）、ALREADY_UP_TO_DATE（已最新）、UPDATE_FINISHED（完成）、ERROR_DOWNLOAD（下载失败）、ERROR_VERIFY（校验失败）等事件，在每个错误事件里记录日志并作出对应处理，不能只监听 UPDATE_FINISHED 就认为热更逻辑完整。

为什么： 只监听成功事件是 AI 生成热更代码时最普遍的问题：assetManager 的事件码有十余个，AI 通常只生成 UPDATE_FINISHED 的处理，其余全部忽略。结果：网络慢导致部分文件下载超时（ERROR_DOWNLOAD）没有触发重试，用户停在进度条 90% 永久卡死；资源下载后文件损坏（ERROR_VERIFY）没有删除损坏文件并重试，下次启动直接崩溃。ERROR_FAILED_DECOMPRESS 在 Android 低版本上尤其常见，忽略它会导致 zip 格式 bundle 无法解压，表现为进入某个功能模块时白屏。

怎么做：

import { native } from "cc";

export class HotUpdateManager {
    private _am: native.AssetsManager | null = null;
    private _updating = false;

    init(manifestPath: string, storagePath: string) {
        if (!native.AssetsManager) return; // 非原生平台跳过
        this._am = new native.AssetsManager(manifestPath, storagePath);
        this._am.setVerifyCallback((filePath, asset) => {
            // ✅ 可在此自定义校验逻辑（默认 MD5 校验已够用，返回 true 表示通过）
            return true;
        });
    }

    checkUpdate(): Promise<boolean> {
        return new Promise((resolve) => {
            if (!this._am) { resolve(false); return; }
            this._am.setEventCallback((event) => {
                const code = event.getEventCode();
                const EventCode = native.AssetsManager.EventCode;
                if (code === EventCode.ALREADY_UP_TO_DATE) {
                    resolve(false); // 无需更新
                } else if (code === EventCode.NEW_VERSION_FOUND) {
                    resolve(true); // 有新版本
                } else if (code === EventCode.ERROR_DOWNLOAD_MANIFEST ||
                           code === EventCode.ERROR_PARSE_MANIFEST) {
                    console.error("manifest 获取失败:", event.getMessage());
                    resolve(false); // 降级：当做无更新处理
                }
            });
            this._am.checkUpdate();
        });
    }

    update(onProgress: (percent: number) => void): Promise<void> {
        return new Promise((resolve, reject) => {
            if (!this._am || this._updating) return;
            this._updating = true;
            const EventCode = native.AssetsManager.EventCode;
            this._am.setEventCallback((event) => {
                const code = event.getEventCode();
                switch (code) {
                    case EventCode.UPDATE_PROGRESSION:
                        onProgress(event.getPercent());
                        break;
                    case EventCode.UPDATE_FINISHED:
                        this._updating = false;
                        resolve();
                        break;
                    case EventCode.ERROR_DOWNLOAD:
                        console.error("下载失败:", event.getAssetId(), event.getMessage());
                        // ✅ 单个文件下载失败继续其他文件，全部完成后统一重试失败列表
                        break;
                    case EventCode.ERROR_VERIFY:
                        console.error("校验失败:", event.getAssetId());
                        this._am!.downloadFailedAssets(); // ✅ 重新下载校验失败的文件
                        break;
                    case EventCode.ERROR_FAILED_DECOMPRESS:
                        console.error("解压失败:", event.getMessage());
                        this._updating = false;
                        reject(new Error("decompress_failed"));
                        break;
                    case EventCode.UPDATE_FAILED:
                        this._updating = false;
                        reject(new Error(event.getMessage()));
                        break;
                }
            });
            this._am.update();
        });
    }
}