【Android】Android 包体积优化：R8/ProGuard 深度配置全攻略

Android 包体积优化：R8/ProGuard 深度配置全攻略

> 一句话收益：掌握 R8 编译器的深层优化机制与 ProGuard 规则精细化配置，让你的 APK 体积减少 30%~50%，同时彻底避免混淆引发的线上崩溃。

> 适用版本：Android Gradle Plugin 7.0+，R8 全模式（Full Mode），Kotlin 1.9+，AGP 8.x

> 阅读时长：约 18 分钟

1. 从一个真实 Bug 切入

线上突然来了一批崩溃，堆栈如下：

复制代码

java.lang.ClassNotFoundException: com.example.app.data.model.UserResponse

at dalvik.system.BaseDexClassLoader.findClass(BaseDexClassLoader.java:207)


at java.lang.ClassLoader.loadClass(ClassLoader.java:379)

UserResponse 是一个纯 Kotlin data class，用于 Gson 反序列化。本地 debug 包完全正常，release 包上线后炸了。

原因：R8 开启后，发现 UserResponse 的字段从未被"显式调用"，直接把这个类的字段改名甚至删除了------Gson 靠字段名反射匹配 JSON key，混淆后名字变了，数据反序列化全部失败。

这是最典型的"包体积优化配置不当"场景。本文从原理出发，彻底搞清楚 R8/ProGuard 怎么配才能又小又稳。

2. R8 与 ProGuard 全景解析

2.1 两者关系与演进

复制代码

ProGuard 时代（AGP < 3.4）

└─ 独立工具：shrink → optimize → obfuscate → preverify



R8 时代（AGP 3.4+，默认启用）


└─ 集成进 D8 编译器：


├─ Shrinking（代码收缩）  ── 删除未使用的类/方法/字段


├─ Optimization（优化）   ── 内联、常量折叠、循环展开


├─ Obfuscation（混淆）    ── 重命名类/方法/字段


└─ Resource Shrinking     ── 与 Android Gradle Plugin 协作删除资源



R8 Full Mode（AGP 8.0 可选，AGP 8.1+ 默认）


└─ 更激进的优化：移除接口默认方法、空构造器优化、Kotlin 元数据压缩

R8 读取的规则文件与 ProGuard 完全兼容，但有少量 R8 专属指令（-assumevalues、-identifiernamestring 等）。

2.2 R8 处理流程（AGP 8.x）

复制代码

Java/Kotlin 源码

│


▼


kotlinc + javac


│  .class 文件


▼


D8（Dex 编译）


│


▼ ◄─── proguard-rules.pro


R8（收缩 + 混淆 + 优化）


│  mapping.txt（混淆映射）


▼


classes.dex（已优化）


│


▼


APK/AAB

关键产物：build/outputs/mapping/release/mapping.txt --- 线上崩溃 deobfuscate 的唯一依据，必须归档。

2.3 R8 Full Mode vs 兼容模式

| 特性 | 兼容模式（默认至 AGP 8.0） | Full Mode（AGP 8.1+ 默认） |

|------|--------------------------|---------------------------|

| 接口默认方法内联 | 否 | 是 |

| 移除 Kotlin 元数据 | 部分 | 更激进 |

| 构造函数合并 | 否 | 是 |

| 优化效果 | 中等 | 显著（额外 5~15% 体积减少） |

| 需要额外规则 | 较少 | 较多（需显式 keep 反射目标） |

在 gradle.properties 中控制：

复制代码

## 强制启用 Full Mode（AGP 8.1+ 已默认）



android.enableR8.fullMode=true

3. 核心优化机制深度原理

3.1 Shrinking：树摇（Tree Shaking）

R8 从 Entry Point（-keep 声明的保留点）出发，构建一个可达性图：

复制代码

Entry Points（四大组件、Application、@Keep 等）

│


▼ 可达性分析


直接引用的类/方法/字段 ──► 间接引用 ──► ...


│


▼ 不可达的 → 删除


最终 Dex

关键： 反射引用 对 R8 不可见，这是大多数崩溃的根源。

3.2 Optimization：内联与常量折叠

R8 会将短方法直接内联，减少方法数和调用开销：

复制代码

// 优化前

fun isDebug(): Boolean = BuildConfig.DEBUG



fun doSomething() {


if (isDebug()) log("debug")  // 方法调用


}



// R8 内联后（release 下 DEBUG=false）


fun doSomething() {


// if (false) log("debug")  → 整个分支被删除


}

3.3 Obfuscation：混淆字典

默认使用 a、b、c... 短名字。可自定义混淆字典进一步压缩：

复制代码

## 使用自定义字典（更短的标识符）



-obfuscationdictionary       dictionary.txt


-classobfuscationdictionary  dictionary.txt


-packageobfuscationdictionary dictionary.txt

4. 代码示例

4.1 标准 proguard-rules.pro 模板（含注释）

复制代码

## ============================================



## 基础保留规则



## ============================================




## 保留所有注解（注解处理器依赖）



-keepattributes *Annotation*



## 保留行号信息（便于崩溃定位）



-keepattributes SourceFile,LineNumberTable



## 混淆后保留原始文件名映射（用于 deobfuscate）



-renamesourcefileattribute SourceFile



## ============================================



## Kotlin 专项规则



## ============================================




## 保留 Kotlin 元数据（反射/序列化依赖）



-keep class kotlin.Metadata { *; }



## 保留 Kotlin 协程内部类（Full Mode 下必须）



-keepclassmembers class kotlinx.coroutines.** {


volatile 
   
    ;
   


}



## ============================================



## 序列化/反序列化（Gson/Moshi/kotlinx.serialization）



## ============================================




## Gson：保留所有用于反序列化的 data class



## 推荐方案：创建自定义注解 @JsonModel，只 keep 带注解的类



-keepclassmembers @com.example.app.annotation.JsonModel class ** {

    
  
   ;
    
   
    ();

    
}



    
## kotlinx.serialization：不需要额外 keep，插件自动生成 -keepclassmembers



    
## 但需要保留序列化类本身



    
-keepclasseswithmembers class ** {


    
@kotlinx.serialization.Serializable *;


    
}



    
## ============================================



    
## 反射使用点（精确 keep）



    
## ============================================




    
## Room：保留所有 Entity 和 DAO



    
-keep class * extends androidx.room.RoomDatabase { *; }


    
-keepclassmembers @androidx.room.Entity class ** { *; }


    
-keepclassmembers interface * extends androidx.room.RoomDatabase { *; }

4.2 错误写法 → 问题 → 正确写法

错误写法（过度 keep）：

复制代码

## ❌ 危险：保留了整个包，完全失去混淆和收缩效果



-keep class com.example.app.** { *; }

问题：

包内所有类、方法、字段全部保留，R8 Shrinking 对这部分完全无效
一个中型项目这样配置，APK 体积可能只减少 5%，而不是应有的 40%
正确写法（精确 keep）：

✅ 只 keep 被反射访问的类，且只保留必要成员

-keepclassmembers class com.example.app.data.model.** {

只保留字段（Gson 反序列化需要）
复制代码
```
 ;
```
保留无参构造器（实例化需要）
复制代码
```
  ();
```
}

✅ 或者用注解驱动（推荐）：给需要保留的类加 @Keep

无需任何 proguard 规则，AGP 自动处理 @Keep 注解

5. 最佳实践

5.1 启用 R8 Full Mode 并配套 Baseline Profile

做法：在 gradle.properties 启用 android.enableR8.fullMode=true，同时生成 Baseline Profile。原因：Full Mode 的激进优化会删除更多"看起来没用"的代码，但结合 Baseline Profile 可以确保热路径代码不被错误删除，同时启动速度不降反升。对比：不启用 Full Mode，仅靠兼容模式，APK 通常只能减少 20~30%；Full Mode 下可达 35~50%。

5.2 序列化模型改用 kotlinx.serialization

做法：将 Gson/Jackson 替换为 kotlinx.serialization，并在数据类上加 @Serializable。原因：kotlinx.serialization 在编译期生成序列化代码，无需运行时反射，R8 可以准确追踪所有引用，无需手写 keep 规则，体积更小且更安全。对比：Gson 需要大量 -keepclassmembers 规则，稍有遗漏就崩溃；kotlinx.serialization 的 Gradle 插件自动生成规则，几乎零配置。

5.3 为每个 AAR 模块维护独立的 consumer-proguard-rules.pro

做法：在 library module 的 build.gradle 中声明 consumerProguardFiles "consumer-rules.pro"，将本模块所需的 keep 规则放入该文件。原因：library 的使用者无需关心其内部实现，keep 规则随 AAR 自动传递，避免应用层规则臃肿且容易遗漏。对比：若所有规则都堆在 app module 的 proguard-rules.pro，多人协作时极易产生遗漏和冲突。

5.4 用 `-whyareyoukeeping` 审计 keep 原因

做法：在调试期规则文件中加入 -whyareyoukeeping class com.example.TargetClass，查看 R8 为什么保留了某个类。原因：许多开发者不知道是哪条规则导致某个类被保留， -whyareyoukeeping 直接输出保留原因链。对比：不用此指令，只能盲目猜测，往往多次发版才找到问题根源。

5.5 归档 mapping.txt 并集成 Firebase Crashlytics 自动上传

做法：

复制代码

// build.gradle (app)

buildTypes {


release {


// Crashlytics 自动上传 mapping.txt


firebaseCrashlytics {


mappingFileUploadEnabled true


}


}


}

原因：线上崩溃堆栈是混淆后的，没有 mapping.txt 无法 deobfuscate，等于拿到了一堆乱码。对比：不上传 mapping.txt，线上崩溃完全无法定位，只能靠猜。

6. 常见坑点

坑1：Gson 反序列化崩溃（最高频）

现象：Release 包运行时 NullPointerException 或 JSON 解析结果全为 null，字段值丢失。原因：Gson 通过反射读取字段名匹配 JSON key，R8 混淆后字段名变为 a、 b、 c，与 JSON key 不匹配。复现：

复制代码

data class UserResponse(val name: String, val age: Int)

// R8 混淆后可能变为：


// class a { val a: String; val b: Int }


// Gson 找不到 "name"、"age" 字段，返回 null

解决方案 ：

复制代码

// 方案1：给字段加 @SerializedName（显式绑定，不受混淆影响）

data class UserResponse(


@SerializedName("name") val name: String,


@SerializedName("age") val age: Int


)



// 方案2（推荐）：改用 kotlinx.serialization，彻底告别此类问题


@Serializable


data class UserResponse(val name: String, val age: Int)

坑2：反射实例化失败（ClassNotFoundException / InstantiationException）

现象：通过 Class.forName("com.example.SomeClass").newInstance() 在 release 包抛出 ClassNotFoundException。原因：R8 认为该类不可达，直接删除了它。复现：插件系统、工厂模式中通过字符串类名动态加载。 解决方案 ：

复制代码

## proguard-rules.pro



-keep class com.example.SomeClass { 
   
    (); }
   

@Keep  // 告诉 R8 不要删除/混淆这个类

class SomeClass { ... }

坑3：Parcelable CREATOR 字段丢失

现象： BadParcelableException: Parcelable protocol requires a Parcelable.Creator object called CREATOR 原因：R8 把 Parcelable 实现类的静态字段 CREATOR 混淆成了别的名字。 解决方案 ：

复制代码

-keepclassmembers class * implements android.os.Parcelable {

public static final ** CREATOR;


}

坑4：R8 删除了"只被反射调用"的方法

现象：某个方法在代码里明明存在，release 包运行时 NoSuchMethodException。原因：R8 静态分析未发现该方法被直接调用（反射调用对 R8 不可见），判定为"dead code"并删除。 解决方案 ：

复制代码

@Keep

fun onEventBusEvent(event: MyEvent) { ... }

坑5：资源收缩误删资源

现象：App 部分 UI 展示空白或崩溃，Release 包中某个 drawable/layout 消失。原因：通过动态字符串拼接引用的资源无法被静态分析检测到，R8 错误地删除了这些资源。 解决方案 ：

复制代码

   tools:keep="@drawable/ic_*"


   
tools:discard="@layout/unused_layout" />

7. 总结

R8 Full Mode 是方向：AGP 8.1+ 已默认开启，激进优化显著减少体积，配合 Baseline Profile 消除潜在冷启动回退。
精确 keep 胜过宽泛 keep ：-keep class com.example.** 是体积优化的最大敌人；用注解驱动替代宽泛规则。
序列化方案选型决定 keep 工作量：kotlinx.serialization 编译期代码生成，几乎无需 keep 规则；Gson 依赖运行时反射，每个模型类都是潜在的坑。
mapping.txt 是线上问题的生命线：必须归档每个 release 版本的 mapping.txt，并通过 Crashlytics 自动上传。
善用 -whyareyoukeeping 和 -printusage：前者分析 keep 原因，后者列出所有被删除的代码，是调试规则的最佳工具。

> 核心结论：R8 优化的本质是缩小 Entry Point 集合，配置的核心原则是"只 keep 反射和框架真正需要的，其余交给 R8 决定"。

【Android】Android 包体积优化：R8/ProGuard 深度配置全攻略

Android 包体积优化：R8/ProGuard 深度配置全攻略

1. 从一个真实 Bug 切入

2. R8 与 ProGuard 全景解析

2.1 两者关系与演进

2.2 R8 处理流程（AGP 8.x）

2.3 R8 Full Mode vs 兼容模式

3. 核心优化机制深度原理

3.1 Shrinking：树摇（Tree Shaking）

3.2 Optimization：内联与常量折叠

3.3 Obfuscation：混淆字典

4. 代码示例

4.1 标准 proguard-rules.pro 模板（含注释）

4.2 错误写法 → 问题 → 正确写法

✅ 只 keep 被反射访问的类，且只保留必要成员

只保留字段（Gson 反序列化需要）

保留无参构造器（实例化需要）

✅ 或者用注解驱动（推荐）：给需要保留的类加 @Keep

无需任何 proguard 规则，AGP 自动处理 @Keep 注解

5. 最佳实践

5.1 启用 R8 Full Mode 并配套 Baseline Profile

5.2 序列化模型改用 kotlinx.serialization

5.3 为每个 AAR 模块维护独立的 consumer-proguard-rules.pro

5.4 用 -whyareyoukeeping 审计 keep 原因

5.5 归档 mapping.txt 并集成 Firebase Crashlytics 自动上传

6. 常见坑点

坑1：Gson 反序列化崩溃（最高频）

坑2：反射实例化失败（ClassNotFoundException / InstantiationException）

坑3：Parcelable CREATOR 字段丢失

坑4：R8 删除了"只被反射调用"的方法

坑5：资源收缩误删资源

7. 总结

参考资料

5.4 用 `-whyareyoukeeping` 审计 keep 原因