Android Tinker 热修复集成与使用指南 1.9.15.2

Tinker 热修复集成与使用指南

版本：Tinker 1.9.15.2、AGP 8.2.2、Gradle 8.7。 目标：讲清环境、引入、集成、日常怎么用，并列出本项目踩过的坑。 项目仓库地址：点击进入 aar修复，请参照项目文件 docs目录下的 old和new .aar文件，关于项目如何打包 .aar，我会出一个新的文档

一、Tinker 能做什么

说明： 手机上不会单独替换 .aar 文件，而是把新版 AAR 编译进新 APK，再与基准 APK 做差量生成补丁；用户加载补丁后，AAR 内的 Dex/资源/so 变更会随补丁生效。

不能做的： 不能改 SampleApplication 壳类；不能靠补丁在 Manifest 里注册新的 Activity/Service 等组件。

二、环境搭建

2.1 必备环境

• JDK 11+（本项目 sourceCompatibility = 11）
• Android SDK，compileSdk 34
• Gradle Wrapper 8.7（不要用 Gradle 9，Tinker 插件会报 GFileUtils 等错误）

2.2 版本对照（与本项目一致）

2.3 仓库

settings.gradle 中已配置 google()、mavenCentral()，并保留 Tinker / 阿里云镜像（拉 SevenZip 等依赖时有用）。

三、引入 Tinker

3.1 根工程 build.gradle

buildscript {
dependencies {
classpath 'com.android.tools.build:gradle:8.2.2'
classpath 'com.tencent.tinker:tinker-patch-gradle-plugin:1.9.15.2'
}
}

3.2 模块 app/build.gradle

apply plugin: 'com.android.application'
apply plugin: 'com.tencent.tinker.patch' // 必须在 application 插件之后

dependencies {
implementation 'com.tencent.tinker:tinker-android-lib:1.9.15.2'
implementation 'androidx.multidex:multidex:2.0.1'
}

3.3 Release 构建注意

• multiDexEnabled true
• minifyEnabled true 时必须有 mapping.txt
• shrinkResources 必须为 false（Tinker 要求）
• 配置 Release 签名（基准包与补丁包签名一致）

四、集成步骤（对照本项目）

4.1 核心类分工

SampleApplication ← 壳，不能热修，只做 Tinker 入口
SampleApplicationLike ← 真正 Application 逻辑，可热修
TinkerManager ← install / loadPatch / cleanPatch
PatchResultService ← 合成成功后冷重启
TinkerPatchService ← :patch 进程合成补丁

4.2 Application 壳

AndroidManifest.xml 中 android:name 指向 SampleApplication，不要直接写 ApplicationLike。

SampleApplication 继承 TinkerApplication，并指定代理类：

public SampleApplication() {
super(
ShareConstants.TINKER_ENABLE_ALL, // dex + so + res
"com.example.tinkerdemo.app.SampleApplicationLike",
"com.tencent.tinker.loader.TinkerLoader",
false // 正式环境建议 true：校验补丁 MD5
);
}

4.3 在 attachBaseContext 安装 Tinker

SampleApplicationLike.onBaseContextAttached() 中：

必须在 attachBaseContext 阶段完成，不能拖到 onCreate。

4.4 AndroidManifest 必配项

• meta-data TINKER_ID：与 build.gradle 里 manifestPlaceholders 一致
• Service（本项目已注册）：
  • TinkerPatchService（:patch 进程）
  • PatchResultService（主进程，合成后杀进程冷启动）
  • TinkerPatchForeService（Android 8+ 前台保活）

4.5 权限（本地调试补丁路径）

• READ/WRITE_EXTERNAL_STORAGE
• Android 11+：MANAGE_EXTERNAL_STORAGE（读 /sdcard/patch_signed_7zip.apk）
• android:requestLegacyExternalStorage="true"（调试方便）

4.6 混淆 proguard-rules.pro

至少保留：

• com.tencent.tinker.**
• SampleApplication（loader 白名单）
• ApplicationLike、Patch/Load Reporter
• R$* 成员（资源 ID 稳定）

打补丁时使用基准包的 mapping.txt（applyMapping）。

4.7 tinkerPatch 配置要点

def TINKER_ID = "base-1.0.0"
def OLD_APK = "${rootDir}/patch/base/app-release.apk"
def OLD_MAPPING = "${rootDir}/patch/base/mapping.txt"
def OLD_RESOURCE = "${rootDir}/patch/base/R.txt"

android {
defaultConfig {
manifestPlaceholders = [TINKER_ID: TINKER_ID]
}
}

tinkerPatch {
oldApk = OLD_APK
ignoreWarning = true // 含 Java/AAR 改动时建议 true，见「常见问题」
useSign = true

buildConfig {
applyMapping = OLD_MAPPING
applyResourceMapping = OLD_RESOURCE
tinkerId = TINKER_ID
}

dex {
dexMode = "jar"
pattern = ["classes*.dex"]
loader = [
"com.tencent.tinker.loader.*",
"com.example.tinkerdemo.app.SampleApplication"
]
}
lib { pattern = ["lib/*/**.so"] }
res { pattern = ["res/*", "assets/*", "resources.arsc", "AndroidManifest.xml"] }
}

4.8 本地 AAR 与热修复（已验证）

implementation files('libs/zcclib-release.aar')

两种场景不要搞混：

AAR 热修步骤（本项目已验证）：

补丁日志中通常能看到 Dex 差量（AAR 内 Java 变更）以及 资源差量（若 AAR 含 layout、strings 等）。若 AAR 带 jni/*.so，还会走 lib 差量。

注意： 热修 AAR 时仍需使用基准包的 mapping.txt、R.txt；若新版 AAR 导致资源 ID 体系变化过大，需评估是否应发新基准包而非打补丁。

五、目录与基准包

TinkerClaude/
├── patch/
│ ├── base/ # 基准包（“已上线版本”）
│ │ ├── app-release.apk
│ │ ├── mapping.txt
│ │ └── R.txt
│ └── patch_signed_7zip.apk # 可选：备份最近一次补丁
├── app/build/tmp/tinkerPatch/ # 补丁真正输出目录（推这个）
│ ├── patch_signed_7zip.apk
│ └── patch_signed.apk
└── keystore/tinker_demo.jks # Release 签名

每次发布新基准包都要更新 patch/base/ 三件套，并 adb install -r 装到手机。

六、使用流程（推荐顺序）

6.1 发布基准包（模拟上线）

# Windows
.\\gradlew.bat clean :app:assembleRelease

将产物拷贝到 patch/base/：

安装到手机：

adb install -r patch/base/app-release.apk

6.2 修改代码 / 资源 / AAR 后打补丁

在不改变 patch/base/ 基准包的前提下，任选其一或组合修改：

• 改 App 内 Java、layout、strings 等
• 用新版 .aar 覆盖 app/libs/ 下同名文件（AAR 热修，已验证）

然后：

.\\gradlew.bat tinkerPatchRelease

仅替换 AAR 时：基准包仍是旧 AAR 打进 APK 的那一版；新 AAR 只参与「新 APK」构建，用于和基准做 diff，无需为此重新安装基准包（除非你还改了 Manifest、TINKER_ID 等）。

补丁输出位置（重要）：

• ✅ 使用：app/build/tmp/tinkerPatch/patch_signed_7zip.apk
• ❌ 不要只推：app/build/outputs/apk/tinkerPatch/release/（可能是旧文件）

6.3 推送到真机并加载

adb push app/build/tmp/tinkerPatch/patch_signed_7zip.apk /sdcard/patch_signed_7zip.apk
adb shell stat -c %s /sdcard/patch_signed_7zip.apk # 校验大小

App 内：从外部存储加载补丁 → 授权「所有文件访问权限」→ 合成成功后会 自动冷重启（PatchResultService）。

6.4 验证是否生效

• 看 资源演示页 文案/颜色是否变化
• logcat 过滤 Tinker.TinkerLoader，应出现 tryLoadPatchFiles: load end, ok!
• 首次装基准包未打补丁时，code=-2（无 tinker 目录）是正常现象

6.5 清除补丁

主界面 清除补丁 → 强制停止 App → 再打开，即回到基准包行为。

七、代码里如何触发补丁

7.1 从 SD 卡加载（Demo 默认）

路径：/storage/emulated/0/patch_signed_7zip.apk（见 PatchFileUtils）

TinkerManager.loadPatch(context, patchPath);

7.2 从 assets 加载（本地演示）

将补丁放入 app/src/main/assets/patch_signed_7zip.apk，点击「从 assets 加载」。

7.3 生产环境建议

用 OkHttp / 下载 SDK 把补丁下到私有目录或 getExternalFilesDir，再调用：

TinkerInstaller.onReceiveUpgradePatch(context, absolutePath);

合成成功后务必 冷启动（杀进程或依赖 PatchResultService）。

八、能力边界速查

九、常见问题

9.1 打补丁失败：ShareTinkerInternals loader 类变更

现象： some loader class has been changed in new primary dex

处理： tinkerPatch { ignoreWarning = true }（本项目已开启）。这是 R8 重编译后的无害差异，不影响业务类热修。

9.2 补丁推了但界面不变

9.3 patch_meta.info / code=-2 日志

• 首次安装、未加载过补丁：正常
• 重装基准包后：先 清除补丁 再加载新补丁

9.4 mkdir res_temp/res 报错但显示合成成功

部分机型（如 vivo）常见，若 onPatchResult: success=true 且冷启动后界面已更新，可忽略。

9.5 Gradle 9 构建失败

请使用 Gradle 8.7，不要用 9.x milestone。

9.6 改了 AndroidManifest（新增 Service 等）

Manifest 变更 不能 靠补丁生效，需 重新打基准包并安装。

9.7 何时必须更新基准包

• 新功能首次上线（新的基准 APK）
• 修改了 Manifest 组件
• 修改了 TINKER_ID
• 换了签名或 ABI 策略

仅改业务代码 / 资源 / 覆盖 libs 下 AAR 后打补丁：只打补丁，不更新基准。

9.8 AAR 热修后无效果

十、命令速查

十一、本项目关键文件索引

十二、参考链接

• Tencent Tinker 官方仓库
• 本 Demo 包名：com.example.tinkerdemo
• 更多项目使用和详细 参见 Android Tinker Demo 使用手册