Cocos Creator 3 官方热更新方案实践

本文中的操作实践基于 Cocos Creator 3.8.3 版本进行，但文中所述的热更新方案并不特定于此版本。请根据实际情况进行调整和应用。

官方 资源热更新教程 - 3.8 感觉更多的是描述热更新方案的原理，没有明确的步骤顺序，所以本文基于文档和提供的范例工程实践一下，把过程步骤记录下来。

本文旨在循序渐进的同时介绍一些注意事项，因此会有一些绕弯的行为。如果你想直接跑通范例项目，可以直接跳转到 简洁步骤 。

0. 准备工作

1. 范例工程可以从 GitHub | Gitee 获取（master 分支）。

   官方文档中提供的 Gitee 地址是无效的，我不清楚是改名了，还是说就是搞错了，项目名是“cocos-tutorial-hot-update”，跳转链接地址里的项目名却是“tutorial-hot-update”。

2. 打开 Cocos Dashboard，导入范例工程，我这里显示它是基于 3.3.2 版本的，将它升级成 3.8.3 版本。

3. 由于 WEB 版本可以通过服务器直接进行版本更新，所以资源热更新只适用于原生发布版本。

   @CocosCreatorDocs资源热更新教程 - 使用场景和设计思路

   本文选择 Android，因此需要 Android 原生开发环境配置，可以参考文档 安装配置原生开发环境 和 Android 原生开发环境配置。

1. 构建生成

选择 项目 -> 构建发布 菜单，点击面板上的“新建构建任务”选项：

1. 选择发布平台“安卓”。

2. 填写“游戏名称”。

3. 填写“应用 ID 名称”。

4. 选择“Target API Level”。

   这里出现的选项跟你的 Android SDK 有关，需要和你要测试的真机或模拟器安卓版本对应。我选择是 android-28 ，因为我模拟器系统是 Android 9 。

5. 其他选项可以根据自己的情况进行调整。

6. 点击“构建”，等待构建完成。

构建成功后，如果不是首次编译 Android 项目，继续点击旁边的“生成”按钮，等待生成成功即可。

否则需要通过 Android Studio 编译：

1. 找到生成好的 Android Studio 工程。

   

   

2. 用 Android Studio 打开已经构建好的项目。

   

   打开 Android Studio 后，会花一段时间进行准备工作，待 Android Studio 将项目准备完成后，即可打包 APK。

3. 打开构建菜单选择 Build Bundle(s) / APK(s) -> Build APK(s)。

   

4. 成功后可以在 proj/build 目录内找到 APK。

   

Android 平台通过编辑器和 Android Studio 编译后的结果有些区别：

• 通过编辑器执行“生成”步骤后，会在发布路径下生成 build 目录，.apk 生成在 build 目录的 build\app\publish\ 目录下。
• 通过 Android Studio 编译后，.apk 则生成在 proj\app{游戏名称}\outputs\apk 目录下。

相关：

• 安卓构建示例 - 发布流程
• 打包发布到原生平台 - 编译和运行
• 打包发布到原生平台 - 注意事项

2. 安装 APK & 试运行

将 APK 安装到模拟器或者真机上，打开应用会显示这个界面：

点击“检查更新”，过会会显示“Fail to download manifest file, hot update skipped.”。这是因为并没有运行对应的服务器，获取不到远程资源包。

3. 运行服务器

为了让游戏可以检测到远程版本，可以在本机上模拟一个远程服务器。

我选择的是 Node.js + http-server 的方案：

1. 安装 Node.js。

2. 安装 http-server 模块：

   npm install -g http-server

3. 导航到你想要作为服务器根目录的文件夹（没有的话可以自己新建）。例如：

   cd D:\Program\cocos\cocos-tutorial-hot-update-server

4. 在该目录下运行以下命令启动服务器：

   http-server -p 7879

   

这将启动一个在端口 7879 上运行的 HTTP 服务器。

你可以在浏览器中访问 http-server 打印出的：

• http://{本地 IP}:7879
• http://127.0.0.1:7879

或 http://localhost:7879 其中任意一个地址来查看服务器内容。

4. 部署远程版本

游戏发布后，若需要更新版本，则生成一套远程版本资源，包含 assets 目录、src 目录和 Manifest 文件，将远程版本部署到服务端。

@CocosCreatorDocs资源热更新教程 - 在 Cocos Creator 项目中支持热更新

所以我们需要准备一套远程版本资源。

1. 打开发布路径，找到 assets 目录（不是工程的 assets 目录）。

   

2. 将所有文件复制到服务器根目录下。

   

3. 打开范例工程的 assets 目录。

   

4. 将 project.manifest 和 version.manifest 复制到服务器根目录下。

   

这时查看服务器内容，应该如下图所示：

再次点击“检查更新”，会发现还是提示“Fail to download manifest file, hot update skipped.”。

其实查看打包后的 manifest 文件会发现 packageUrl 、 remoteManifestUrl 和 remoteVersionUrl 的 IP 是 192.168.130.1 。

这是范例工程遗留下来的，所以我们需要更新 manifest 文件，让应用可以成功找到远程包。

相关：

• 原生项目目录 - 项目目录

5. 使用 Version Generator 来生成 Manifest 文件

在范例工程中，官方提供了一个 version_generator.js ，这是一个用于生成 Manifest 文件的 NodeJS 脚本。使用方式如下：

> node version_generator.js -v 1.0.0 -u http://your-server-address/tutorial-hot-update/remote-assets/ -s native/package/ -d assets/

http://your-server-address/tutorial-hot-update/remote-assets/ 、 native/package/、assets/ 相当于都是占位符，需要根据自己的情况进行替换。

下面是参数说明：

• -v 指定 Manifest 文件的主版本号。
• -u 指定服务器远程包的地址，这个地址需要和最初发布版本中 Manifest 文件的远程包地址一致，否则无法检测到更新。
  • 需要以 / 结尾，因为最后生成的 Manifest 文件会在后面拼接上“project.manifest”和“version.manifest”。
• -s 本地原生打包版本的目录相对路径，比如 ./build/android/assets。
• -d 本地保存 Manifest 文件的相对路径。

根据参数说明，我们需要修改“服务器远程包的地址”和“本地原生打包版本的目录相对路径”：

- > node version_generator.js -v 1.0.0 -u http://your-server-address/tutorial-hot-update/remote-assets/ -s native/package/ -d assets/
+ > node version_generator.js -v 1.0.0 -u http://192.168.0.105:7879/ -s ./build/android/assets -d assets/

因为我们在 4. 部署远程版本 中是把远程版本资源直接放在服务器根目录下，所以这里直接就是 http://192.168.0.105:7879/ （端口号要跟 3. 运行服务器中设置的一致），否则需要提供像 http://192.168.0.105:7879/tutorial-hot-update/remote-assets/ 这样具体的地址。

然后在范例工程根目录下执行修改后的命令：

6. 重新打包并部署

移除之前的构建任务并选择“删除源文件”，接着重新按照 1. 构建生成 步骤新建一个构建任务并构建生成。

• “清空构建缓存”没有用。
• 也可以直接新建一个构建任务并构建生成，但构建任务列表会有多个安卓构建任务，可能会导致管理混乱或磁盘吃紧，而且这种情况下 5. 使用 Version Generator 来生成 Manifest 文件 时要注意本地原生打包版本的目录相对路径，比如 ./build/android-001/assets。
• 第二次生成 APK 可以直接在 Cocos 编辑器“构建发布”面板中点击“生成”，不需要启动 Android Studio，但要注意 .apk 生成在 build 目录的 build\app\publish\ 目录下

可以看到新打包后的 manifest 文件里的 IP 已经是 192.168.0.105 了。

然后将新生成的远程版本资源和 project.manifest 、version.manifest 覆盖掉服务器上之前的旧资源。

在模拟器或者真机上安装新生成的 APK 并打开，点击“检查更新”，会显示“Already up to date with the latest remote version.”，也就是说已经更新到最新的远程版本。

7. 热更新

终于要真正开始热更新了。

1. 为了看出更新前后的区别，我把背景的颜色改成了黑色。

2. 重新构建（不需要生成 APK）并把新生成的远程版本资源覆盖掉服务器上之前的旧资源。

3. 重新 5. 使用 Version Generator 来生成 Manifest 文件 并把新生成的 project.manifest 、version.manifest 覆盖掉服务器上之前的旧资源。

   • 记得升版本号，例如升级到 1.0.1 ：

     node version_generator.js -v 1.0.1 -u http://192.168.0.105:7879/ -s ./build/android/assets -d assets/

重启应用，点击“检查更新”，显示“New version found, please try to update.”。

点击“立即更新”。

更新完毕后会自动进行重启。

如果要使用热更新之后的资源，需要重启游戏。有两个原因，第一是更新之后的脚本需要干净的 JS 环境才能正常运行。第二是场景配置，AssetManager 中的配置都需要更新到最新才能够正常加载场景和资源。

@CocosCreatorDocs热更新管理器 AssetsManager - 技术细节解析 - 重启的必要性

简洁步骤

1. 使用 Version Generator 来生成 Manifest 文件
   • 会报错 Error: ENOENT: no such file or directory，这是因为没有构建过的话，没有本地原生打包版本的目录。这个错误不影响，主要是修改 Manifest 文件中的 IP，当然你也可以自己手动修改。
     
2. 构建生成
3. 运行服务器
4. 部署远程版本
5. 热更新

参考

• 资源热更新教程
• 热更新管理器