第2章 Kotlin 工程 Gradle 集成：依赖声明、版本选择与 ProGuard 配置

LeakCanary 在 Kotlin 工程中的集成方式直接影响后续的检测效率与稳定性。本章聚焦 Gradle 构建体系下的三个核心环节：依赖声明（添加仓库与模块坐标）、版本选择（兼容 Kotlin 版本与 Android API Level）、ProGuard 混淆规则（保留关键类与方法不被移除）。正确完成这三步，才能为后续的自动化检测打下可靠基础。

2.1 依赖声明：仓库与模块坐标

LeakCanary 2.x 及更新版本统一通过 Maven Central 分发。在工程根级 build.gradle 或 settings.gradle 中配置仓库地址：

// settings.gradle（推荐方式）
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        mavenCentral()
        google()
    }
}

如果项目仍使用传统方式，在根 build.gradle 的 allprojects 块中添加：

allprojects {
    repositories {
        mavenCentral()
        google()
    }
}

然后在模块级 build.gradle 的 dependencies 块中声明 LeakCanary 模块。下表列出常用变体及其用途：

dependencies {
    // ✅ 正确方式：仅 debug 变体生效
    debugImplementation 'com.squareup.leakcanary:leakcanary-android:2.14'

    // ❌ 错误方式：release 包会包含检测逻辑，增加包体积与性能开销
    implementation 'com.squareup.leakcanary:leakcanary-android:2.14'
}

2.2 版本选择：兼容性与推荐基线

LeakCanary 版本与 Kotlin 编译器、AGP（Android Gradle Plugin）及目标 API Level 存在对应关系。选错版本轻则编译失败，重则运行时静默失效。下表列出主流版本的兼容矩阵：

版本选择遵循三条原则：

1. 对齐主版本： 优先使用 2.x 最新稳定版，避免使用 1.x 系列（已停止维护）。
2. 验证 Kotlin 编译： 更新 LeakCanary 后执行 ./gradlew assembleDebug --refresh-dependencies，观察编译是否通过。
3. 检查运行时日志： 首次启动 App 时过滤 LeakCanary 日志，确认版本号与初始化状态。

2.3 ProGuard 配置：防止检测逻辑被移除

如果项目开启了代码混淆（minifyEnabled true），LeakCanary 的反射调用链路可能会被 Shrink 步骤破坏。必须在 ProGuard 规则文件中添加保留声明。

在模块 proguard-rules.pro 中追加以下规则：

# 保留 LeakCanary 所有公开 API 及内部回调
-keep class com.squareup.leakcanary.** { *; }

# 保留对象监控器中的弱引用回调
-keep class com.squareup.leakcanary.internal.** { *; }

# 保留 ObjectWatcher 标记对象
-keep class com.squareup.leakcanary.ObjectWatcher { *; }

# 保留 Android 组件的生命周期监听器
-keep class * extends android.app.Application
-keep class * extends android.app.Activity
-keep class * extends android.app.Fragment
-keep class * extends androidx.fragment.app.Fragment

# 防止 dump 文件写入类被混淆
-keep class leakcanary.** { *; }
-keep class shark.** { *; }

对于使用 R8 全量模式的项目，还需要在 gradle.properties 中额外关闭对 LeakCanary 的智能优化：

# 防止 R8 内联 LeakCanary 内部方法
android.enableR8.fullMode=false

2.4 集成流程全景图

下图串联了依赖声明 → 版本匹配 → 混淆防护的完整决策路径，帮助快速定位集成阶段的关键节点：

图中清晰展示了三个关键步骤的衔接：仓库配置 → 依赖声明与版本校验 → 混淆规则保护。每一步都有明确的检出条件，避免遗漏导致集成失败。

2.5 常见集成错误与排查

完成本章的 Gradle 集成后，LeakCanary 已经能在 debug 构建中自动运行。第3章将深入 对象监控器（ObjectWatcher） 的工作原理，理解 LeakCanary 如何判定一个对象是否泄漏。