bit-hotupdate

Cocos Creator 热更新系统封装，提供简单易用的热更新接口。

简介

bit-hotupdate 是基于 Cocos Creator 的热更新系统封装，提供增量更新和版本管理功能。支持 Android 和 iOS 原生平台，简化了热更新的使用流程。

核心特性：

• 🔄 增量更新，只下载变化的文件
• 📦 自动版本管理和对比
• ⚡ 实时下载进度跟踪
• 🛡️ 完善的错误码和重试机制
• 🎯 简洁的 API 设计
• 📱 支持 Android 和 iOS 原生平台

安装

npm install @gongxh/bit-hotupdate

使用说明

热更新管理器 (HotUpdateManager)

全局单例，负责热更新配置和实例管理。

初始化配置：

• getInstance() - 获取单例实例
• init(config) - 初始化热更新系统
  • config.manifestUrl - 本地 manifest 文件路径
  • config.writablePath - 热更新资源存储路径

实例管理：

• create() - 创建热更新实例
• resVersion - 获取当前资源版本号

热更新实例 (HotUpdate)

执行具体的更新操作。

检查更新：

• checkUpdate() - 检查是否有新版本
  • 返回 Promise<ICheckUpdatePromiseResult>
  • 成功：返回新版本信息和文件大小
  • 失败：返回错误码和消息

开始更新：

• startUpdate(options) - 开始下载更新
  • options.skipCheck - 是否跳过检查（默认 false）
  • options.progress - 进度回调 (downloadedKB, totalKB) => void
  • options.complete - 完成回调 (code, message) => void

重试更新：

• retryUpdate() - 重试失败的资源下载

属性：

• resVersion - 当前资源版本号

状态码 (HotUpdateCode)

定义了所有可能的更新状态：

成功状态：

• Succeed (0) - 更新成功

特殊状态：

• PlatformNotSupported (-1000) - 平台不支持（非原生平台）
• NotInitialized (-1001) - 未初始化
• LatestVersion (-1002) - 已是最新版本
• Updating (-1003) - 更新中

错误状态：

• LoadManifestFailed (-1004) - 加载本地 manifest 失败
• ParseManifestFailed (-1005) - 解析 manifest 文件失败
• LoadVersionFailed (-1006) - 下载 version.manifest 失败
• ParseVersionFailed (-1007) - 解析 version.manifest 失败
• UpdateFailed (-1008) - 更新失败（可重试）
• UpdateError (-1009) - 更新错误
• DecompressError (-1010) - 解压错误

Manifest 文件

热更新需要两个 manifest 文件：

1. project.manifest - 完整的资源清单

   • 包含所有资源的 MD5 和大小
   • 用于计算需要下载的文件

2. version.manifest - 轻量级版本文件

   • 只包含版本信息
   • 用于快速检查版本

典型使用流程

1. 初始化 - 游戏启动时初始化 HotUpdateManager
2. 创建实例 - 创建 HotUpdate 实例
3. 检查更新 - 调用 checkUpdate() 检查新版本
4. 提示用户 - 显示更新对话框
5. 开始更新 - 用户确认后调用 startUpdate()
6. 显示进度 - 更新进度条
7. 处理结果 - 更新成功后重启游戏

服务端配置

目录结构：

hotupdate/
├── version.manifest
├── project.manifest
├── assets/
└── src/

Nginx 配置要点：

• 允许跨域请求
• manifest 文件禁止缓存
• 支持 Range 请求（断点续传）

详细 API 请查看 bit-hotupdate.d.ts 类型定义文件。

依赖

• @gongxh/bit-core - 核心功能

许可证

MIT License

作者

bit老宫 (gongxh)
邮箱: [email protected]

源码仓库

• GitHub
• npm