1. 引言

2. 技术背景

2.1 热更新解决的问题

• 快速修复：线上 Bug 可通过补丁包即时修复，避免商店审核周期。
• 内容迭代：运营活动、节日皮肤、新关卡可动态下发。
• 降低包体：首包仅含核心资源，其余按需下载，减少初次下载体积。
• 跨平台统一：一套热更逻辑覆盖 iOS/Android/Windows/macOS。

2.2 Cocos2dx 热更方案演进

• 早期：手动 HTTP 下载 + 文件覆盖，缺乏版本管理与校验。
• AssetsManager（Cocos2d-x 3.x）：基于 CURL 的简单版本比对与下载，功能有限。
• AssetsManagerEx（Cocos2d-x 3.10+）：引入Manifest 清单、增量更新、断点续传、文件校验（MD5/SHA1）、并发下载、失败重试。
• Creator 3.x：改用Bundle 分包与Addressables式资源加载，但底层仍可用类似机制。

2.3 热更关键技术点

• 版本清单（Manifest）：JSON 格式，记录资源路径、版本号、MD5、文件大小、依赖关系。
• 差异比对：客户端本地 Manifest 与服务器最新 Manifest 比对，生成下载列表。
• 安全校验：MD5/SHA1 校验防篡改，HTTPS 防劫持。
• 原子更新：下载完成后原子替换旧资源，避免半更新导致崩溃。
• 回滚机制：保留上一版本资源，更新失败时自动回滚。

3. 应用使用场景

4. 原理解释

4.1 热更核心流程

1. 初始化：客户端读取本地 Manifest（记录当前版本与资源信息）。
2. 版本检查：请求服务器最新 Manifest，比对版本号与文件差异。
3. 下载列表生成：筛选出需更新的文件（新增/修改/删除）。
4. 下载与校验：并发下载文件，实时校验 MD5，失败重试。
5. 原子替换：下载完成后，将临时目录文件移至正式资源目录。
6. 重启生效：部分资源（如 Lua 脚本）需重启或重新加载模块生效。

4.2 AssetsManagerEx 关键类

• AssetsManagerEx：热更管理器，负责流程控制。
• Downloader：HTTP 下载器（支持断点续传、并发）。
• Manifest：版本清单解析与比对。
• Storage：本地存储管理（创建临时目录、备份旧版本）。

5. 核心特性

• 增量更新：只下载变化的文件，节省流量与时间。
• 断点续传：网络中断后可从上次进度继续。
• 文件校验：MD5/SHA1 确保文件完整性。
• 并发下载：多线程加速大资源包更新。
• 原子操作：避免半更新状态导致崩溃。
• 回滚支持：保留上一版本，失败时自动恢复。
• 进度回调：实时反馈下载进度、速度与状态。

6. 原理流程图

flowchart TD
A[启动游戏] --> B[读取本地Manifest]
B --> C[请求服务器最新Manifest]
C --> D{版本比对}
D -- 有更新 --> E[生成下载列表]
D -- 无更新 --> F[进入游戏]
E --> G[并发下载文件]
G --> H[MD5校验]
H -- 校验失败 --> I[重试/报错]
H -- 校验成功 --> J[移至正式目录]
J --> K[更新本地Manifest]
K --> L[重启或热加载生效]
I --> M[回滚到旧版本]
M --> F

7. 环境准备

• 引擎版本：Cocos2d-x 3.10+（推荐 3.17+，AssetsManagerEx 更稳定）。
• 开发语言：C++（本文以 C++ 为例，Lua/JS 可调用 C++ 接口）。
• 服务器：提供 Manifest 与资源文件的 HTTP(S) 服务（Nginx/Apache/CDN）。
• 工具：
  • Python/Node.js 脚本生成 Manifest（遍历资源目录计算 MD5）。
  • Postman/cURL 测试接口可用性。
• 项目结构：

Project/
├── Resources/
│   ├── src/                 # 脚本与代码
│   ├── res/                 # 原始资源
│   └── version.manifest     # 初始 Manifest（打包进 APK/IPA）
├── assets_manager/          # AssetsManagerEx 源码
├── hotupdate/               # 热更逻辑封装
└── server/                  # 模拟热更服务器
    ├── project.manifest     # 最新 Manifest
    └── res/                 # 热更资源

8. 实际详细应用 代码示例实现

8.1 Manifest 生成脚本（Python 示例）

# generate_manifest.py
import os
import hashlib
import json
from datetime import datetime

def calc_md5(file_path):
    md5 = hashlib.md5()
    with open(file_path, 'rb') as f:
        for chunk in iter(lambda: f.read(4096), b''):
            md5.update(chunk)
    return md5.hexdigest()

def generate_manifest(res_dir, output_file):
    manifest = {
        "packageUrl": "http://192.168.1.100/hotupdate/res/",  # 资源服务器地址
        "remoteVersionUrl": "http://192.168.1.100/hotupdate/project.manifest",
        "version": "1.0.1",
        "engineVersion": "Cocos2d-x v3.17",
        "assets": {}
    }
    for root, dirs, files in os.walk(res_dir):
        for file in files:
            if file.startswith('.'): continue
            full_path = os.path.join(root, file)
            rel_path = os.path.relpath(full_path, res_dir).replace('\\', '/')
            size = os.path.getsize(full_path)
            md5 = calc_md5(full_path)
            manifest["assets"][rel_path] = {
                "md5": md5,
                "size": size,
                "downloadState": "none"
            }
    with open(output_file, 'w', encoding='utf-8') as f:
        json.dump(manifest, f, indent=2, ensure_ascii=False)
    print(f"Manifest generated: {output_file}")

if __name__ == "__main__":
    generate_manifest("./server/res", "./server/project.manifest")

8.2 热更管理封装（C++）

// HotUpdateManager.h
#pragma once
#include "cocos2d.h"
#include "extensions/assets-manager/AssetsManagerEx.h"

USING_NS_CC;
using namespace cocos2d::extension;

class HotUpdateManager {
public:
    static HotUpdateManager* getInstance();
    void checkUpdate(const std::string& versionPath, const std::string& storagePath);
    void onUpdateProgress(double percent, double kbPerSec, const std::string& msg);
    void onUpdateFinished();
    void onUpdateFailed(const std::string& reason);

private:
    HotUpdateManager();
    ~HotUpdateManager();
    void createDownloadDir(const std::string& path);
    std::string _storagePath;
    AssetsManagerEx* _am;
    EventListenerCustom* _eventListener;
};

// HotUpdateManager.cpp
#include "HotUpdateManager.h"
#include "network/HttpClient.h"

HotUpdateManager* HotUpdateManager::_instance = nullptr;

HotUpdateManager* HotUpdateManager::getInstance() {
    if (!_instance) {
        _instance = new HotUpdateManager();
    }
    return _instance;
}

HotUpdateManager::HotUpdateManager() : _am(nullptr), _eventListener(nullptr) {}

HotUpdateManager::~HotUpdateManager() {
    if (_am) {
        _am->release();
    }
    if (_eventListener) {
        Director::getInstance()->getEventDispatcher()->removeEventListener(_eventListener);
    }
}

void HotUpdateManager::checkUpdate(const std::string& versionPath, const std::string& storagePath) {
    _storagePath = FileUtils::getInstance()->getWritablePath() + storagePath + "/";
    createDownloadDir(_storagePath);

    // 本地 Manifest 路径（首次使用包内自带的 version.manifest）
    std::string localManifestPath = FileUtils::getInstance()->fullPathForFilename("version.manifest");
    if (!FileUtils::getInstance()->isFileExist(localManifestPath)) {
        // 若包内没有，则用服务器 Manifest 作为初始
        localManifestPath = _storagePath + "project.manifest";
    }

    _am = AssetsManagerEx::create(versionPath, localManifestPath, _storagePath);
    _am->retain();

    _eventListener = EventListenerCustom::create(EVENT_RESOURCE_PROGRESS, [this](EventCustom* event) {
        auto evt = (ResourceProgress*)event->getUserData();
        this->onUpdateProgress(evt->getPercent(), evt->getSpeed(), evt->getMessage());
    });
    Director::getInstance()->getEventDispatcher()->addEventListenerWithFixedPriority(_eventListener, 1);

    _eventListener = EventListenerCustom::create(EVENT_RESOURCE_FINISHED, [this](EventCustom* event) {
        this->onUpdateFinished();
    });
    Director::getInstance()->getEventDispatcher()->addEventListenerWithFixedPriority(_eventListener, 1);

    _eventListener = EventListenerCustom::create(EVENT_RESOURCE_FAILED, [this](EventCustom* event) {
        auto evt = (ResourceError*)event->getUserData();
        this->onUpdateFailed(evt->getCURLErrorString());
    });
    Director::getInstance()->getEventDispatcher()->addEventListenerWithFixedPriority(_eventListener, 1);

    _am->update();
}

void HotUpdateManager::createDownloadDir(const std::string& path) {
    if (!FileUtils::getInstance()->isDirectoryExist(path)) {
        FileUtils::getInstance()->createDirectory(path);
    }
}

void HotUpdateManager::onUpdateProgress(double percent, double kbPerSec, const std::string& msg) {
    CCLOG("Progress: %.2f%% Speed: %.2fKB/s Msg: %s", percent, kbPerSec, msg.c_str());
    // 可更新 UI 进度条
}

void HotUpdateManager::onUpdateFinished() {
    CCLOG("Update finished.");
    // 更新成功后，将临时 Manifest 替换为本地版本 Manifest
    std::string tempManifest = _storagePath + "project.manifest";
    std::string localManifest = FileUtils::getInstance()->getWritablePath() + "project.manifest";
    FileUtils::getInstance()->renameFile(_storagePath, "project.manifest", localManifest);
    // 重启或重新加载资源
}

void HotUpdateManager::onUpdateFailed(const std::string& reason) {
    CCLOG("Update failed: %s", reason.c_str());
    // 可尝试回滚或提示用户
}

8.3 在 AppDelegate 中集成热更

// AppDelegate.cpp
#include "HotUpdateManager.h"

bool AppDelegate::applicationDidFinishLaunching() {
    // ... 引擎初始化
    // 热更检查
    std::string versionUrl = "http://192.168.1.100/hotupdate/project.manifest";
    std::string storagePath = "hotupdate";
    HotUpdateManager::getInstance()->checkUpdate(versionUrl, storagePath);
    return true;
}

9. 运行结果与测试步骤

9.1 运行结果

• 首次启动：下载差异文件，进度条从 0% 到 100%。
• 校验失败：自动重试 3 次后提示失败，保留旧资源。
• 更新成功：本地 Manifest 更新，重启后加载新资源（如 Lua 脚本、新图片）。

9.2 测试步骤

1. 启动服务器，放置 project.manifest与 res/资源。
2. 修改服务器资源或 Manifest 版本号，模拟新版本。
3. 客户端启动，观察日志与进度回调。
4. 断网测试：验证断点续传与失败重试。
5. 篡改文件 MD5：验证校验失败逻辑。
6. 回滚测试：删除下载目录，验证自动恢复旧资源。

10. 部署场景

• 开发期：本地服务器 + 版本号频繁迭代，快速验证热更流程。
• 测试服：独立 CDN，模拟真实网络环境，进行压力与弱网测试。
• 生产环境：HTTPS + CDN 分发，Manifest 与资源加签防篡改，分渠道/分地区部署。

11. 疑难解答

12. 未来展望与技术趋势

• 增量 Patch：基于 bsdiff/xdelta 生成二进制差分，进一步减少下载量。
• 资源加密：下载时解密，运行时加载，防止资源被提取。
• 热更与 Bundle 结合：Cocos Creator 3.x 的 Bundle 机制可与 AssetsManagerEx 互补。
• 云控开关：热更与 AB 测试、功能灰度结合，实现精细化运营。
• WebAssembly 逻辑更新：C++ 逻辑编译为 Wasm，热更 Wasm 模块。

13. 总结