Android 热更新实战:XopHotFix SDK 集成与补丁生成、发布完整教程

一、前言

在 Android 项目开发过程中,线上 Bug 修复一直是一个比较麻烦的问题。

传统的 Bug 修复流程通常需要:

  1. 修改代码并重新编译 APK。
  2. 重新测试和打包。
  3. 将新版本上传到应用市场。
  4. 等待用户下载安装更新。

这种方式不仅发布周期较长,而且对于一些紧急线上 Bug 来说,用户无法及时更新也会影响使用体验。

那么,有没有一种方式,可以在不重新安装 APK 的情况下,修复 Android 应用中的部分问题?

XopHotFix 就是为了解决这一问题而设计的 Android 热更新方案。

XopHotFix 提供 Android SDK,开发者只需要在项目中集成 SDK,完成初始化,就可以为应用接入热更新能力。

当线上出现 Bug 时,可以通过补丁生成工具制作补丁,再上传到控制台进行验证、灰度发布或全量发布。

本文将从零开始,介绍 XopHotFix Android SDK 的完整使用流程。

官方文档:

https://hotfix.yqsh168.cn/docs/android-quickstart

二、XopHotFix 功能介绍

XopHotFix 面向 Android 应用热更新场景,主要提供以下能力:

1. SDK 集成简单

在控制台创建应用后,获取以下信息:

  • AppId
  • AppKey
  • AppSecret
  • 补丁公钥

将相关凭证配置到 Android 工程中,通过 Application 初始化 SDK,即可完成接入。

2. 支持桌面端生成补丁

提供桌面端补丁制作工具,可以选择旧版 APK 和新版 APK,自动生成对应的 Patch 文件。

如果项目开启了代码混淆,还可以同时选择对应的 Mapping 文件。

3. 支持 APP 端生成补丁

除了桌面端,XopHotFix 还提供 APP 端工具。

通过手机端可以完成:

  • 注册和登录
  • 创建应用
  • 查看应用凭证
  • 选择 APK 生成补丁
  • 上传补丁
  • 扫码验证
  • 灰度发布
  • 全量发布

基本覆盖了热更新补丁发布的主要操作流程。

三、Android SDK 快速集成

接下来介绍如何将 XopHotFix SDK 集成到现有 Android 项目中。

1. 注册账号并创建应用

首先打开 XopHotFix 官方网站:

https://hotfix.yqsh168.cn/register

注册账号并登录控制台。

进入控制台后,选择:

应用 → 创建应用

填写应用名称和包名。

需要注意:

应用包名必须与 Android 工程中的 applicationId 保持一致。

例如:

android { defaultConfig { applicationId = "com.example.myapp" } } 

创建应用时填写的包名也应该是:

com.example.myapp 

2. 获取应用凭证

应用创建成功后,系统会弹出应用凭证窗口。

需要保存以下信息:

凭证 说明
AppId 应用 ID
AppKey 应用接入 Key
AppSecret 应用接入密钥
补丁公钥 用于补丁相关校验

特别注意:

AppSecret 仅展示一次(也可以在应用详情中输入登录密码再次查看)。

请妥善保存相关凭证,不要将 AppSecret 提交到公开 Git 仓库。

3. 添加 SDK 依赖

打开 Android 项目的 app 模块下的 build.gradle.kts 文件。

在 dependencies 中添加:

dependencies { implementation("io.github.xopjack:xop-platform-client:1.1.7") } 

当前官方快速入门文档使用的 SDK 版本为:

io.github.xopjack:xop-platform-client:1.1.7 

添加依赖后,同步 Gradle,等待 SDK 下载完成。

4. 在 Application 中初始化 SDK

接下来是最关键的一步。

在项目中找到自定义的 Application 类,如果没有,可以自行创建一个。

这里以 MyApp 为例:

class MyApp : Application() { companion object { private const val APP_KEY = "xk_xxxxxxxx" private const val APP_SECRET = "xs_xxxxxxxx" private val PATCH_PUBLIC_KEY = """ -----BEGIN PUBLIC KEY----- 在这里填写控制台获取的补丁公钥 -----END PUBLIC KEY----- """.trimIndent() } override fun attachBaseContext(base: Context) { super.attachBaseContext(base) // 本地初始化,并自动应用已有补丁 // 注意:这里不要同步拉取网络补丁 XopHotFix.loadSecretMetaData( this, APP_KEY, APP_SECRET, PATCH_PUBLIC_KEY ) } override fun onCreate() { super.onCreate() // 异步查询并加载云端新补丁 XopHotFix.loadNewPatch() } } 

这里需要重点理解两个初始化位置。

第一处:attachBaseContext()

override fun attachBaseContext(base: Context) { super.attachBaseContext(base) XopHotFix.loadSecretMetaData( this, APP_KEY, APP_SECRET, PATCH_PUBLIC_KEY ) } 

主要负责本地初始化以及已有补丁的自动应用。

注意:不要在这里同步拉取网络补丁。

第二处:onCreate()

override fun onCreate() { super.onCreate() XopHotFix.loadNewPatch() } 

负责异步查询并加载云端的新补丁。

通过这两个位置的初始化,就完成了 SDK 的基本接入。

5. 配置 AndroidManifest.xml

最后,需要在 AndroidManifest.xml 中注册自定义 Application,并声明网络权限。

示例:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"> <uses-permission android:name="android.permission.INTERNET" /> <application android:name=".MyApp" android:allowBackup="true" android:label="@string/app_name" android:supportsRtl="true"> <!-- 其他组件配置 --> </application> </manifest> 

注意将 .MyApp 替换为自己项目中 Application 的实际路径。

同时,将示例中的 AppKey、AppSecret 和补丁公钥替换为控制台获取的真实凭证。

至此,XopHotFix Android SDK 就已经完成集成。

完成以上步骤后,应用 APK 就可以正常打包并上线。

当线上出现 Bug 时,再通过补丁工具生成补丁并发布即可。

四、补丁生成与发布

SDK 集成完成后,接下来介绍如何制作和发布热更新补丁。

XopHotFix 提供两种补丁制作方式:

  1. 桌面端补丁工具
  2. APP 端补丁工具

两种方式任选其一即可。

完整流程:

选择旧版 APK ↓ 选择新版 APK ↓ 生成 Patch 补丁 ↓ 上传到控制台 ↓ 扫码验证 ↓ 灰度发布 / 全量发布 

五、方式一:使用桌面端生成补丁

1. 下载桌面端工具

打开官方软件下载页面:

https://hotfix.yqsh168.cn/download

下载安装桌面端「XOP 热更新」工具。

安装完成后打开软件。

2. 选择旧版 APK 和新版 APK

进入「制作补丁」页面。

需要选择两个 APK:

  • 旧 APK:线上已经安装的旧版本 APK。
  • 新 APK:基于旧版本修复 Bug 后重新编译的 APK。

这里有几个注意事项:

  1. 旧 APK 必须是线上已经发布的版本。
  2. 新 APK 应该基于相同基线进行 Bug 修复。
  3. 两个 APK 都必须是未加固 APK。
  4. 如果项目开启了代码混淆,需要同时选择对应的 mapping-old 和 mapping-new 文件。

3. 开始制作补丁

确认 APK 文件选择正确后,点击:

开始制作

工具会根据选择的 APK 生成补丁文件。

等待补丁制作完成。

4. 上传补丁到控制台

打开 XopHotFix Web 控制台。

进入:

补丁 → 上传 Patch 文件

选择刚刚生成的补丁文件。

系统会从补丁 manifest 中读取版本信息。

需要确认:

  • 旧 APK 的 versionName
  • 旧 APK 的 versionCode
  • 补丁版本

确认信息无误后,点击创建。

5. 扫码验证并发布

补丁上传成功后,不建议直接进行全量发布。

可以先使用扫码验证功能,在真实 Android 设备上测试补丁。

验证前,需要确保手机已经安装对应的旧版 APK。

验证流程:

  1. 在控制台进入补丁详情。
  2. 点击扫码验证。
  3. 使用手机扫描二维码。
  4. 在真实设备上测试补丁加载效果。
  5. 确认没有问题后,再进行发布。

验证通过后,可以选择:

  • 灰度发布
  • 全量发布

如果希望先小范围验证线上效果,可以先选择灰度发布。

确认没有问题后,再进行全量发布。

至此,桌面端补丁制作和发布流程就完成了。

六、方式二:使用 APP 端生成补丁

除了桌面端,XopHotFix 还支持直接使用手机 APP 完成补丁制作和发布。

对于没有电脑或者希望直接通过手机操作的场景,这种方式会更加方便。

1. 下载 APP 并登录

打开官方软件下载页面:

https://hotfix.yqsh168.cn/download

下载并安装 APP 端工具。

如果还没有账号,可以直接注册。

已有账号则直接登录。

2. 创建应用

登录后进入底部导航栏的「控制台」。

找到「应用」页面。

如果当前没有应用,点击:

+ 创建应用

3. 填写应用信息

填写以下信息:

  • 应用名称
  • 应用包名
  • 应用描述(可选)

其中应用包名必须与目标 Android APK 的包名一致。

填写完成后点击创建应用。

4. 获取应用凭证

创建成功后,进入应用详情页面。

可以查看并复制:

  • AppId
  • AppKey
  • AppSecret
  • 补丁公钥

这些凭证可以用于 Android SDK 的接入配置。

5. 进入补丁生成工具

在 APP 底部导航栏中切换到:

工具

确认当前选择的应用正确。

然后点击:

生成补丁

如果已经有补丁,也可以直接使用扫码验证功能。

6. 选择 APK 并生成补丁

进入补丁生成页面后,需要选择:

  • 旧版 APK
  • 新版 APK

如果项目开启了代码混淆,还需要选择对应的 Mapping 文件。

选择完成后,点击:

开始生成

等待补丁生成完成。

7. 上传补丁

补丁生成成功后,会进入上传页面。

确认旧 APK 版本和补丁版本信息。

确认无误后,点击:

开始上传补丁

等待上传完成。

8. 验证并全量发布

上传完成后,进入补丁详情页面。

可以选择:

  • 扫码验证
  • 下载到本地验证

建议先在真实设备上完成补丁验证,确认修复效果正常。

验证通过后,执行:

全量发布

也可以根据实际需要先进行灰度发布。

至此,通过 APP 端完成补丁生成、上传、验证和发布的完整流程。

七、常见注意事项

在实际使用过程中,建议重点关注以下几个方面。

1. 应用包名必须一致

创建 XopHotFix 应用时填写的包名,必须与 Android 工程的 applicationId 一致。

否则可能导致应用配置不匹配。

2. 妥善保管应用凭证

AppKey、AppSecret 和补丁公钥需要正确配置。

特别是 AppSecret,不要提交到公开代码仓库。

3. attachBaseContext 中不要同步拉取网络补丁

SDK 初始化需要区分本地初始化和云端补丁加载。

本地初始化放在 attachBaseContext() 中。

云端新补丁查询放在 onCreate() 中。

4. 补丁制作需要选择正确的 APK

制作补丁时,旧 APK 应当是线上已经安装的版本,新 APK 应当基于相同基线进行 Bug 修复。

同时,选择的 APK 必须是未加固版本。

5. 开启混淆时注意 Mapping 文件

如果项目使用了代码混淆,制作补丁时需要提供对应的:

  • mapping-old
  • mapping-new

避免遗漏对应文件。

6. 正式发布前先验证

补丁上传成功后,建议先通过扫码验证或本地下载验证。

确认补丁效果正常后,再进行灰度发布或全量发布。

八、总结

通过本文,我们完整介绍了 XopHotFix Android 热更新 SDK 的接入和补丁发布流程。

整个过程可以分为两个阶段:

第一阶段:SDK 集成

  1. 注册 XopHotFix 账号。
  2. 创建应用。
  3. 获取 AppKey、AppSecret 和补丁公钥。
  4. 添加 Gradle 依赖。
  5. 在 Application 中初始化 SDK。
  6. 配置 AndroidManifest.xml。
  7. 打包并上线应用。

第二阶段:补丁发布

  1. 选择旧版 APK 和新版 APK。
  2. 生成 Patch 补丁。
  3. 上传到控制台。
  4. 扫码或本地验证。
  5. 灰度发布或全量发布。

XopHotFix 同时提供桌面端和 APP 端补丁工具,可以根据实际开发场景选择合适的方式。

对于 Android 开发者来说,提前在项目中集成热更新 SDK,可以在后续线上 Bug 修复时提供更加灵活的处理方式。

如果你正在寻找 Android 热更新解决方案,可以参考 XopHotFix 官方文档进行接入。

官方地址:

文章标签:

Android、Android 热更新、Kotlin、Android SDK、Gradle、热修复、Bug 修复、XopHotFix