📚 课程目录第2章项目集成LeakCanary

第2章：项目集成LeakCanary

2.1 集成概述

LeakCanary 2.x 采用 自动注册 机制，只需添加 Gradle 依赖即可完成核心接入。但在企业级项目中，必须正确处理 Debug 与 Release 环境的依赖分离，避免将检测代码带入生产包。

版本说明：本章基于 LeakCanary 2.12+，该版本默认使用 ContentProvider 自动初始化，无需在 Application 中手动注册。若使用 1.x 或 2.0-2.11，则需手动调用 LeakCanary.install()。

2.2 Gradle依赖配置

2.2.1 标准配置（Debug启用，Release禁用）

在模块级 build.gradle 或 build.gradle.kts 中添加依赖，利用 debugImplementation 和 releaseImplementation 实现环境隔离：

// build.gradle (Groovy)
dependencies {
    // Debug 模式：包含完整 LeakCanary
    debugImplementation "com.squareup.leakcanary:leakcanary-android:2.12"

    // Release 模式：仅包含空壳（no-op），不会执行任何检测
    releaseImplementation "com.squareup.leakcanary:leakcanary-android-no-op:2.12"

    // 可选：test 模式也使用 no-op
    testImplementation "com.squareup.leakcanary:leakcanary-android-no-op:2.12"
}

2.2.2 使用 Kotlin DSL 的配置

// build.gradle.kts
dependencies {
    debugImplementation("com.squareup.leakcanary:leakcanary-android:2.12")
    releaseImplementation("com.squareup.leakcanary:leakcanary-android-no-op:2.12")
    testImplementation("com.squareup.leakcanary:leakcanary-android-no-op:2.12")
}

配置项	作用域	说明
`debugImplementation`	debug 构建变体	包含完整堆栈分析、通知展示、dump 文件
`releaseImplementation`	release 构建变体	空壳，所有方法体为空，不产生任何开销
`testImplementation`	单元/插桩测试	避免测试运行时意外触发检测

常见错误：切勿使用 implementation 直接引入完整库。生产包若包含 leakanary-android，会暴露调试 Activity 和通知栏，且可能因缺少 root 权限或文件写入失败导致崩溃。

2.3 Application初始化

LeakCanary 2.x 通过 ContentProvider 自动注册，无需在 Application.onCreate() 中编写任何代码。自动注册流程如下：

Android 系统在应用启动时调用所有注册的 ContentProvider 的 onCreate()。
LeakCanary 内部组件 InternalLeakCanary 在此处完成初始化。
初始化成功后，自动开始监控 Activity/Fragment 生命周期。

若需自定义配置（如调整检测阈值、自定义通知），可在 Application 类的 onCreate() 中通过 AppWatcher.config 修改：

// Application.kt
class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()
        if (LeakCanary.isInAnalyzerProcess(this)) {
            // 仅在 LeakCanary 分析进程执行，避免重复初始化
            return
        }
        // 自定义配置示例
        AppWatcher.config = AppWatcher.config.copy(
            watchFragmentViews = true,      // 监控 Fragment View
            watchFragmentArguments = true,  // 监控 Fragment 参数
            retainedDelayMillis = 5000L    // 等待 5 秒再判定泄漏
        )
    }
}

调试技巧：添加 LeakCanary.showLeakDisplayActivityLauncherIcon(false) 可在 Debug 构建中隐藏桌面图标，避免测试人员误操作。

2.4 Debug与Release区分机制

2.4.1 构建变体 vs 库变体

Gradle 构建系统为每个 product flavor / build type 提供独立的依赖作用域。debugImplementation 仅作用于 debug 变体及其衍生 flavor。releaseImplementation 作用于 release 变体。

2.4.2 符号表与ProGuard

Release 版本若使用混淆，需保留 LeakCanary no-op 库中的类名，否则可能因混淆导致编译错误。通常 no-op 库已内置混淆规则，无需额外配置。

# proguard-rules.pro  (可选)
-keep class com.squareup.leakcanary.** { *; }

2.5 验证集成是否成功

以 Debug 构建运行 App。
观察 Logcat 输出过滤 LeakCanary 标签，应看到如下日志：

D/LeakCanary: LeakCanary is running
D/LeakCanary: AppWatcher.config: Config(retainedDelayMillis=5000, watchFragmentViews=true, ...)

在 Release 构建中运行，不应出现任何 LeakCanary 日志，且 APK 体积无显著增加。

2.6 集成流程总览

下图展示了从依赖配置到运行监测的完整链路：

2.7 常见错误与排错

错误现象	可能原因	解决方案
Debug 版本 Logcat 无 LeakCanary 日志	依赖未正确添加，或 build variant 不是 debug	检查 `BuildConfig.BUILD_TYPE` 值，确保构建变体为 debug
Release 版本安装后弹出通知	误用了 `implementation` 而非 `releaseImplementation`	将完整库改为 releaseImplementation + no-op
编译时报错：Cannot resolve symbol LeakCanary	依赖版本号错误或 Maven 仓库未配置	在 `repositories` 中添加 `mavenCentral()`，检查版本号是否可用
自定义配置未生效	`LeakCanary.isInAnalyzerProcess` 提前返回	确认配置代码在 Application.onCreate 主线程执行，并放于 return 之前

2.8 性能注意事项

Debug 构建中，LeakCanary 会在主线程执行 dump 操作，可能造成短暂卡顿。建议通过 AppWatcher.config.retainedDelayMillis 调大等待时间（如 10s）减少误判。
Release 构建因使用 no-op，无任何性能损耗，APK 体积仅增加约 40KB（no-op Jar）。
若仍需在 Release 构建中保留轻量级日志记录，可考虑自定义 BuildConfig 条件或 Product Flavor 隔离。