1. 项目概述为什么热更新是Cocos项目开发的“刚需”做Cocos Creator项目尤其是手游最怕什么怕的不是代码写不出来而是版本发出去之后发现一个致命Bug或者想紧急加个活动。这时候如果让玩家重新下载几百兆甚至上G的安装包流失率能高得让你心碎。热更新就是解决这个痛点的“后悔药”和“快速通道”。它允许你在不重新发布应用商店版本、不要求用户下载完整包的情况下将新的游戏资源如图片、音频、配置表、脚本甚至部分逻辑代码动态地推送到玩家设备上。我经历过不止一次因为没有完善的热更新机制而导致的运营事故。一次是某个节日活动资源包漏打了客户端直接白屏另一次是线上出了一个严重的数值平衡Bug只能眼睁睁看着玩家抱怨等着一周后渠道审核通过新包。从那以后我就把热更新的稳定性和易用性提到了项目基础架构的最高优先级。对于使用Cocos Creator的团队来说掌握一套成熟、可靠的热更新方案不是“加分项”而是“生存技能”。它直接关系到你的项目能否快速迭代、灵活运营以及应对线上突发状况的能力。Cocos Creator官方提供了基于Asset Manager和Manifest机制的热更新解决方案这套方案已经比较成熟能够覆盖从资源到脚本的大部分更新需求。但官方文档更像是一份API说明书很多在实际部署中会遇到的“坑”——比如版本号管理策略、差异更新与全量更新的抉择、更新失败的回滚、以及如何与自己的服务器对接——都需要开发者自己去摸索和填平。这篇指南就是结合我多个项目的实战经验带你从零开始搭建一套可投入生产的Cocos Creator热更新系统并重点分享那些文档里不会写的“避坑指南”。2. 热更新核心原理与架构设计2.1 官方热更新流程拆解要玩转热更新首先得理解它的“心脏”是如何跳动的。Cocos Creator的热更新核心依赖于两个东西资源清单Manifest和资源管理模块Asset Manager。资源清单Manifest这是一个JSON文件你可以把它想象成游戏资源的“户籍档案”。里面记录了当前版本所有需要热更的资源文件的详细信息包括版本号比如1.0.1。这是热更新的灵魂通过比较本地和远程的版本号来决定是否需要以及如何更新。文件列表每个资源文件的相对路径、MD5哈希值用于校验文件完整性、文件大小。包名通常用于区分不同的资源包比如main包、sub包。资源管理模块Asset Manager这是Cocos Creator内置的、功能强大的资源加载器。在热更新场景下它的职责是读取本地Manifest游戏启动时先加载打包在包体内的、最初的Manifest。检查远程Manifest向你的版本服务器请求最新的Manifest文件。对比分析将远程Manifest与本地Manifest进行对比生成一个需要下载、删除或更新的文件列表。执行更新根据列表从远程资源服务器通常是CDN下载新增或变化的文件到设备的持久化数据目录如wx.env.USER_DATA_PATH下。切换版本下载并校验完成后将本地记录的当前版本指向新的远程版本号。此后Asset Manager在加载资源时会优先从热更新目录查找找不到再回退到包体内置资源。这个流程听起来清晰但其中有几个关键设计点决定了你方案的健壮性版本号设计我强烈建议使用三段式如主版本.热更版本.资源版本。主版本对应商店大包更新热更版本是每次发布热更递增资源版本可以用时间戳或哈希确保唯一性。这比单纯一个数字包含更多信息。Manifest生成Cocos Creator构建项目时在build目录下会自动生成对应平台的Manifest文件如project.manifest。你需要做的就是把这个文件和你构建出的src、res等资源文件夹一起上传到你的服务器。切记构建时务必勾选“MD5 Cache”选项这样生成的文件名会带哈希值既能解决缓存问题又能方便进行差异对比。2.2 服务器端架构选型官方示例通常用一个简单的Node.js或Nginx静态服务器来托管资源这对于Demo足够了但对于线上项目远远不够。一个生产环境的热更新后端至少需要考虑以下几点资源托管CDN这是必须的。千万不要用自己简陋的应用服务器提供资源下载。将热更资源src,res等放到阿里云OSS、腾讯云COS等对象存储服务并开启CDN加速。这能极大提升全国乃至全球玩家的下载速度并减轻你源站的压力。费用极低但体验提升巨大。版本管理服务器Version Server这个服务器的作用是提供最新的Manifest文件下载地址和版本信息。它可以是极轻量级的一个简单的API接口即可。例如// 假设接口GET /version/check?platformandroidcur_version1.0.0 { code: 0, data: { hasUpdate: true, isSilent: false, // 是否静默更新小资源包 isMandatory: false, // 是否强制更新大版本 packageUrl: https://your-cdn.com/hotupdate/v1.0.1/, // 资源根URL remoteManifestUrl: https://your-cdn.com/hotupdate/v1.0.1/project.manifest, remoteVersionUrl: https://your-cdn.com/hotupdate/v1.0.1/version.manifest, version: 1.0.1, engineVersion: 2.4.3, // 可选匹配引擎版本 updateMsg: 修复了若干BUG优化了游戏体验。 // 更新提示文案 } }这个服务器需要你自行开发可以用任何你熟悉的后端语言Node.js, Python, Go等。它的数据库里只需要维护一张表记录每个平台iOS, Android的最新版本号、资源包URL、更新说明等。安全与防盗链虽然资源是静态的但建议为CDN资源配置Referer白名单或时间戳签名防盗链防止资源被恶意刷流量。版本管理服务器的接口也可以考虑简单的Token校验。注意很多团队初期会偷懒把Manifest文件也放在CDN客户端直接写死CDN的一个Manifest路径。这非常危险一旦你需要回滚版本或者某个资源包有问题想快速切换你将无法控制客户端去拉取哪个Manifest。版本管理服务器是你的“指挥中枢”必须掌握在自己手里。2.3 客户端更新策略设计客户端逻辑是整个流程的“执行者”其策略设计直接影响用户体验。更新触发时机启动时检查最常用。游戏启动后先显示一个Loading界面或Logo在此后台进行更新检查和解压。手动检查在游戏设置中提供“检查更新”按钮。定时检查在游戏运行过程中定期如每24小时在后台悄悄检查一次。更新流程UI/状态设计一个友好的更新界面应该包含更新提示弹窗当检测到非静默更新时弹出展示版本更新内容、包大小并提供“立即更新”和“稍后再说”选项非强制更新时。下载进度条清晰显示下载进度文件数/总文件数已下载大小/总大小。断点续传Asset Manager本身不支持但可以通过监听下载失败事件记录已下载文件列表下次从断点开始。对于大版本更新这个功能能有效提升成功率。失败重试与回滚网络失败、文件校验失败时应提供明确错误提示和重试按钮。在极端情况下如新版本Manifest本身有问题应能回退到上一个可用版本。静默更新与强制更新静默更新适用于更新量很小如几百KB的配置表或脚本在玩家无感知的情况下后台下载并应用。通常可以设定一个大小阈值如2MB。强制更新当热更版本不兼容旧版本如数据结构大变或涉及重大安全修复时必须强制玩家更新到最新版本才能进入游戏。此时“稍后再说”按钮应隐藏或点击后退出游戏。3. 一步步实现热更新模块3.1 项目配置与构建准备首先在Cocos Creator中做好基础配置。开启MD5 Cache在项目 - 项目设置 - 构建发布中找到“MD5 Cache”选项并勾选。这一步至关重要它确保了构建出的资源文件名称会包含其内容的哈希值从而实现精确的差异对比和缓存管理。构建路径与名称在构建面板中注意“发布路径”。建议构建到一个固定的、清晰的目录比如../publish/{platform}。这样方便写脚本自动上传。构建出的结果中src、res、project.manifest、version.manifest是我们需要关心的核心文件。自定义构建模板可选但推荐为了更灵活地控制热更新初始化逻辑你可以自定义构建模板。在项目根目录创建build-templates文件夹然后按照build-templates/{platform}的目录结构放置你修改过的main.js或game.js。在这里你可以插入自己的版本检查逻辑甚至先于游戏启动执行一个简单的更新器。3.2 编写核心热更新管理器HotUpdateManager我们将创建一个单例类来统一管理所有热更新逻辑。这是整个客户端更新的“大脑”。// HotUpdateManager.ts import { AssetManager, director, game } from cc; import { MessageBox } from ./MessageBox; // 假设你有一个UI弹窗组件 import { VersionServer } from ./VersionServer; // 与版本服务器通信的模块 export class HotUpdateManager { private static _instance: HotUpdateManager null; private _am: AssetManager.Bundle null; private _localManifest: AssetManager.Manifest null; private _remoteManifest: AssetManager.Manifest null; private _storagePath: string ; // 热更新资源存储路径 private _updateCallback: (finished: boolean, message?: string) void null; public static get instance(): HotUpdateManager { if (!this._instance) { this._instance new HotUpdateManager(); } return this._instance; } private constructor() { this._storagePath ${game.localStoragePath}/hotupdate-assets/; // 初始化AssetManager this._am new AssetManager.Bundle(); // 设置本地资源搜索路径优先热更目录再回退包内 this._am.baseDir this._storagePath; this._am.on(AssetManager.Event.ERROR, this.onError, this); } // 启动更新检查 public async checkAndUpdate(): Promisevoid { // 1. 加载本地Manifest (打包在包体内的初始版本) await this.loadLocalManifest(); // 2. 向版本服务器请求更新信息 const updateInfo await VersionServer.instance.checkVersion(this._localManifest.version); if (!updateInfo.hasUpdate) { this._updateCallback?.(true, 已是最新版本); return; } // 3. 根据更新信息决定更新方式静默/提示/强制 this.handleUpdateStrategy(updateInfo); } private async loadLocalManifest(): Promisevoid { // 从application包内加载初始manifest // 注意这里加载的是构建时生成的、随包发布的那个manifest await this._am.loadManifest(project.manifest); this._localManifest this._am.manifest; console.log(本地版本: ${this._localManifest.version}); } private handleUpdateStrategy(info: any): void { if (info.isMandatory) { // 强制更新直接弹窗只能选“更新” MessageBox.show(发现新版本${info.version}必须更新后才能继续游戏。\n\n更新内容${info.updateMsg}, 强制更新, [确定], (idx) { this.startDownload(info); }); } else if (info.isSilent this.calculateUpdateSize(info) 2 * 1024 * 1024) { // 小于2MB // 静默更新后台进行 console.log(开始静默更新...); this.startDownload(info, true); } else { // 普通更新弹窗让玩家选择 const sizeStr this.formatSize(this.calculateUpdateSize(info)); MessageBox.show(发现新版本${info.version}大小约${sizeStr}。\n\n更新内容${info.updateMsg}, 版本更新, [立即更新, 稍后再说], (idx) { if (idx 0) { this.startDownload(info); } else { this._updateCallback?.(false, 用户取消更新); } }); } } private async startDownload(info: any, isSilent: boolean false): Promisevoid { // 加载远程Manifest try { await this._am.loadManifest(info.remoteManifestUrl); this._remoteManifest this._am.manifest; } catch (e) { this.onError(new Error(加载远程Manifest失败: ${e.message})); return; } // 设置资源包根路径 this._am.setBundleRoot(info.packageUrl); // 检查更新 const { totalBytes, totalFiles } this._am.checkUpdate(); if (totalFiles 0) { console.log(没有文件需要更新); this.onUpdateSuccess(); return; } console.log(需要更新 ${totalFiles} 个文件总计 ${this.formatSize(totalBytes)}); if (!isSilent) { // 显示带进度条的UI this.showUpdateProgressUI(); } // 开始下载更新 this._am.update((completed, total, message) { // 更新进度回调 if (!isSilent) { this.updateProgressUI(completed, total, message); } console.log(更新进度: ${completed}/${total}, ${message}); }, this.onUpdateSuccess.bind(this), this.onError.bind(this)); } private onUpdateSuccess(): void { console.log(热更新完成); // 保存新版本信息可以存到LocalStorage // 重启游戏或刷新资源管理 director.loadScene(MainScene); // 重新加载主场景或重启游戏 this._updateCallback?.(true); } private onError(error: Error): void { console.error(热更新出错:, error); // 显示错误提示提供重试按钮 MessageBox.show(更新失败${error.message}, 错误, [重试, 跳过], (idx) { if (idx 0) { // 重新尝试 this.retryUpdate(); } else { // 跳过更新尝试用旧版本进入游戏可能功能不全 this._updateCallback?.(false, error.message); } }); } // ... 其他辅助方法如 calculateUpdateSize, formatSize, showUpdateProgressUI 等 }这个管理器封装了从检查到下载的完整流程并处理了不同的更新策略。你需要根据你的UI框架来实现MessageBox和进度条界面。3.3 服务器端部署与资源上传客户端代码写好了服务器端需要准备好。准备资源使用Cocos Creator构建项目后进入构建输出目录如build/android你会看到assets,src,res,project.manifest,version.manifest等。整个这个目录就是你这次构建的“资源包”。版本命名与目录结构我推荐在服务器CDN上使用清晰的目录结构来管理不同版本。例如https://your-cdn.com/hotupdate/ ├── v1.0.0/ (初始包理论上可以不存) ├── v1.0.1/ │ ├── project.manifest │ ├── version.manifest │ ├── assets/ │ ├── src/ │ └── res/ └── v1.0.2/ └── ...每次构建后将整个输出目录上传到以新版本号命名的文件夹下。自动化上传脚本手动上传容易出错写一个简单的Node.js脚本来自动化这个过程// upload.js const fs require(fs-extra); const path require(path); const { OSS } require(ali-oss); // 以阿里云OSS为例 const client new OSS({ /* 你的配置 */ }); const version process.argv[2] || 1.0.1; // 从命令行参数或package.json读取版本 const buildDir path.join(__dirname, ../build/web-mobile); // 你的构建目录 const remoteDir hotupdate/v${version}/; async function uploadDir(localPath, remotePrefix) { const files await fs.readdir(localPath); for (const file of files) { const localFilePath path.join(localPath, file); const stat await fs.stat(localFilePath); const remoteFilePath ${remotePrefix}${file}; if (stat.isDirectory()) { await uploadDir(localFilePath, ${remoteFilePath}/); } else { console.log(上传: ${remoteFilePath}); await client.put(remoteFilePath, localFilePath); } } } (async () { console.log(开始上传版本 ${version}...); await uploadDir(buildDir, remoteDir); console.log(上传完成); // 这里可以调用你的版本管理服务器API更新数据库中的最新版本号 })();然后通过node upload.js 1.0.1命令即可一键上传。更新版本管理服务器上传资源后调用你版本管理服务器的后台API将新版本号v1.0.1及其对应的资源包URLhttps://your-cdn.com/hotupdate/v1.0.1/写入数据库使其成为该平台的最新版本。4. 高级技巧与避坑实战指南4.1 差异更新增量更新优化默认情况下assetManager.checkUpdate()会对比本地和远程Manifest中每个文件的MD5只下载MD5不同的文件。这已经是差异更新。但要最大化其效率你还需要注意小文件合并如果项目有大量零碎的小配置文件如JSON可以考虑在构建后用一个脚本将它们打包成一个.zip或自定义的二进制包。这样Manifest里只记录一个大文件减少HTTP请求次数下载效率更高。当然客户端需要相应的解包逻辑。避免频繁更改大资源对于音频、视频、大型图集等文件一旦确定尽量避免修改。因为即使只改了一个字节MD5就全变了需要重新下载整个文件。对于这类资源版本规划要更谨慎。4.2 更新失败与回滚机制网络不稳定、存储空间不足、文件校验失败都可能导致更新中断。一个健壮的系统必须能处理这些情况。失败重试在onError回调中不要立即判定为致命错误。可以设置一个重试计数器比如3次在提示用户网络不佳的同时自动进行重试。对于下载失败的具体文件Asset Manager会记录重试时会跳过已成功的。版本回滚这是更高级的保障。思路是在成功应用一个新版本后不要立即删除旧版本的热更资源。可以保留上一个稳定版本的数据。在HotUpdateManager中每次更新成功后将当前有效的Manifest内容或版本号备份到LocalStorage。如果新版本启动后发生崩溃可通过全局异常捕获判断可以在下次启动时自动将热更目录回滚到备份的版本并提示用户更新失败已恢复至稳定版本。空间检查在开始下载前检查设备可用存储空间。可以通过fs模块在小游戏平台有相应API尝试写入一个测试文件来估算。如果空间不足提前提示用户清理避免下载到一半失败。4.3 热更新脚本JavaScript的注意事项Cocos Creator的热更新也支持更新src目录下的脚本文件。但这需要满足一个关键前提项目必须使用Asset Bundle功能并且将需要热更的脚本放在Bundle中或者将整个src作为Asset Bundle打包。具体操作在资源管理器中新建一个文件夹比如scripts。将需要热更的脚本拖入此文件夹。在资源管理器中右键点击scripts文件夹选择创建 - Asset Bundle。这会在项目设置 - Asset Bundle中创建一个新的Bundle。构建时这个Bundle会被单独打包。你可以通过配置让这个Bundle参与热更新。重要警告热更新脚本存在风险。如果新脚本有语法错误或逻辑问题可能导致游戏直接崩溃且回滚困难。因此对于脚本更新务必进行充分测试。更安全的做法是将频繁变动的逻辑放在配置表JSON中通过热更新配置表来实现逻辑变化脚本主体保持稳定。4.4 多平台与引擎版本兼容性平台差异iOS、Android、微信小游戏、字节小游戏等平台的存储路径、网络权限、文件系统API有所不同。game.localStoragePath是Cocos Creator提供的跨平台路径但在小游戏平台下载大文件可能需要使用平台特定的API如微信的wx.downloadFile和wx.getFileSystemManager。你可能需要为不同平台编写适配代码。引擎版本热更新机制在不同Cocos Creator版本间可能有细微调整。特别是从2.x升级到3.xAsset Manager API有较大变化。如果你的项目需要升级引擎热更新代码是需要重点测试和迁移的部分。在Manifest中也可以加入engineVersion字段客户端可以检查并提示玩家是否需要升级App本体。4.5 实测中的性能与体验优化点分帧下载对于超大更新包比如几百MB如果一次性让Asset Manager下载所有文件可能会造成界面卡顿。虽然Asset Manager内部有队列但我们还可以在update的回调中每下载完N个文件比如10个就主动setTimeout一下让出主线程给UI渲染实现更平滑的进度条更新。后台下载在移动端应用切换到后台时网络请求可能会被挂起或限制。你需要监听应用的生命周期事件如game.onPause在切后台时暂停下载切回来时恢复。同时在更新界面明确提示用户“请保持应用在前台”。Wi-Fi判断对于大体积更新可以检查网络环境是否为Wi-Fi。如果是蜂窝数据应弹窗提醒用户并获得确认后再开始下载避免消耗用户过多流量。预热与预加载更新完成后不要急着跳转场景。可以趁用户在“更新完成”界面点击“确定”的时机在后台预加载一些主场景的关键资源让进入游戏后的等待时间更短。5. 常见问题排查与解决方案实录即使按照指南操作在实际部署中你还是会遇到各种奇怪的问题。下面是我踩过的一些坑和解决办法。问题1更新后资源加载失败提示“找不到资源”或显示为粉色方块。可能原因A热更新存储路径权限问题。在某些Android设备上应用对内部存储空间的写入权限可能受限。排查在HotUpdateManager初始化后立即尝试在this._storagePath下创建一个测试文件看是否成功。解决如果失败可以尝试使用jsb.fileUtils.getWritablePath()来获取一个肯定可写的路径Cocos Native平台。对于小游戏平台使用其提供的文件系统API。可能原因BManifest中的路径或包根URLpackageUrl配置错误。排查检查CDN上project.manifest文件的内容查看packageUrl字段。确保这个URL拼接上资源相对路径后能直接访问到文件。例如如果packageUrl是https://cdn.com/v1.0.1/那么一张图片assets/image.png的完整URL应该是https://cdn.com/v1.0.1/assets/image.png。用浏览器打开这个链接测试一下。解决修正构建后上传的目录结构或修正packageUrl。确保构建后project.manifest里的packageUrl是相对于资源根目录的正确路径上传时保持这个相对关系。可能原因C文件MD5校验失败。文件在下载过程中损坏或服务器上的文件与Manifest中记录的MD5不符。排查监听Asset Manager的ERROR事件查看错误信息是否包含“md5 mismatch”。解决重新构建并上传资源确保构建过程一致勾选MD5 Cache。检查CDN服务是否有自动压缩或修改文件的行为如果有需要配置CDN不处理这些文件类型。问题2iOS版本更新正常但Android版本不行或反之。可能原因平台构建的差异。Cocos Creator为不同平台构建时生成的project.manifest内容可能略有不同特别是路径分隔符/vs\或平台特定字段。排查分别下载iOS和Android构建出的project.manifest用文本对比工具比较。解决确保你的版本服务器和上传脚本能正确区分不同平台的资源包。最好在服务器目录结构上就分开/hotupdate/ios/v1.0.1/和/hotupdate/android/v1.0.1/。客户端检查更新时需要上传自己的平台标识。问题3热更新后游戏逻辑没变化好像没生效。可能原因A脚本没有正确打包进热更包。如果你希望更新脚本必须确保脚本所在的目录被配置为Asset Bundle并且该Bundle被设置为“远程包”Remote Bundle在构建后会上传。排查检查构建后的src目录大小看是否包含你修改的脚本文件。检查project.manifest里的文件列表是否包含了这些.js文件。解决正确配置Asset Bundle。并在加载新场景前尝试先使用assetManager.removeBundle(脚本Bundle名)移除旧的Bundle缓存再重新加载。可能原因B缓存问题。可能是旧的资源被浏览器或引擎缓存了。排查在更新完成后彻底关闭游戏进程再重启看是否生效。解决对于Web平台可以在请求资源URL时加查询参数如?v版本号来打破缓存。对于Native平台确保热更路径 (this._storagePath) 设置正确Asset Manager确实优先从该路径加载。问题4更新进度条卡住长时间不动。可能原因A某个文件下载失败阻塞了队列。Asset Manager默认会重试但可能卡在某个环节。排查在update进度回调中打印出message参数它通常包含当前正在处理的文件名。看卡在哪个文件上。解决检查该文件在CDN上是否存在、是否可访问。可能是文件名包含特殊字符导致URL编码问题也可能是CDN节点同步延迟。增加超时和重试机制。可能原因B主线程被阻塞。如果更新过程中有同步的复杂计算或大量DOM操作可能阻塞了网络回调的执行。排查在更新时尽量减少不必要的UI渲染和逻辑运算。解决使用前面提到的“分帧下载”技巧主动让出主线程。问题5在微信小游戏等平台更新包总大小超过平台限制。背景微信小游戏对本地缓存有容量限制如50MB且单次wx.downloadFile下载也有大小限制。解决这是设计层面要考虑的。必须严格控制热更包的大小。资源精简定期清理未使用的资源压缩图片和音频。分包加载使用Cocos Creator的Asset Bundle功能将游戏按模块分成多个包。首次只加载主包其他功能包在需要时或通过热更新动态下载。增量更新确保每次更新只推送变化的文件这是基础。资源远程加载对于非即时需要的超大资源如过场动画视频可以不放在热更包里而是在游戏内通过网络直接流式加载播放。最后建立一个完善的热更新测试流程至关重要。在我的团队里每次发布热更前我们会在内部测试渠道覆盖以下测试在不同网络Wi-Fi/4G下更新、中断下载后恢复更新、磁盘空间不足时更新、更新后回退旧版本安装包验证兼容性。只有这些都通过了才会推送到生产环境。热更新是线上项目的生命线多花一点时间打磨它的稳定性和用户体验绝对物超所值。
1. 项目概述为什么热更新是Cocos项目开发的“刚需”做Cocos Creator项目尤其是手游最怕什么怕的不是代码写不出来而是版本发出去之后发现一个致命Bug或者想紧急加个活动。这时候如果让玩家重新下载几百兆甚至上G的安装包流失率能高得让你心碎。热更新就是解决这个痛点的“后悔药”和“快速通道”。它允许你在不重新发布应用商店版本、不要求用户下载完整包的情况下将新的游戏资源如图片、音频、配置表、脚本甚至部分逻辑代码动态地推送到玩家设备上。我经历过不止一次因为没有完善的热更新机制而导致的运营事故。一次是某个节日活动资源包漏打了客户端直接白屏另一次是线上出了一个严重的数值平衡Bug只能眼睁睁看着玩家抱怨等着一周后渠道审核通过新包。从那以后我就把热更新的稳定性和易用性提到了项目基础架构的最高优先级。对于使用Cocos Creator的团队来说掌握一套成熟、可靠的热更新方案不是“加分项”而是“生存技能”。它直接关系到你的项目能否快速迭代、灵活运营以及应对线上突发状况的能力。Cocos Creator官方提供了基于Asset Manager和Manifest机制的热更新解决方案这套方案已经比较成熟能够覆盖从资源到脚本的大部分更新需求。但官方文档更像是一份API说明书很多在实际部署中会遇到的“坑”——比如版本号管理策略、差异更新与全量更新的抉择、更新失败的回滚、以及如何与自己的服务器对接——都需要开发者自己去摸索和填平。这篇指南就是结合我多个项目的实战经验带你从零开始搭建一套可投入生产的Cocos Creator热更新系统并重点分享那些文档里不会写的“避坑指南”。2. 热更新核心原理与架构设计2.1 官方热更新流程拆解要玩转热更新首先得理解它的“心脏”是如何跳动的。Cocos Creator的热更新核心依赖于两个东西资源清单Manifest和资源管理模块Asset Manager。资源清单Manifest这是一个JSON文件你可以把它想象成游戏资源的“户籍档案”。里面记录了当前版本所有需要热更的资源文件的详细信息包括版本号比如1.0.1。这是热更新的灵魂通过比较本地和远程的版本号来决定是否需要以及如何更新。文件列表每个资源文件的相对路径、MD5哈希值用于校验文件完整性、文件大小。包名通常用于区分不同的资源包比如main包、sub包。资源管理模块Asset Manager这是Cocos Creator内置的、功能强大的资源加载器。在热更新场景下它的职责是读取本地Manifest游戏启动时先加载打包在包体内的、最初的Manifest。检查远程Manifest向你的版本服务器请求最新的Manifest文件。对比分析将远程Manifest与本地Manifest进行对比生成一个需要下载、删除或更新的文件列表。执行更新根据列表从远程资源服务器通常是CDN下载新增或变化的文件到设备的持久化数据目录如wx.env.USER_DATA_PATH下。切换版本下载并校验完成后将本地记录的当前版本指向新的远程版本号。此后Asset Manager在加载资源时会优先从热更新目录查找找不到再回退到包体内置资源。这个流程听起来清晰但其中有几个关键设计点决定了你方案的健壮性版本号设计我强烈建议使用三段式如主版本.热更版本.资源版本。主版本对应商店大包更新热更版本是每次发布热更递增资源版本可以用时间戳或哈希确保唯一性。这比单纯一个数字包含更多信息。Manifest生成Cocos Creator构建项目时在build目录下会自动生成对应平台的Manifest文件如project.manifest。你需要做的就是把这个文件和你构建出的src、res等资源文件夹一起上传到你的服务器。切记构建时务必勾选“MD5 Cache”选项这样生成的文件名会带哈希值既能解决缓存问题又能方便进行差异对比。2.2 服务器端架构选型官方示例通常用一个简单的Node.js或Nginx静态服务器来托管资源这对于Demo足够了但对于线上项目远远不够。一个生产环境的热更新后端至少需要考虑以下几点资源托管CDN这是必须的。千万不要用自己简陋的应用服务器提供资源下载。将热更资源src,res等放到阿里云OSS、腾讯云COS等对象存储服务并开启CDN加速。这能极大提升全国乃至全球玩家的下载速度并减轻你源站的压力。费用极低但体验提升巨大。版本管理服务器Version Server这个服务器的作用是提供最新的Manifest文件下载地址和版本信息。它可以是极轻量级的一个简单的API接口即可。例如// 假设接口GET /version/check?platformandroidcur_version1.0.0 { code: 0, data: { hasUpdate: true, isSilent: false, // 是否静默更新小资源包 isMandatory: false, // 是否强制更新大版本 packageUrl: https://your-cdn.com/hotupdate/v1.0.1/, // 资源根URL remoteManifestUrl: https://your-cdn.com/hotupdate/v1.0.1/project.manifest, remoteVersionUrl: https://your-cdn.com/hotupdate/v1.0.1/version.manifest, version: 1.0.1, engineVersion: 2.4.3, // 可选匹配引擎版本 updateMsg: 修复了若干BUG优化了游戏体验。 // 更新提示文案 } }这个服务器需要你自行开发可以用任何你熟悉的后端语言Node.js, Python, Go等。它的数据库里只需要维护一张表记录每个平台iOS, Android的最新版本号、资源包URL、更新说明等。安全与防盗链虽然资源是静态的但建议为CDN资源配置Referer白名单或时间戳签名防盗链防止资源被恶意刷流量。版本管理服务器的接口也可以考虑简单的Token校验。注意很多团队初期会偷懒把Manifest文件也放在CDN客户端直接写死CDN的一个Manifest路径。这非常危险一旦你需要回滚版本或者某个资源包有问题想快速切换你将无法控制客户端去拉取哪个Manifest。版本管理服务器是你的“指挥中枢”必须掌握在自己手里。2.3 客户端更新策略设计客户端逻辑是整个流程的“执行者”其策略设计直接影响用户体验。更新触发时机启动时检查最常用。游戏启动后先显示一个Loading界面或Logo在此后台进行更新检查和解压。手动检查在游戏设置中提供“检查更新”按钮。定时检查在游戏运行过程中定期如每24小时在后台悄悄检查一次。更新流程UI/状态设计一个友好的更新界面应该包含更新提示弹窗当检测到非静默更新时弹出展示版本更新内容、包大小并提供“立即更新”和“稍后再说”选项非强制更新时。下载进度条清晰显示下载进度文件数/总文件数已下载大小/总大小。断点续传Asset Manager本身不支持但可以通过监听下载失败事件记录已下载文件列表下次从断点开始。对于大版本更新这个功能能有效提升成功率。失败重试与回滚网络失败、文件校验失败时应提供明确错误提示和重试按钮。在极端情况下如新版本Manifest本身有问题应能回退到上一个可用版本。静默更新与强制更新静默更新适用于更新量很小如几百KB的配置表或脚本在玩家无感知的情况下后台下载并应用。通常可以设定一个大小阈值如2MB。强制更新当热更版本不兼容旧版本如数据结构大变或涉及重大安全修复时必须强制玩家更新到最新版本才能进入游戏。此时“稍后再说”按钮应隐藏或点击后退出游戏。3. 一步步实现热更新模块3.1 项目配置与构建准备首先在Cocos Creator中做好基础配置。开启MD5 Cache在项目 - 项目设置 - 构建发布中找到“MD5 Cache”选项并勾选。这一步至关重要它确保了构建出的资源文件名称会包含其内容的哈希值从而实现精确的差异对比和缓存管理。构建路径与名称在构建面板中注意“发布路径”。建议构建到一个固定的、清晰的目录比如../publish/{platform}。这样方便写脚本自动上传。构建出的结果中src、res、project.manifest、version.manifest是我们需要关心的核心文件。自定义构建模板可选但推荐为了更灵活地控制热更新初始化逻辑你可以自定义构建模板。在项目根目录创建build-templates文件夹然后按照build-templates/{platform}的目录结构放置你修改过的main.js或game.js。在这里你可以插入自己的版本检查逻辑甚至先于游戏启动执行一个简单的更新器。3.2 编写核心热更新管理器HotUpdateManager我们将创建一个单例类来统一管理所有热更新逻辑。这是整个客户端更新的“大脑”。// HotUpdateManager.ts import { AssetManager, director, game } from cc; import { MessageBox } from ./MessageBox; // 假设你有一个UI弹窗组件 import { VersionServer } from ./VersionServer; // 与版本服务器通信的模块 export class HotUpdateManager { private static _instance: HotUpdateManager null; private _am: AssetManager.Bundle null; private _localManifest: AssetManager.Manifest null; private _remoteManifest: AssetManager.Manifest null; private _storagePath: string ; // 热更新资源存储路径 private _updateCallback: (finished: boolean, message?: string) void null; public static get instance(): HotUpdateManager { if (!this._instance) { this._instance new HotUpdateManager(); } return this._instance; } private constructor() { this._storagePath ${game.localStoragePath}/hotupdate-assets/; // 初始化AssetManager this._am new AssetManager.Bundle(); // 设置本地资源搜索路径优先热更目录再回退包内 this._am.baseDir this._storagePath; this._am.on(AssetManager.Event.ERROR, this.onError, this); } // 启动更新检查 public async checkAndUpdate(): Promisevoid { // 1. 加载本地Manifest (打包在包体内的初始版本) await this.loadLocalManifest(); // 2. 向版本服务器请求更新信息 const updateInfo await VersionServer.instance.checkVersion(this._localManifest.version); if (!updateInfo.hasUpdate) { this._updateCallback?.(true, 已是最新版本); return; } // 3. 根据更新信息决定更新方式静默/提示/强制 this.handleUpdateStrategy(updateInfo); } private async loadLocalManifest(): Promisevoid { // 从application包内加载初始manifest // 注意这里加载的是构建时生成的、随包发布的那个manifest await this._am.loadManifest(project.manifest); this._localManifest this._am.manifest; console.log(本地版本: ${this._localManifest.version}); } private handleUpdateStrategy(info: any): void { if (info.isMandatory) { // 强制更新直接弹窗只能选“更新” MessageBox.show(发现新版本${info.version}必须更新后才能继续游戏。\n\n更新内容${info.updateMsg}, 强制更新, [确定], (idx) { this.startDownload(info); }); } else if (info.isSilent this.calculateUpdateSize(info) 2 * 1024 * 1024) { // 小于2MB // 静默更新后台进行 console.log(开始静默更新...); this.startDownload(info, true); } else { // 普通更新弹窗让玩家选择 const sizeStr this.formatSize(this.calculateUpdateSize(info)); MessageBox.show(发现新版本${info.version}大小约${sizeStr}。\n\n更新内容${info.updateMsg}, 版本更新, [立即更新, 稍后再说], (idx) { if (idx 0) { this.startDownload(info); } else { this._updateCallback?.(false, 用户取消更新); } }); } } private async startDownload(info: any, isSilent: boolean false): Promisevoid { // 加载远程Manifest try { await this._am.loadManifest(info.remoteManifestUrl); this._remoteManifest this._am.manifest; } catch (e) { this.onError(new Error(加载远程Manifest失败: ${e.message})); return; } // 设置资源包根路径 this._am.setBundleRoot(info.packageUrl); // 检查更新 const { totalBytes, totalFiles } this._am.checkUpdate(); if (totalFiles 0) { console.log(没有文件需要更新); this.onUpdateSuccess(); return; } console.log(需要更新 ${totalFiles} 个文件总计 ${this.formatSize(totalBytes)}); if (!isSilent) { // 显示带进度条的UI this.showUpdateProgressUI(); } // 开始下载更新 this._am.update((completed, total, message) { // 更新进度回调 if (!isSilent) { this.updateProgressUI(completed, total, message); } console.log(更新进度: ${completed}/${total}, ${message}); }, this.onUpdateSuccess.bind(this), this.onError.bind(this)); } private onUpdateSuccess(): void { console.log(热更新完成); // 保存新版本信息可以存到LocalStorage // 重启游戏或刷新资源管理 director.loadScene(MainScene); // 重新加载主场景或重启游戏 this._updateCallback?.(true); } private onError(error: Error): void { console.error(热更新出错:, error); // 显示错误提示提供重试按钮 MessageBox.show(更新失败${error.message}, 错误, [重试, 跳过], (idx) { if (idx 0) { // 重新尝试 this.retryUpdate(); } else { // 跳过更新尝试用旧版本进入游戏可能功能不全 this._updateCallback?.(false, error.message); } }); } // ... 其他辅助方法如 calculateUpdateSize, formatSize, showUpdateProgressUI 等 }这个管理器封装了从检查到下载的完整流程并处理了不同的更新策略。你需要根据你的UI框架来实现MessageBox和进度条界面。3.3 服务器端部署与资源上传客户端代码写好了服务器端需要准备好。准备资源使用Cocos Creator构建项目后进入构建输出目录如build/android你会看到assets,src,res,project.manifest,version.manifest等。整个这个目录就是你这次构建的“资源包”。版本命名与目录结构我推荐在服务器CDN上使用清晰的目录结构来管理不同版本。例如https://your-cdn.com/hotupdate/ ├── v1.0.0/ (初始包理论上可以不存) ├── v1.0.1/ │ ├── project.manifest │ ├── version.manifest │ ├── assets/ │ ├── src/ │ └── res/ └── v1.0.2/ └── ...每次构建后将整个输出目录上传到以新版本号命名的文件夹下。自动化上传脚本手动上传容易出错写一个简单的Node.js脚本来自动化这个过程// upload.js const fs require(fs-extra); const path require(path); const { OSS } require(ali-oss); // 以阿里云OSS为例 const client new OSS({ /* 你的配置 */ }); const version process.argv[2] || 1.0.1; // 从命令行参数或package.json读取版本 const buildDir path.join(__dirname, ../build/web-mobile); // 你的构建目录 const remoteDir hotupdate/v${version}/; async function uploadDir(localPath, remotePrefix) { const files await fs.readdir(localPath); for (const file of files) { const localFilePath path.join(localPath, file); const stat await fs.stat(localFilePath); const remoteFilePath ${remotePrefix}${file}; if (stat.isDirectory()) { await uploadDir(localFilePath, ${remoteFilePath}/); } else { console.log(上传: ${remoteFilePath}); await client.put(remoteFilePath, localFilePath); } } } (async () { console.log(开始上传版本 ${version}...); await uploadDir(buildDir, remoteDir); console.log(上传完成); // 这里可以调用你的版本管理服务器API更新数据库中的最新版本号 })();然后通过node upload.js 1.0.1命令即可一键上传。更新版本管理服务器上传资源后调用你版本管理服务器的后台API将新版本号v1.0.1及其对应的资源包URLhttps://your-cdn.com/hotupdate/v1.0.1/写入数据库使其成为该平台的最新版本。4. 高级技巧与避坑实战指南4.1 差异更新增量更新优化默认情况下assetManager.checkUpdate()会对比本地和远程Manifest中每个文件的MD5只下载MD5不同的文件。这已经是差异更新。但要最大化其效率你还需要注意小文件合并如果项目有大量零碎的小配置文件如JSON可以考虑在构建后用一个脚本将它们打包成一个.zip或自定义的二进制包。这样Manifest里只记录一个大文件减少HTTP请求次数下载效率更高。当然客户端需要相应的解包逻辑。避免频繁更改大资源对于音频、视频、大型图集等文件一旦确定尽量避免修改。因为即使只改了一个字节MD5就全变了需要重新下载整个文件。对于这类资源版本规划要更谨慎。4.2 更新失败与回滚机制网络不稳定、存储空间不足、文件校验失败都可能导致更新中断。一个健壮的系统必须能处理这些情况。失败重试在onError回调中不要立即判定为致命错误。可以设置一个重试计数器比如3次在提示用户网络不佳的同时自动进行重试。对于下载失败的具体文件Asset Manager会记录重试时会跳过已成功的。版本回滚这是更高级的保障。思路是在成功应用一个新版本后不要立即删除旧版本的热更资源。可以保留上一个稳定版本的数据。在HotUpdateManager中每次更新成功后将当前有效的Manifest内容或版本号备份到LocalStorage。如果新版本启动后发生崩溃可通过全局异常捕获判断可以在下次启动时自动将热更目录回滚到备份的版本并提示用户更新失败已恢复至稳定版本。空间检查在开始下载前检查设备可用存储空间。可以通过fs模块在小游戏平台有相应API尝试写入一个测试文件来估算。如果空间不足提前提示用户清理避免下载到一半失败。4.3 热更新脚本JavaScript的注意事项Cocos Creator的热更新也支持更新src目录下的脚本文件。但这需要满足一个关键前提项目必须使用Asset Bundle功能并且将需要热更的脚本放在Bundle中或者将整个src作为Asset Bundle打包。具体操作在资源管理器中新建一个文件夹比如scripts。将需要热更的脚本拖入此文件夹。在资源管理器中右键点击scripts文件夹选择创建 - Asset Bundle。这会在项目设置 - Asset Bundle中创建一个新的Bundle。构建时这个Bundle会被单独打包。你可以通过配置让这个Bundle参与热更新。重要警告热更新脚本存在风险。如果新脚本有语法错误或逻辑问题可能导致游戏直接崩溃且回滚困难。因此对于脚本更新务必进行充分测试。更安全的做法是将频繁变动的逻辑放在配置表JSON中通过热更新配置表来实现逻辑变化脚本主体保持稳定。4.4 多平台与引擎版本兼容性平台差异iOS、Android、微信小游戏、字节小游戏等平台的存储路径、网络权限、文件系统API有所不同。game.localStoragePath是Cocos Creator提供的跨平台路径但在小游戏平台下载大文件可能需要使用平台特定的API如微信的wx.downloadFile和wx.getFileSystemManager。你可能需要为不同平台编写适配代码。引擎版本热更新机制在不同Cocos Creator版本间可能有细微调整。特别是从2.x升级到3.xAsset Manager API有较大变化。如果你的项目需要升级引擎热更新代码是需要重点测试和迁移的部分。在Manifest中也可以加入engineVersion字段客户端可以检查并提示玩家是否需要升级App本体。4.5 实测中的性能与体验优化点分帧下载对于超大更新包比如几百MB如果一次性让Asset Manager下载所有文件可能会造成界面卡顿。虽然Asset Manager内部有队列但我们还可以在update的回调中每下载完N个文件比如10个就主动setTimeout一下让出主线程给UI渲染实现更平滑的进度条更新。后台下载在移动端应用切换到后台时网络请求可能会被挂起或限制。你需要监听应用的生命周期事件如game.onPause在切后台时暂停下载切回来时恢复。同时在更新界面明确提示用户“请保持应用在前台”。Wi-Fi判断对于大体积更新可以检查网络环境是否为Wi-Fi。如果是蜂窝数据应弹窗提醒用户并获得确认后再开始下载避免消耗用户过多流量。预热与预加载更新完成后不要急着跳转场景。可以趁用户在“更新完成”界面点击“确定”的时机在后台预加载一些主场景的关键资源让进入游戏后的等待时间更短。5. 常见问题排查与解决方案实录即使按照指南操作在实际部署中你还是会遇到各种奇怪的问题。下面是我踩过的一些坑和解决办法。问题1更新后资源加载失败提示“找不到资源”或显示为粉色方块。可能原因A热更新存储路径权限问题。在某些Android设备上应用对内部存储空间的写入权限可能受限。排查在HotUpdateManager初始化后立即尝试在this._storagePath下创建一个测试文件看是否成功。解决如果失败可以尝试使用jsb.fileUtils.getWritablePath()来获取一个肯定可写的路径Cocos Native平台。对于小游戏平台使用其提供的文件系统API。可能原因BManifest中的路径或包根URLpackageUrl配置错误。排查检查CDN上project.manifest文件的内容查看packageUrl字段。确保这个URL拼接上资源相对路径后能直接访问到文件。例如如果packageUrl是https://cdn.com/v1.0.1/那么一张图片assets/image.png的完整URL应该是https://cdn.com/v1.0.1/assets/image.png。用浏览器打开这个链接测试一下。解决修正构建后上传的目录结构或修正packageUrl。确保构建后project.manifest里的packageUrl是相对于资源根目录的正确路径上传时保持这个相对关系。可能原因C文件MD5校验失败。文件在下载过程中损坏或服务器上的文件与Manifest中记录的MD5不符。排查监听Asset Manager的ERROR事件查看错误信息是否包含“md5 mismatch”。解决重新构建并上传资源确保构建过程一致勾选MD5 Cache。检查CDN服务是否有自动压缩或修改文件的行为如果有需要配置CDN不处理这些文件类型。问题2iOS版本更新正常但Android版本不行或反之。可能原因平台构建的差异。Cocos Creator为不同平台构建时生成的project.manifest内容可能略有不同特别是路径分隔符/vs\或平台特定字段。排查分别下载iOS和Android构建出的project.manifest用文本对比工具比较。解决确保你的版本服务器和上传脚本能正确区分不同平台的资源包。最好在服务器目录结构上就分开/hotupdate/ios/v1.0.1/和/hotupdate/android/v1.0.1/。客户端检查更新时需要上传自己的平台标识。问题3热更新后游戏逻辑没变化好像没生效。可能原因A脚本没有正确打包进热更包。如果你希望更新脚本必须确保脚本所在的目录被配置为Asset Bundle并且该Bundle被设置为“远程包”Remote Bundle在构建后会上传。排查检查构建后的src目录大小看是否包含你修改的脚本文件。检查project.manifest里的文件列表是否包含了这些.js文件。解决正确配置Asset Bundle。并在加载新场景前尝试先使用assetManager.removeBundle(脚本Bundle名)移除旧的Bundle缓存再重新加载。可能原因B缓存问题。可能是旧的资源被浏览器或引擎缓存了。排查在更新完成后彻底关闭游戏进程再重启看是否生效。解决对于Web平台可以在请求资源URL时加查询参数如?v版本号来打破缓存。对于Native平台确保热更路径 (this._storagePath) 设置正确Asset Manager确实优先从该路径加载。问题4更新进度条卡住长时间不动。可能原因A某个文件下载失败阻塞了队列。Asset Manager默认会重试但可能卡在某个环节。排查在update进度回调中打印出message参数它通常包含当前正在处理的文件名。看卡在哪个文件上。解决检查该文件在CDN上是否存在、是否可访问。可能是文件名包含特殊字符导致URL编码问题也可能是CDN节点同步延迟。增加超时和重试机制。可能原因B主线程被阻塞。如果更新过程中有同步的复杂计算或大量DOM操作可能阻塞了网络回调的执行。排查在更新时尽量减少不必要的UI渲染和逻辑运算。解决使用前面提到的“分帧下载”技巧主动让出主线程。问题5在微信小游戏等平台更新包总大小超过平台限制。背景微信小游戏对本地缓存有容量限制如50MB且单次wx.downloadFile下载也有大小限制。解决这是设计层面要考虑的。必须严格控制热更包的大小。资源精简定期清理未使用的资源压缩图片和音频。分包加载使用Cocos Creator的Asset Bundle功能将游戏按模块分成多个包。首次只加载主包其他功能包在需要时或通过热更新动态下载。增量更新确保每次更新只推送变化的文件这是基础。资源远程加载对于非即时需要的超大资源如过场动画视频可以不放在热更包里而是在游戏内通过网络直接流式加载播放。最后建立一个完善的热更新测试流程至关重要。在我的团队里每次发布热更前我们会在内部测试渠道覆盖以下测试在不同网络Wi-Fi/4G下更新、中断下载后恢复更新、磁盘空间不足时更新、更新后回退旧版本安装包验证兼容性。只有这些都通过了才会推送到生产环境。热更新是线上项目的生命线多花一点时间打磨它的稳定性和用户体验绝对物超所值。
（支持资料、图片参考_相关定制）_)
![[C++]内存管理：串顺序存储的内存回收](http://pic.xiahunao.cn/yaotu/[C++]内存管理：串顺序存储的内存回收)
