保留规则简介

如果您使用默认设置启用应用优化，R8 会执行 广泛的优化，以最大限度地提高性能优势。R8 会对代码进行大量修改，包括重命名、移动和移除类、字段和方法。如果您发现这些修改会导致 错误，则需要通过在保留规则中声明 R8 不应 修改的代码部分，来指定这些部分。

需要保留规则的常见场景

R8 会识别并保留代码中的所有直接调用。不过，R8 无法识别间接代码使用情况，这可能会导致它移除应用需要的代码，从而导致应用崩溃。使用保留规则告知 R8 保留此类间接使用的代码。以下是一些常见情况，您可能需要使用保留规则：

  • 通过反射访问的代码：R8 无法识别何时通过反射访问类、字段或方法。例如，R8 无法识别使用 Class.getDeclaredMethod() 按名称查找的方法，也无法识别使用 Class.getAnnotation() 检索的注解。在这些情况下，R8 可能会重命名这些方法和注解，或将其完全移除，从而导致在运行时出现 ClassNotFoundException 或 NoSuchMethodException。
  • 通过 Java 原生接口 (JNI) 调用的代码：当原生（C 或 C++）代码调用 Java 或 Kotlin 方法，或者 Java 或 Kotlin 代码通过 JNI 调用 C++ 代码时，调用基于对方法名称的动态字符串查找。R8 无法识别基于动态字符串的方法调用，因此其优化可能会破坏您的代码。

这并非需要保留规则的场景的完整列表，但这些场景涵盖了您可能需要保留规则的大部分情况。

如果您的代码使用反射或通过 JNI 调用，您可以为该 代码添加 Jetpack Keep 注解，而不是手动编写保留规则。 其 Gradle 插件会在构建时根据注解生成保留规则。

如何为应用添加保留规则

保留规则配置取决于您使用的 AGP 版本。

较大的应用通常在多个库模块中包含代码。在这种情况下，最好将保留规则与它们适用的代码放在特定库模块中。维护库的保留规则的关键区别在于，您如何在库模块的 build.gradle.kts（或 build.gradle）文件中声明这些规则。如需了解详情，请参阅面向库 作者的优化。

对于 AGP 9.3 及更高版本

将规则添加到以 .keep 为后缀的文件中，该文件位于 src/<variant>/keepRules 目录中。例如，src/main/keepRules/custom-rules.keep。请注意，使用针对 AGP 9.3 及更高版本更新的 DSL 可同时实现代码和资源优化，并且 不需要 您显式定义默认 Android 保留规则文件 (proguard-android-optimize.txt)，因为该文件默认包含在内，除非您明确将其省略。

Kotlin

android {
    buildTypes {
        release {
            optimization {
                enable = true // Enables code and resource optimizations.
            }
        }
    }
}

Groovy

android {
    buildTypes {
        release {
            optimization {
                enable = true // Enables code and resource optimizations.
            }
        }
    }
}

省略默认 Android 平台保留规则（高级）

AGP 提供了一组默认 Android 平台规则。如需从项目的配置中省略这些规则并自行管理所有保留规则，请将 optimization.keepRules.includeDefault 设置为 false。

Kotlin

android {
    buildTypes {
        release {
            optimization {
                enable = true // Enables code and resource optimizations.
                keepRules {
                    includeDefault = false // The file with optimization
                    // rules for the Android platform is included by
                    // default. To omit this file, set this option to false.
                }
            }
        }
    }
}

Groovy

android {
    buildTypes {
        release {
            optimization {
                enable = true // Enables code and resource optimizations.
                keepRules {
                    includeDefault = false // The file with optimization
                    // rules for the Android platform is included by
                    // default. To omit this file, set this option to false.
                }
            }
        }
    }
}

AGP 9.3 之前的版本的旧版 DSL

将规则添加到应用模块根目录下的 proguard-rules.pro 文件中，该文件可能已存在，但如果不存在，请创建该文件。如需应用 该文件中的规则，您必须在模块级 build.gradle.kts（或 build.gradle）文件中声明该文件。

默认情况下，您的 build 文件还包含 proguard-android-optimize.txt 文件。此文件包含大多数 Android 项目所需的规则，因此您应让其保留在 build 文件中。此文件基于 proguard-common.txt 文件，并与其共享 内容。

旧版 DSL (Kotlin)

android {
    buildTypes {
        release {
            isMinifyEnabled = true
            isShrinkResources = true

            proguardFiles(
                // Default file with default optimization rules.
                getDefaultProguardFile("proguard-android-optimize.txt"),
                ...
            )
        }
    }
}

旧版 DSL (Groovy)

android {
    buildTypes {
        release {
            minifyEnabled = true
            shrinkResources = true

            // Default file with default optimization rules.
            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt')
            ...
        }
    }
}

添加保留规则

添加保留规则时，您可以添加全局选项，也可以定义自己的保留规则。

  • 全局选项：全局选项是影响 R8 如何对整个代码库进行操作的常规指令。如需了解详情，请参阅全局选项。

  • 保留规则：保留规则需要经过精心设计，以确保您 在最大限度地优化代码的同时，不会 意外破坏应用。如需了解如何编写保留规则，请参阅添加 保留规则。

面向库作者的保留规则

了解保留规则的全局选项和语法后，请参阅 面向库作者的优化，了解更多详情。