4. 增量编译原理与配置优化

4.1 增量编译核心原理

增量编译（Incremental Compilation）是 AGP 在构建过程中只重新编译发生变更的源文件及其直接影响的范围，从而大幅缩短单次构建耗时。其实现依赖于文件级别的变更检测与依赖图分析。

4.2 Java / Kotlin 增量编译触发条件

4.3 ABI 变更影响分析

ABI（Application Binary Interface） 变更指类、方法、字段的公开签名、继承关系、注解等对二进制兼容性有影响的变化。当 ABI 发生变更时，即使只修改了一个文件，AGP 也会强制全量重新编译所有依赖该 ABI 的模块或源文件，以确保二进制一致性。

// 示例：ABI 友好的变更（触发增量）
// 仅修改方法体，无签名变化
fun calculate(a: Int, b: Int): Int {
    return a * b + a   // 原来为 a + b
}

// 示例：ABI 破坏性变更（触发全量）
// 修改方法签名（返回值类型变化）
fun calculate(a: Int, b: Int): Long {   // 原为 Int
    return (a + b).toLong()
}

4.4 增量编译流程图

下图描述了 AGP 在执行 compileJava / compileKotlin 任务时，基于文件变更与 ABI 分析所做的决策路径：

4.5 优化配置与命令

4.5.1 Gradle 属性配置（gradle.properties）

# 启用 Kotlin 增量编译（需要 Kotlin 1.3.70+）
kotlin.incremental=true
# 启用并行编译，提升多模块增量构建速度
org.gradle.parallel=true
# 增加编译守护进程堆内存，防止 GC 打断增量缓存
org.gradle.jvmargs=-Xmx4096m -XX:MaxMetaspaceSize=512m

4.5.2 模块级 build.gradle.kts 配置

android {
    compileOptions {
        // 增量编译已默认开启
        isIncremental = true
    }
    // 配置编译时依赖分析精度（默认 ONLY_SOURCE_ROOTS）
    // 可设置为 ALL_CLASSES 以更激进地检测 ABI 变更
    compileSdk = 34
    defaultConfig {
        // 开启 R8 增量混淆（减少全量打包）
        isMinifyEnabled = false // 调试阶段建议关闭
    }
}

kotlin {
    // 针对 Kotlin 编译优化
    incremental = true // Kotlin 1.6+ 可直接在 kotlinBlock 中配置
    useIR = false        // 使用 K1 编译器时增量更稳定
} 

4.5.3 命令行调试与验证

# 查看增量编译日志（--info 级别）
./gradlew assembleDebug --info 2>&1 | grep -E "(incremental|non-incremental|ABI)"

# 强制全量编译以验证增量配置是否正确
./gradlew clean assembleDebug

# 输出编译任务执行明细（可用于分析任务依赖图）
./gradlew :app:compileDebugKotlin --dry-run

4.6 常见错误与排查

4.7 性能与稳定性优化建议

• 减少 ABI 变动范围： 将公共 API 封装在稳定接口中，避免经常修改；对于内部实现类使用 internal 可见性。
• 使用 KSP（Kotlin Symbol Processing）替代 kapt： kapt 会破坏 Kotlin 增量编译缓存，而 KSP 设计为增量友好。
• 分层增量缓存： 对大型项目，考虑使用 --build-cache 结合远程缓存，让 CI 共享增量编译产物。
• 调整编译线程数： kotlin.compiler.execution.strategy=in-process 可提升小项目的增量稳定性，但大项目建议保持默认。
• 定期清理失效缓存： Gradle 的 clean 能清除可能损坏的增量快照，建议在分支切换后执行一次。