unianx logo悠南.unianx采菊东篱下，悠然见南山。

移动端

Android热修复：Aliyun EMAS Sophix

2025年11月16日Android / 前端工程化 / 热修复 / 工具

介绍 Sophix 是阿里云 EMAS 提供的全托管 Android 热修复方案，基于自研虚拟机和多段补丁引擎，支持 Dex、So、资源多类型修复，单补丁最高 20 MB。平台提供补丁...

介绍

Sophix 是阿里云 EMAS 提供的全托管 Android 热修复方案，基于自研虚拟机和多段补丁引擎，支持 Dex、So、资源多类型修复，单补丁最高 20 MB。平台提供补丁灰度、渠道维度下发、基线管理、运行数据回流等能力，非常适合对实时修复与稳定性有高要求的项目。

  • 补丁粒度：Dex/资源/So 可独立或组合修复，Dex 支持多进程复用。
  • 分发策略：按版本、渠道（productFlavors）、机型、IMEI/UID 列表精准投放。
  • 安全保障：三元密钥（AppId/AppSecret/RSA）+ 热修复签名校验、防二次注入。
  • 监控治理：控制台可查看补丁下载、加载、回滚数据，并自动降级异常补丁。

集成前准备

  1. EMAS 控制台开通：进入 EMAS > 移动研发平台 > 热修复，创建应用并记录 AppId、AppSecret、RSA Secret。
  2. 补丁基线策略：确认哪些版本允许热修复，保证可重复构建，并保持 ProGuard/R8 配置一致。
  3. CI/CD 联动：准备 Release apk + mapping/so 符号文件，以便后续差分及定位。

SDK 集成流程

1. 仓库与插件配置

在项目根 build.gradle 增加阿里云 Maven 仓库与 EMAS 插件：

buildscript {
    repositories {
        google()
        mavenCentral()
        maven { url "https://maven.aliyun.com/repository/public" }
    }
}

在 app/build.gradle 中引入热修复 SDK：

apply plugin: "com.aliyun.ams.emas-services"

dependencies {
    implementation "com.aliyun.ams:alicloud-android-hotfix:${new_version}"
}

2. 初始化 Sophix

EMAS 推荐通过 SophixStubApplication 提前初始化，保证补丁在 attachBaseContext 阶段加载：

public class SophixStubApplication extends SophixApplication {

	@Keep  
	@SophixEntry(MyApplication.class)  
	static class RealApplicationStub {}

    @Override
    protected void attachBaseContext(Context base) {
        super.attachBaseContext(base);
        initSophix();
    }

    private void initSophix() {
        SophixManager.getInstance()
            .setContext(this)
            .setAppVersion(getAppVersion())
            // ⚠️ setSecretMetaData 和 AndroidManifest.xml meta-data 配置二选一
            .setSecretMetaData("yourAppId", "yourAppSecret", "yourRsaSecret")
            .initialize();
    }
    
    /**  
	 * 获取 AppVersion Name. 不能使用工具类, Sophix 入口文件不支持出Android包的其他代码
	 * @return App Version Name  
	 */
	 private final String getAppVersion() {  
	    try {  
	        return this.getPackageManager()  
	                .getPackageInfo(this.getPackageName(), 0)  
	                .versionName;  
	    } catch (Exception e) {  
	        return "0.0.0";  
	    }  
	}
}

AndroidManifest.xml 中配置真实 Application：

<application
    android:name="com.taobao.sophix.SophixStubApplication">
	<meta-data
		android:name="com.taobao.android.hotfix.IDSECRET"
		android:value="App ID" />
	<meta-data
		android:name="com.taobao.android.hotfix.APPSECRET"
		android:value="App Secret" />
	<meta-data
		android:name="com.taobao.android.hotfix.RSASECRET"
		android:value="RSA密钥" />
</application>

注意 ⚠️：

  1. setSecretMetaData 和 AndroidManifest.xml meta-data 配置二选一
  2. SophixStubApplication 必须使用 Java，目前测试 Kotlin v1.9.24 中测试kotlin文件会导致MyApplication.class无法正常加载
  3. SophixStubApplication 不能使用非Android原生包的类
  4. 插件包能够修改MyApplication.class，但是不能修改SophixStubApplication

3.混淆配置

作者配置的项目使用的环境如下，以下内容以下述环境下测试：

  • Gradle 8.2.1
  • Kotlin 1.9.22
  • AGP 8.2.2 官方配置文件中要求使用 ProGuard 混淆 image.png

接入测试中关闭R8采用官方配置混淆时发现无法正常通过编译，原因主要为Proguard使用了Transform API，AGP8已经移除了，于是尝试保留R8开启，发现能够正常通过编译。 混淆规则：

#基线包使用，生成mapping.txt
-printmapping mapping.txt
#生成的mapping.txt在app/build/outputs/mapping/release路径下，移动到/app路径下
#修复后的项目使用，保证混淆结果一致
#-applymapping mapping.txt
#hotfix
-keep class com.taobao.sophix.**{*;}
-keep class com.ta.utdid2.device.**{*;}
#防止inline
-dontoptimize

注意⚠️：

  1. 打包时需保留mapping.txt方便 Crash 采集后查看堆栈信息及补丁生成，最好使用版本控制管理
  2. 当生成mapping.txt 文件后需要将 -applymapping mapping.txt 配置打开，保证每次打包都对应同一个混淆规则

制作与发布补丁

前期准备

接入热修复前一般需要保存好每次发布的安装包，这些保存的安装包将作为基线包生成补丁，如果有多渠道配置，注意保留好不同渠道的安装包方便补丁的测试。

生成补丁

参考 生成补丁页面下载打包工具安装后，按步骤完成补丁生成 图片替换文本

参数说明
旧包<必填> 选择基线包路径（有问题的APK）。
新包<必填> 选择新包路径（修复过该问题APK）。
日志打开日志输出窗口。
设置• 补丁输出路径：<必填>指定生成补丁之后补丁的存放位置，必须是已存在的目录。• Key Store Path：<选填>本地的签名文件的路径，不输入则不做签名。目前只支持jks的签名文件。• Key Store Password：<选填>证书文件的密码。• Key Alias：<选填>Key的别名。• Key Passwrod：<选填>Key的密码。• AES Key：<选填>自定义aes秘钥，必须是16位数字或字母的组合。必须与setAesKey中设置的秘钥一致。• Filter Class File：<选填>本地的白名单类列表文件的路径，放进去的类不会再计算patch，文件格式：一行一个类名。
高级• 强制冷启动：勾选的话强制生成补丁包为需要冷启动才能修复的格式。默认不选的话，工具会根据代码变更情况自动选择即时热替换或者冷启动修复。• 不比较资源：打补丁时不比较资源的变化。• 不比较SO库：打补丁时不比较SO库的变化。• 检查初始化：检查初始化写法是否正确。• 快速打包：加快补丁生成速度。• 优化资源补丁：压缩补丁资源的大小。
GO！开始生成补丁。

上传补丁

  1. 查找您的项目，单击项目，进入EMAS概览页。
  2. 在顶部导航栏，选择研发工具。
  3. 左侧导航栏选择移动热修复 > 补丁管理。
  4. 选择待修复的应用版本，单击上传补丁，选择补丁文件、填写补丁描述后单击确定。 图片替换文本 注意⚠️： 上传到控制台的补丁文件名必须为：sophix-patch.jar。 image.png

调试补丁

可以参考 调试补丁 文档进行调试，主要有三种方法调试工具调试：调试工具、本地调试、灰度发布。但实际中发现调试工具调试会提示 “该应用包名错误，请重新输入”，能用的只有本地调试、灰度发布调试，可以通过初始化时设置tags来进行特定设备的初始化 image.png