Tinker热修复集成

官方链接

GitHub · Tencent/tinker
文档 - Shiply 腾讯平台解决方案

开发集成环境

1. Android Studio Ladybug Feature Drop | 2024.2.2 Patch 1
2. Gradle Version：7.4
3. AGP Version 7.2.2
4. Tinker：1.9.15.1
5. compileSdk：33，targetSdk：31，minSdk：23

截至v1.9.15.1版本适配情况：

gradle 7.4 及以下支持360加固和非加固apk。

gradle 7.4 以上只支持非加固apk

依赖引入

1. 工程build.gradle

dependencies {
        classpath 'com.android.tools.build:gradle:7.2.2'
        classpath 'com.tencent.tinker:tinker-patch-gradle-plugin:1.9.15.1'


        // NOTE: Do not place your application dependencies here; they belong
        // in the individual module build.gradle files
    }

1.插件版本为1.9.15.1，最新版本可以查看链接：插件链接

2.代码块添加在“plugins {}”代码块之前，不然会提示错误信息“all buildscript {} blocks must appear before any plugins {} blocks in the script”

2. APP build.gradle.kts

    implementation("com.android.tools.smali:smali-dexlib2:3.0.9")
    //可选，用于生成application类
    annotationProcessor("com.tencent.tinker:tinker-android-anno:1.9.15.1") { isChanging = true}
    compileOnly("com.tencent.tinker:tinker-android-anno:1.9.15.1") { isChanging = true}
    //tinker的核心库
    implementation("com.tencent.tinker:tinker-android-lib:1.9.15.1") { isChanging = true}
    // Maven local cannot handle transist dependencies.
    implementation("com.tencent.tinker:tinker-android-loader:1.9.15.1") { isChanging = true}

3. 引入插件

plugins {
    id 'com.tencent.tinker.patch'
}

4. 配置版本

项目的gradle.properties文件添加如下属性：

TINKER_ID = 1.0 

tinkerId一般为每次发版的版本号，补丁包是根据tinkerId匹配基准包的。之后会在app的build.gradle.kts当中引用该属性。

5. 混淆文件配置

将官方demo中的文件【tinker_multidexkeep.pro】拷贝到自己项目的app目录下。

PS：该文件内有一处需要修改成自己内容的地方，需要将该文件内替换为自己的application。如下：

6. 在app下的build.gradle添加如下内容

defaultConfig {
        multiDexEnabled = true
        multiDexKeepProguard = file("tinker_multidexkeep.pro")
        
        buildConfigField("String", "MESSAGE", "\"I am the base apk\"")
        buildConfigField( "String", "TINKER_ID", "\"1.0.0\"")
        buildConfigField( "String", "PLATFORM", "\"all\"")
    }
    
// tinker支持大工程文件配置
dexOptions {
    jumboMode = true
}

打包配置

在官方demo中，将打包的配置都写在了app下的build.gradle当中，这里可以单独创建tinker.gradle文件。并在app下的build.gradle中引入：

// 引入自动备份打包资源脚本
apply("tinker-auto-backup.gradle")
// 引入tinker配置
apply("tinker.gradle")

tinker.gradle：

官方demo当中的gradle语法属性有些已经废弃了，具体参考如下

def bakPath = file("${projectDir.absolutePath}/tinker/")

ext {
    //for some reason, you may want to ignore tinkerBuild, such as instant run debug build?
    tinkerEnabled = true
    //for normal build
    //打补丁包时候这里配置基准包的全称
    tinkerOldApkPath = "${bakPath}/old.apk"
    tinkerNewApkPath = "${bakPath}/new.apk"
    //打Release补丁包时候这里配置基准包时候生成的mapping文件proguard mapping file to build //patch apk
    tinkerApplyMappingPath = "${bakPath}/mapping.txt"
    //打补丁包时候这里配置基准包时候生成的文件全称resource R.txt to build patch apk, must input //if there is resource changed
    tinkerApplyResourcePath = "${bakPath}/R.txt"
}

def gitSha() {
    try {
        String gitRev = 'git rev-parse --short HEAD'.execute(null, project.rootDir).text.trim()
        if (gitRev == null) {
            throw new GradleException("can't get git rev, you should add git to system path or just input test value, such as 'testTinkerId'")
        }
        return gitRev
    } catch (Exception e) {
        throw new GradleException("can't get git rev, you should add git to system path or just input test value, such as 'testTinkerId'")
    }
}

def getOldApkPath() {
    return hasProperty("OLD_APK") ? OLD_APK : ext.tinkerOldApkPath
}

def getNewApkPath() {
    return hasProperty("NEW_APK") ? NEW_APK : ext.tinkerNewApkPath
}

def getApplyMappingPath() {
    return hasProperty("APPLY_MAPPING") ? APPLY_MAPPING : ext.tinkerApplyMappingPath
}

def getApplyResourceMappingPath() {
    return hasProperty("APPLY_RESOURCE") ? APPLY_RESOURCE : ext.tinkerApplyResourcePath
}

def getTinkerIdValue() {
    return hasProperty("TINKER_ID") ? TINKER_ID : gitSha()
}

def buildWithTinker() {
    return hasProperty("TINKER_ENABLE") ? Boolean.parseBoolean(TINKER_ENABLE) : ext.tinkerEnabled
}

def getTinkerBuildFlavorDirectory() {
    return ext.tinkerBuildFlavorDirectory
}

if (buildWithTinker()) {
    apply plugin: 'com.tencent.tinker.patch'

    tinkerPatch {
        oldApk = getOldApkPath()
        newApk = getNewApkPath()

        outputFolder = "${bakPath}"

        ignoreWarning = false
        allowLoaderInAnyDex = true
        removeLoaderForAllDex = true
        useSign = true
        tinkerEnable = buildWithTinker()

        buildConfig {
            applyMapping = getApplyMappingPath()
            applyResourceMapping = getApplyResourceMappingPath()
            tinkerId = getTinkerIdValue()
            keepDexApply = false

            // 应用是否开启了加固
            isProtectedApp = false
            supportHotplugComponent = false
        }

        dex {
            /**
             * optional，default 'jar'
             * only can be 'raw' or 'jar'. for raw, we would keep its original format
             * for jar, we would repack dexes with zip format.
             * if you want to support below 14, you must use jar
             * or you want to save rom or check quicker, you can use raw mode also
             */
            dexMode = "jar"

            /**
             * necessary，default '[]'
             * what dexes in apk are expected to deal with tinkerPatch
             * it support * or ? pattern.
             */
            pattern = ["classes*.dex",
                       "assets/secondary-dex-?.jar"]
            /**
             * necessary，default '[]'
             * Warning, it is very very important, loader classes can't change with patch.
             * thus, they will be removed from patch dexes.
             * you must put the following class into main dex.
             * Simply, you should add your own application {@code tinker.sample.android.SampleApplication}
             * own tinkerLoader, and the classes you use in them
             *
             */
            loader = [
                    //use sample, let BaseBuildInfo unchangeable with tinker
                    "tinker.sample.android.app.BaseBuildInfo"
            ]
        }

        lib {
            /**
             * optional，default '[]'
             * what library in apk are expected to deal with tinkerPatch
             * it support * or ? pattern.
             * for library in assets, we would just recover them in the patch directory
             * you can get them in TinkerLoadResult with Tinker
             */
            pattern = ["lib/*/*.so"]
        }

        res {
            /**
             * optional，default '[]'
             * what resource in apk are expected to deal with tinkerPatch
             * it support * or ? pattern.
             * you must include all your resources in apk here,
             * otherwise, they won't repack in the new apk resources.
             */
            pattern = ["res/*", "assets/*", "resources.arsc", "AndroidManifest.xml"]

            /**
             * optional，default '[]'
             * the resource file exclude patterns, ignore add, delete or modify resource change
             * it support * or ? pattern.
             * Warning, we can only use for files no relative with resources.arsc
             */
            ignoreChange = ["assets/sample_meta.txt"]

            /**
             * default 100kb
             * for modify resource, if it is larger than 'largeModSize'
             * we would like to use bsdiff algorithm to reduce patch file size
             */
            largeModSize = 100
        }

        packageConfig {
            /**
             * optional，default 'TINKER_ID, TINKER_ID_VALUE' 'NEW_TINKER_ID, NEW_TINKER_ID_VALUE'
             * package meta file gen. path is assets/package_meta.txt in patch file
             * you can use securityCheck.getPackageProperties() in your ownPackageCheck method
             * or TinkerLoadResult.getPackageConfigByName
             * we will get the TINKER_ID from the old apk manifest for you automatic,
             * other config files (such as patchMessage below)is not necessary
             */
            configField("patchMessage", "tinker is sample to use")
            /**
             * just a sample case, you can use such as sdkVersion, brand, channel...
             * you can parse it in the SamplePatchListener.
             * Then you can use patch conditional!
             */
            configField("platform", "all")
            /**
             * patch version via packageConfig
             */
            configField("patchVersion", "1.0")
        }
        //or you can add config filed outside, or get meta value from old apk
        //project.tinkerPatch.packageConfig.configField("test1", project.tinkerPatch.packageConfig.getMetaDataFromOldApk("Test"))
        //project.tinkerPatch.packageConfig.configField("test2", "sample")

        /**
         * if you don't use zipArtifact or path, we just use 7za to try
         */
        sevenZip {
            /**
             * optional，default '7za'
             * the 7zip artifact path, it will use the right 7za with your platform
             */
            zipArtifact = "com.tencent.mm:SevenZip:1.1.10"
            /**
             * 设置path之后会覆盖zipArtifact的配置，使用本地
             * optional，default '7za'
             * you can specify the 7za path yourself, it will overwrite the zipArtifact value
             */
//            path = "/Users/pary/.gradle/caches/modules-2/files-2.1/com.tencent.mm/SevenZip/1.2.17"
        }
    }

    List<String> flavors = new ArrayList<>();
    project.android.productFlavors.each { flavor ->
        flavors.add(flavor.name)
    }
    boolean hasFlavors = flavors.size() > 0
    def date = new Date().format("MMdd-HH")

    /**
     * bak apk and mapping
     */
    android.applicationVariants.all { variant ->
        /**
         * task type, you want to bak
         */
        def taskName = variant.name

        tasks.all {
            if ("assemble${taskName.capitalize()}".equalsIgnoreCase(it.name)) {

                it.doLast {
                    copy {
                        def fileNamePrefix = "${project.name}-${variant.baseName}"
                        def newFileNamePrefix = hasFlavors ? "${fileNamePrefix}" : "${fileNamePrefix}-${date}"

                        def destPath = hasFlavors ? file("${bakPath}/${project.name}-${date}/${variant.flavorName}") : bakPath

                        if (variant.metaClass.hasProperty(variant, 'packageApplicationProvider')) {
                            def packageAndroidArtifact = variant.packageApplicationProvider.get()
                            if (packageAndroidArtifact != null) {
                                try {
                                    from new File(packageAndroidArtifact.outputDirectory.getAsFile().get(), variant.outputs.first().variantOutput.outputFileName.get())
                                } catch (Exception e) {
                                    from new File(packageAndroidArtifact.outputDirectory, variant.outputs.first().variantOutput.outputFileName.get())
                                }
                            } else {
                                from variant.outputs.first().mainOutputFile.outputFile
                            }
                        } else {
                            from variant.outputs.first().outputFile
                        }

                        into destPath
                        rename { String fileName ->
                            fileName.replace("${fileNamePrefix}.apk", "${newFileNamePrefix}.apk")
                        }

                        def dirName = variant.dirName
                        if (hasFlavors) {
                            dirName = taskName
                        }
                        from "${buildDir}/outputs/mapping/${dirName}/mapping.txt"
                        into destPath
                        rename { String fileName ->
                            fileName.replace("mapping.txt", "${newFileNamePrefix}-mapping.txt")
                        }

                        from "${buildDir}/intermediates/symbols/${dirName}/R.txt"
                        from "${buildDir}/intermediates/symbol_list/${dirName}/R.txt"
                        from "${buildDir}/intermediates/runtime_symbol_list/${dirName}/R.txt"
                        into destPath
                        rename { String fileName ->
                            fileName.replace("R.txt", "${newFileNamePrefix}-R.txt")
                        }
                    }
                }
            }
        }
    }
    project.afterEvaluate {
        //sample use for build all flavor for one time
        if (hasFlavors) {
            task(tinkerPatchAllFlavorRelease) {
                group = 'tinker'
                def originOldPath = getTinkerBuildFlavorDirectory()
                for (String flavor : flavors) {
                    def tinkerTask = tasks.getByName("tinkerPatch${flavor.capitalize()}Release")
                    dependsOn tinkerTask
                    def preAssembleTask = tasks.getByName("process${flavor.capitalize()}ReleaseManifest")
                    preAssembleTask.doFirst {
                        String flavorName = preAssembleTask.name.substring(7, 8).toLowerCase() + preAssembleTask.name.substring(8, preAssembleTask.name.length() - 15)
                        project.tinkerPatch.oldApk = "${originOldPath}/${flavorName}/${project.name}-${flavorName}-release.apk"
                        project.tinkerPatch.buildConfig.applyMapping = "${originOldPath}/${flavorName}/${project.name}-${flavorName}-release-mapping.txt"
                        project.tinkerPatch.buildConfig.applyResourceMapping = "${originOldPath}/${flavorName}/${project.name}-${flavorName}-release-R.txt"

                    }

                }
            }

            task(tinkerPatchAllFlavorDebug) {
                group = 'tinker'
                def originOldPath = getTinkerBuildFlavorDirectory()
                for (String flavor : flavors) {
                    def tinkerTask = tasks.getByName("tinkerPatch${flavor.capitalize()}Debug")
                    dependsOn tinkerTask
                    def preAssembleTask = tasks.getByName("process${flavor.capitalize()}DebugManifest")
                    preAssembleTask.doFirst {
                        String flavorName = preAssembleTask.name.substring(7, 8).toLowerCase() + preAssembleTask.name.substring(8, preAssembleTask.name.length() - 13)
                        project.tinkerPatch.oldApk = "${originOldPath}/${flavorName}/${project.name}-${flavorName}-debug.apk"
                        project.tinkerPatch.buildConfig.applyMapping = "${originOldPath}/${flavorName}/${project.name}-${flavorName}-debug-mapping.txt"
                        project.tinkerPatch.buildConfig.applyResourceMapping = "${originOldPath}/${flavorName}/${project.name}-${flavorName}-debug-R.txt"
                    }

                }
            }
        }
    }
}

相比于官方Demo，修改了三处内容，因为不修改的话，打包会报错，修改的具体内容如下：

• 在tinkerPatch{}中增加如下两个属性配置，不添加的话会有报错信息：Warning:ignoreWarning is false,but we found loader classes are found in old secondary dex。

1. allowLoaderInAnyDex =true
2. removeLoaderForAllDex =true

• it.doLast{}当中修改了官方demo中的属性：

1. //官方demo报错的属性方法：
2. variant.outputs.first().apkData.outputFileName
3. //可以正常使用的方法：
4. variant.outputs.first().variantOutput.outputFileName.get()

• sevenZip{}中配置的在打补丁包时候使用的SevenZip配置 ：

1. //修改sevenZip版本：
2. zipArtifact =“com.tencent.mm:SevenZip:1.2.17”
3. 最新版本查询：https://repo.maven.apache.org/maven2/com/tencent/mm/SevenZip/

tinker-auto-backup.gradle

// 是否有Flavors
def hasFlavors = project.android.productFlavors.size() > 0

// 自动备份的路径
def autoBackPath = file("${projectDir}/autoBackup/")

// 是否使用自动备份
def autoBackEnable = true
if (!autoBackEnable) {
    return
}

/**
 * 自动备份编译生成的APK和Mapping文件
 */
android.applicationVariants.all { variant ->
    def variantName = variant.name
    def capitalizedVariantName = variantName.capitalize()

    def assembleTask = tasks.findByName("assemble${capitalizedVariantName}")
    if (assembleTask != null) {
        assembleTask.doLast {
            copy {
                def date = new Date().format("MMddHHmmss")
                def fileNamePrefix = "${project.name}-${variant.baseName}-${date}"
                def destPath = autoBackPath

                // 拷贝Apk
                variant.outputs.forEach { output ->
                    from output.outputFile
                    into destPath
                    rename { String fileName ->
                        def outputName = output.dirName
                        if (outputName.endsWith("/")) {
                            outputName = outputName.substring(0, outputName.length() - 1)
                        }

                        if (!outputName.isEmpty()) {
                            def oldFileName = "${project.name}-${outputName}-${variant.baseName}"
                            def newFileName = "${fileNamePrefix}-${outputName}"
                            fileName.replace(oldFileName, newFileName)
                        } else {
                            def oldFileName = "${project.name}-${variant.baseName}"
                            def newFileName = "${fileNamePrefix}"
                            fileName.replace(oldFileName, newFileName)
                        }
                    }
                }

                from variant.outputs.first().outputFile
                into destPath
                rename { String fileName ->
                    def oldFileName = "${project.name}-${variant.baseName}"
                    fileName.replace("${oldFileName}.apk", "${fileNamePrefix}.apk")
                }

                def dirName = variant.dirName
                if (hasFlavors) {
                    dirName = variantName
                }

                // 拷贝mapping.txt
                from "${buildDir}/outputs/mapping/${dirName}/mapping.txt"
                into destPath
                rename { String fileName ->
                    fileName.replace("mapping.txt", "${fileNamePrefix}-mapping.txt")
                }

                // 拷贝R.txt
//                from "${buildDir}/intermediates/symbols/${dirName}/R.txt"
//                from "${buildDir}/intermediates/symbol_list/${dirName}/R.txt"
                from "${buildDir}/intermediates/runtime_symbol_list/${dirName}/processReleaseResources/R.txt"
                into destPath
                rename { String fileName ->
                    fileName.replace("R.txt", "${fileNamePrefix}-R.txt")
                }

                // 拷贝methodIds.txt
                from "${buildDir}/redirect/methodIds.txt"
                into destPath
                rename { String fileName ->
                    fileName.replace("methodIds.txt", "${fileNamePrefix}-methodIds.txt")
                }
            }
        }
    }
}

注意：这里自动备份R.txt文件不同版本会有区别：

7.4+ 版本使用：
// 拷贝R.txt
from "${buildDir}/intermediates/runtime_symbol_list/${dirName}/processReleaseResources/R.txt"

6.5- 版本使用
// 拷贝R.txt
from "${buildDir}/intermediates/symbols/${dirName}/R.txt"
from "${buildDir}/intermediates/symbol_list/${dirName}/R.txt"
from "${buildDir}/intermediates/runtime_symbol_list/${dirName}/R.txt"

代码接入

（1）从官方demo中找到如下文件拷贝到自己的项目：

（2）AndroidManifest中添加下内容

<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />

<service
            android:name=".SampleResultService"
            android:exported="false"
            android:permission="android.permission.BIND_JOB_SERVICE" />

（3）自定义Application代理类

1. 使用「继承TinkerApplication + DefaultApplicationLike」。（自定义方式）
2. 使用「DefaultLifeCycle注解 + DefaultApplicationLike」。（注解方式）

class MyApplication(
    tinkerFlags: Int = ShareConstants.TINKER_ENABLE_ALL,
    delegateClassName: String = SampleApplicationLike::class.java.name
) : TinkerApplication(
    tinkerFlags,
    delegateClassName
)

（4）修改SampleApplicationLike

ps：这里如果使用自定义方式则去掉@DefaultLifeCycle注解。使用注解则不需要定义MyApplication类，注解自动生成。

原先项目初始化中的内容需要放到SampleApplicationLike的onCreate方法中。

打包流程

打旧包 -> 打新包 -> 打修复补丁

1、配置打包信息

在app/tinker目录生成打包产物，app/autoBackUp目录生成备份产物

2、打old包（也就是发布后需要修复的正式包）

如下tinker目录会生成old包，根据配置改名old.apk，autoBackUp会备份old包和mapping文件、R.txt文件。

3、打new包（修复了old包问题的包

重复第2步打old包流程，生成新包，改名为new.apk

4、打补丁包

打补丁包之前，tinker目录文件红框标识

运行脚本任务：tinkerPatchRelease

最后会在tinker目录下生成/tinkerPatch/补丁包.apk。

最后将补丁包放到业务代码中编写的加载的目录下。

如果成功，应用上的tinker sdk也会toast提示重启应用进程来运行最新的应用，如下会打印成功日志：

5、加固包的补丁生成流程

1. tinker.gradle 文件中 ****isProtectedApp 配置要设置为true
2. 按照上面第一步生成old.apk包，后面生成补丁要用。
3. 将old.apk进行加固，正常上架发布，用户使用的是加固后的old-jiagu.apk
4. 这个时候用户使用的是old-jiagu.apk；如果发现了bug，需要进行修复。首先拉取相应分支编译出未加固的old.apk，然后修复相应的bug编译生成未加固的new.apk，这里注意old.apk和new.apk的版本号要一致，热修复只能同版本修复，无法跨版本。
5. 使用未加固的old.apk和未加固的new.apk打包生成补丁文件patch.apk
6. 测试补丁是否正常，通过测试后发布补丁文件即可。

总的来说，生成补丁都是使用的未加固的包来生成；使用补丁则是在加固后的包上使用。

补丁管理：

因为补丁包需要基于旧包来打，所以保存打旧包时的资源文件比较重要，也可以拉取相应旧包分支来重新打。涉及文件：old.apk、mapping.txt 和 R.txt 三个文件。

在一个app版本内可以包含多个补丁文件，但是新补丁必须要包含旧补丁已修复的代码；这样每次下发时直接下发最新的补丁包即可。

关于补丁包的安全校验，这里可以根据tinkerId和md5双重校验的方式来进行。

问题记录

SevenZip：生成补丁包时提示 Could not resolve all files for configuration ‘:app:sevenZipToolsLocator’

原因是在tinker.gradle配置文件中有一行**zipArtifact = "com.tencent.mm:SevenZip:1.1.10"，**配置压缩依赖，有时候服务器可能无法下载。这里可以手动下载，改成本地目录。

1. brew install p7zip 本地安装7zip

2. 获取本地安装的7zip路径 which 7za

3. 把zipArtifact配置注释掉，path更改为本机安装的7za路径

        sevenZip {
            /**
             * optional，default '7za'
             * the 7zip artifact path, it will use the right 7za with your platform
             */
//            zipArtifact = "com.tencent.mm:SevenZip:1.1.10"
            /**
             * optional，default '7za'
             * you can specify the 7za path yourself, it will overwrite the zipArtifact value
             */
            /*这里改成本地安装的7za路径*/
            path = "/opt/homebrew/bin/7za"
        }

具体原因可以查看：7z包找不到 · Issue #1718 · Tencent/tinker

Mapping和R文件找不到问题

目前发现6.5版本和7.4版本R文件位置目录有变化，这里需要根据自身项目实际修改路径。

Mapping文件一般如下：

\app\build\outputs\mapping\release\mapping.txt

R.txt文件位置如下：

\app\build\intermediates\runtime_symbol_list\release\processReleaseResources\R.txt