简介：LeakCanary 是 Android 内存泄漏检测的常用工具，这份资源面向需要做性能优化与内存排查的 Android 开发者，提供一套可直接运行的 LeakCanary 使用示例 Demo。资源以 Android 工程形式组织，共 54 个文件，压缩包约 596KB，包含 java 源码、gradle 构建脚本、xml 配置文件、png 图片等，涵盖 App 模块、依赖配置与资源文件，结构清晰，便于导入 Android Studio 后直接体验 LeakCanary 的接入和泄漏提示流程。目前已有 1912 人学习下载。通过该示例，读者可以快速了解 LeakCanary 的初始化方式、如何监控 Activity 泄漏、如何在泄漏发生时查看堆栈与引用链，并在此基础上结合 Android Profiler 等工具，建立内存优化的排查思路。适合刚接触内存分析、希望以最小 Demo 验证 LeakCanary 实际效果的中级开发者参考。
1. 内存泄漏是个“黑匣子”：LeakCanary 怎么把它变成一条可复现的引用链
在 Android 开发里，内存泄漏是出了名的“黑匣子”：线上 OOM 来了，日志只有几条 GC 告警，看不出是哪次操作漏的；想本地复现，又往往来回点十几遍也不出现。LeakCanary 就是用来对付这个的——debug 包一启动它就自动盯上 Activity、Fragment 和 ViewModel，发现该回收的对象迟迟没被回收，先触发 GC 做二次确认，再抓一份内存堆快照，把引用链翻译成可读路径。这篇笔记从它的 2.x 机制讲起，把集成方式、关键参数、误报排查和 hprof 二次分析一次说清。适合刚接手老项目、正在排查内存压力的开发者，也适合想把泄漏检测变成日常习惯的人。
2. LeakCanary 的检测原理：弱引用、二次 GC 与引用链快照
2.1 弱引用 + ReferenceQueue：泄漏检测的最小闭环
一个对象有没有被 GC 回收，你没法直接问 JVM，但可以借助WeakReference和ReferenceQueue做一次“挂号”。弱引用本身不阻止对象回收，当 GC 发现对象只被弱引用持有时，会把这个弱引用对象塞进关联的ReferenceQueue。所以程序稍后轮询队列，就能反推“目标对象已经被回收”。
LeakCanary 的ObjectWatcher核心逻辑就是这一套。它在 Activity 的 onDestroy、Fragment 的 onDestroyView 等回调点调用 watch()，把一个弱引用挂到监控列表里。如果等待一段时间后对象还活着，再主动触发一次 GC，对象仍然没有被回收，就会进入待确认泄漏列表。
// 简化版 ObjectWatcher 思路：弱引用 + 引用队列 class WatchSample { private val queue = ReferenceQueue<Any>() fun track(target: Any) { // 目标被回收时，这个 WeakReference 会被 JVM 放入 queue val ref = WeakReference(target, queue) // 实际代码里会把 ref 存到自己的监控集合中 println("tracked: $ref") } fun drainGCQueue() { while (true) { val ref = queue.poll() ?: break // 能 poll 到，说明目标对象已经被回收 println("reclaimed: $ref") } } }这段代码里，WeakReference(target, queue)把队列和弱引用绑定，poll()是非阻塞的，队列为空时返回 null，所以用while (true)配合break把已回收引用排空。真实的 LeakCanary 不会在这里 println，而是根据“队列里有没有出现这条引用”来判断对象是否已经被回收。
这里有个时间窗口问题：对象被回收本身不一定是立刻发生，GC 的调度、后台线程的存活、系统组件对页面的临时引用都会让回收晚几步。所以 LeakCanary 并不是销毁事件一发生就立刻判断，而是会等一个观察窗口，常见的默认值是 5 秒左右，对应配置里的watchDurationMillis。窗口结束再触发 GC，再检查对象是否仍然存活，这样能在很大程度上避开生命周期过渡期的误判。
2.2 从 retained 到 hprof：泄漏判定与最短引用链
单靠“弱引用还活着”只能说明对象可能泄漏，还不足以证明泄漏。LeakCanary 不会一发现可疑对象就去抓堆，因为堆转储是非常重的操作：它要暂停 Java 线程做一致快照，堆越大越慢，做多了反而影响调试体验。所以它会先攒一攒，当存活的可疑对象数量到达一定阈值时，再触发一次自动堆转储。
这个阈值就是maxRetainedObjects，默认一般是 5。也就是说，LeakCanary 不是“发现一个漏一个就抓堆”，而是攒够一批再统一定位。这样既降低了抓堆频率，又能把一批相关问题一次性暴露出来。
堆转储完成后，LeakCanary 会拿到一份 hprof 文件，接下来的事交给它是内部的 Shark 堆分析引擎。Shark 会从 GC Root 出发，遍历所有可达对象，找出“当前还引用着这个可疑对象”的引用路径。GC Root 通常包括静态字段、JNI 全局引用、活跃线程栈等。如果一条强引用链从 GC Root 一直通到泄漏对象，那这条链就是 LeakCanary 展示给开发者看的 LeakTrace。
一次典型的 LeakTrace 看起来像这样：
┬─── │ GC Root: static field com.example.GlobalCache │ ├─ com.example.GlobalCache (class) │ ╰ static activity │ ╰ com.example.MainActivity (instance)这不是代码，而是报告的文本片段。最上层是 GC Root，说明泄漏的源头是一个静态字段；中间是持有者类，GlobalCache用静态字段activity握着一个 MainActivity；最下层是泄漏对象本身。拿到这条路径，修复点通常就清楚了：要么静态字段不该存 Activity，要么存之前应该随生命周期清除。
这个阶段常见的认知误区是“看到 LeakTrace 就把最下面的对象删掉”。实际要修的是路径中间那几环，也就是真正长时间持有引用的对象。LeakTrace 的价值在于把“谁引用谁”的顺序画出来，顺着中间持有者去改，往往一次就能解决一个类别的泄漏。
2.3 2.x 自动装配与 1.x 手动埋点：版本选型怎么定
LeakCanary 1.x 时代的接入方式需要手动LeakCanary.install(this)，并且要自己拿RefWatcher去 watch 目标对象。这带来两个问题：一是 Fragment、ViewModel 这类非 Activity 对象的监控要自己埋点，漏一处就漏一类问题；二是不同项目接入姿势差别大，社区里充满了各种自定义写法。
2.x 之后做了一次比较大的调整：依赖里加了debugImplementation，库内的 ContentProvider 会在 Application 初始化之前被自动拉起，Application 里一行代码都不用写，Activity、Fragment、View 和 ViewModel 的监控默认就开始工作了。这个自动装配逻辑靠 Manifest 合并把 ContentProvider 注入进去，所以 debug 包一启动，LeakCanary 就已经在后台等待。
// 1.x 时代的典型接法，现在基本见不到了 val watcher = LeakCanary.install(application) watcher.watch(targetObject)这段代码展示了手动安装的写法，重点是为了对比：2.x 已经不需要开发者手动调用 install，也不需要保存全局RefWatcher实例。如果还在维护 1.x 接法的老工程，升级到 2.x 的主要工作是去掉 install 调用，然后重新检查自定义 watch 逻辑是否和自动监控重复。
选型建议很直接：新项目直接用 2.x；老项目如果 1.x 用得很老，升级时多跑一轮回归，重点看原来手动 watch 的对象是不是被新默认配置覆盖了。仓库里如果存在多个进程，升级后还要处理子进程问题，这个坑在第 4 章会专门展开。
3. 集成与配置：从 build.gradle 到第一条泄漏报告
3.1 依赖引入与安装验证：debug 专属，别带进 release
集成 LeakCanary 的第一步是加依赖。常见做法是放在 debug 源码集下，这样正式包不会掺进任何 LeakCanary 逻辑，也不用额外维护 no-op 变体。
dependencies { debugImplementation("com.squareup.leakcanary:leakcanary-android:2.x") }这里的2.x需要替换成你当前依赖版本对应的实际版本号。debugImplementation保证只有 debug 构建才会把这个库编进去，release 包不会出现它的类，更不会因调试功能增加包体积或带来性能损耗。如果你用的是 1.x 或自定义编译方式，才需要考虑 no-op 变体；2.x 的常规接入不需要。
依赖加完以后，先不写任何代码，直接跑一个 debug 包，然后查看日志：
adb logcat -s LeakCanary如果启动过程中能看到LeakCanary is running之类的日志，说明自动初始化已经生效。LeakCanary 还会在桌面生成一个名为 Leaks 的应用图标，点击它可以查看历史泄漏记录。注意这个图标只在 debug 包出现，release 包不会有。
提示：如果是测试机，尽量用干净的调试环境。同一台机器反复装不同测试包，历史泄漏记录会混在一起，定位问题时要额外花时间去区分是哪一次构建产生的。
3.2 AppWatcher 监控范围：Activity、Fragment 与 ViewModel 的自动挂接
2.x 的泄漏监控分成两层：AppWatcher负责盯对象，LeakCanary负责在确认泄漏后分析堆。前者主要用于配置“看哪些对象”，后者用于配置“抓到堆之后怎么处理”。
如果你想调整监控范围，一般会在自定义 Application 里改AppWatcher.config：
class DemoApp : Application() { override fun onCreate() { super.onCreate() val config = AppWatcher.config.copy( watchActivities = true, watchFragments = true, watchFragmentViews = true, watchViewModels = true, watchDurationMillis = 5000L, maxRetainedObjects = 5 ) AppWatcher.config = config } }这里的watchActivities、watchFragments和watchViewModels分别控制是否监控 Activity、Fragment 和 ViewModel，默认都开着。watchDurationMillis是观察窗口，前面提到过，默认 5 秒；maxRetainedObjects是触发堆转储的阈值。参数调整时最关键的一点是：watchDurationMillis不要设得太短。设成 1 秒会让回收窗口内出现大量假阳性，设成 10 秒以上又会拖慢问题暴露速度，一般 5~10 秒之间比较合适。
这段配置只影响 AppWatcher 的监控范围，真正抓堆、分析 hprof 的行为由LeakCanary.config控制。日常调试时保持默认配置就够了，除非你遇到了太多误报或低端机卡顿，才会考虑动后面的参数。
3.3 ObjectWatcher 手动监控业务对象：单例、回调和 ViewModel 之外的对象
自动监控覆盖了 Android 组件，但项目里真正容易泄漏的常常是普通业务对象，比如一个请求回调、一个自定义管理器、一个被单例持有的监听器。这些对象不会自动被 AppWatcher 监控，需要手动交给 ObjectWatcher 处理。
class NeedWatch { lateinit var request: Request fun sendRequest() { request = Request() request.callback = object : RequestCallback { override fun onComplete(data: String) { // 这里如果引用了 Activity，泄漏大概率发生在这里 } } // 默认情况下 LeakCanary 不会盯 Request，需要手动 watch AppWatcher.objectWatcher.watch(request, "Request-${System.currentTimeMillis()}") } }这段代码展示了一个典型的业务对象监控姿势：watch()接收两个参数，第一个是要监控的对象，第二个是便于识别的名字，排查时能在 LeakTrace 里直接看到这个标签，比如Request-1700000000。名字最好带时间戳或请求 ID，这样多条记录能区分是哪一次调用产生的。
需要强调的是，watch 的含义是“我预期这个对象在接下来会被回收”。如果一个对象本来就是长期存在的，比如进程级单例、配置管理器，就不应该 watch，否则 LeakCanary 会把它识别为泄漏并持续报告。我一般只对临时的、生命周期只到某次回调结束的对象做手动 watch，比如一次性请求、临时流式解析器、弹窗控制器。
3.4 跑通第一个泄漏用例：静态字段造成的 Activity 泄漏
为了让整个流程看得见摸得着，可以刻意造一个泄漏用例。最常见的泄漏之一就是静态字段持有 Activity。
private object GlobalCache { var activity: MainActivity? = null } class MainActivity : AppCompatActivity() { override fun onDestroy() { super.onDestroy() // 演示泄漏：把即将销毁的 Activity 塞进静态容器 GlobalCache.activity = this } }这段代码利用了静态字段的生命周期等同于进程的特点。MainActivity 执行 onDestroy 后本该被回收，但GlobalCache.activity还持有它的强引用，GC 回收不掉，对象就滞留在堆里。这也是很多老项目里“退出页面后内存不减反增”的典型原因。
跑起来的流程是：打开 MainActivity，再退出，等 LeakCanary 的观察窗口结束后，通知栏出现1 leak found。点开通知，会看到类似第 2 章展示的 LeakTrace：GC Root 指向GlobalCache，然后到activity字段，最后到 MainActivity。看到这条链，修复方式无非两种：用弱引用替换强引用，或者在 onDestroy 里主动置空。实际项目里静态引用往往藏得更深，比如单例持有回调、回调又匿名引用 Activity，但只要 LeakCanary 能把链画出来，修复点就不会太难找。
这个用例验证完之后，记得把GlobalCache.activity = this删掉。它只适合做演示，不适合留在生产代码里。我一般会把这个流程写进团队新人文档，让新成员先亲自动手触发一次泄漏，再去看自动监控给出的引用链，理解“路径上每一环是什么意思”。
4. LeakCanary 避坑指南：误报、混淆与多进程的排查记录
4.1 误报：对象只是晚回收，不是泄漏
现象：退出页面后立刻收到 LeakCanary 通知，显示某个 Activity 泄漏，但用 Android Studio 的堆分析工具手动 GC 几次后，对象其实被回收了。
原因：LeakCanary 的判定依赖 GC 时机。它默认等 5 秒后主动触发一次 GC，如果这时系统刚好还在处理动画结束、Fragment 退出事务或后台线程收尾，对象还没有被回收，就会被当成可疑泄漏。低端机上 GC 延迟更大，这种误报更常见。
解决：先不要急着改业务代码，优先调整观察窗口。把watchDurationMillis从 5 秒拉到 8 秒或 10 秒，给系统回收争取更多时间；再把maxRetainedObjects从默认 5 调大到 8，避免零星一两个可疑对象立刻触发堆转储。如果调完仍然误报，再考虑用自定义泄漏监听器把报告降级成日志：
LeakCanary.config = LeakCanary.config.copy( onHeapAnalyzedListener = object : OnHeapAnalyzedListener { override fun onHeapAnalyzed(heapAnalysis: HeapAnalysis) { if (heapAnalysis.leaks.isNotEmpty()) { Log.w("LeakCheck", heapAnalysis.toString()) } } } )这段配置把“弹通知”替换成“打日志”，适合在批量改造老代码时使用。泄漏信息不再打断开发，但仍然会留在 logcat 里。等业务侧清理得差不多了，再把默认的监听器恢复回来。做法上要注意onHeapAnalyzedListener是 LeakCanary 提供的接口，具体字段名以你接入的版本文档为准，不同小版本之间略有差异。
4.2 混淆后引用链成乱码：怎么保住类名映射
现象：打开minifyEnabled true的 debug 包，LeakCanary 报告的 LeakTrace 里全是a.b.c -> d.e.f这样的短类名，完全看不出业务含义。
原因：R8/ProGuard 在构建时对类名和方法名做了混淆，堆 dump 里记录的是混淆后的类名，LeakCanary 读取出来自然就是乱码。问题常出现在那些为了验证泄漏而临时开启混淆的测试包上。
解决：最稳妥的做法是 debug 构建不开混淆。如果你一定要在混淆环境下测，则在混淆规则中保留业务包名和 LeakCanary 相关类名：
-keep class com.example.** { *; } -keep class leakcanary.** { *; }这段规则的意思是，com.example包下所有类及其成员不被混淆，leakcanary 包内部类也保留原名。这样做会让该包下代码体积变大，所以只适合 debug 验证，不建议直接搬进 release 规则。如果混淆包已经产生了不可读的 LeakTrace，还可以在构建产物里找到 mapping.txt，按原类和混淆类对照手工还原。依赖里只有一份 mapping 文件时必须保留，否则还原无从谈起。
4.3 多进程环境：子进程也初始化，要么重复抓要么漏抓
现象：App 有:push、:channel之类的多进程结构，接入 LeakCanary 后发现每个进程似乎都初始化了一遍，有的进程上报了重复的泄漏，有的进程干脆不弹通知。
原因：LeakCanary 2.x 靠 ContentProvider 自动初始化，而 ContentProvider 默认会在每个进程启动时都被调用一次。子进程里如果也跑完整的泄漏监控，既浪费资源，又因为进程间内存独立，泄漏分析可能被重复执行。
解决：在 Application.onCreate 里判断当前进程名，非主进程直接关闭监控：
override fun onCreate() { super.onCreate() val am = getSystemService(Context.ACTIVITY_SERVICE) as ActivityManager val pid = Process.myPid() val processName = am.runningAppProcesses ?.firstOrNull { it.pid == pid }?.processName if (processName != packageName) { AppWatcher.config = AppWatcher.config.copy(enabled = false) } }这段代码通过ActivityManager拿到当前进程名，和包名比较，不一致就关掉 AppWatcher。注意runningAppProcesses在主进程读取没有问题，但在极端多进程场景下，有的机型可能返回 null，所以稳妥起见可以留一个兜底：如果取不到进程名，默认当作主进程处理。另一个轻量做法是读/proc/self/cmdline，得到的进程名更直接，两种方式选一种即可。
4.4 dump 阶段卡顿或二次 OOM：参数收紧策略
现象：在低端机或大堆应用上，LeakCanary 一进入堆转储阶段，应用明显卡顿，甚至直接 ANR；有的项目还遇到过堆转储过程中自身内存压力过大导致二次 OOM。
原因：Heap dump 要暂停 Java 线程来保证堆一致，暂停时间越长卡顿越明显。大堆应用的一次 dump 可能持续数秒，hprof 解析也需要消耗大量 CPU 和内存，在低端机上很容易触发系统资源紧张。
解决：第一，把maxRetainedObjects调大，减少触发 dump 的频率；第二，给 LeakCanary 的分析过程设置内存上限，让它不要在大堆应用里做全量解析。
LeakCanary.config = LeakCanary.config.copy( dumpHeapWhenLeaking = true, analysisMaxHeapSize = 384L * 1024 * 1024, analysisMaxRetainedHeapSize = 256L * 1024 * 1024 )dumpHeapWhenLeaking表示确认泄漏后自动抓堆，日常调试建议保持 true；analysisMaxHeapSize限制分析引擎能处理的堆大小上限，超过上限会放弃分析而不是硬撑；analysisMaxRetainedHeapSize限制 retained 堆的大小，避免泄漏对象太多时分析过慢。这两项具体字段在不同版本里略有差异，动手前看一眼当前版本依赖里的源码或文档，以实际签名为准。低端机场景下我还会把堆转储放到页面空闲时触发，避免用户正在滑动或输入时卡顿。
5. 把 LeakCanary 用出排查力：hprof 二次分析与 CI 接入
5.1 hprof 导出后用外部工具复查
LeakCanary 给的 LeakTrace 已经能定位问题，但有些场景还需要还原现场，比如泄漏对象数量极大、引用链很长，或者你想确认泄漏对象占了多少内存。这时可以导 hprof 文件出来做二次分析。
LeakCanary 抓到的 hprof 文件保存在应用私有目录，debug 包可以直接用 run-as 导出：
adb exec-out run-as com.example.app cat files/leakcanary/xxx.hprof > leak.hprof这条命令把应用私有目录里的 hprof 文件拉取到本地。xxx.hprof要替换成实际文件名；如果命令行找不到，可以先在 Leaks 图标对应的界面里确认文件名，或通过adb shell run-as com.example.app ls files/leakcanary/列出目录内容。拿到 hprof 后，除了看 LeakCanary 的结论，我一般会再看 Dominator Tree，确认一个泄漏对象实际霸占了多少内存，以及多个泄漏对象之间是否存在同一个根持有者。这样修复时能按“内存影响”排序，而不是按出现顺序挨个改。
5.2 自定义 LeakListener，把泄漏结果变成 CI 的失败信号
LeakCanary 默认只在手机端提示，没有人盯着手机时，泄漏回归很容易被忽略。把泄漏结果输出成可抓取的关键字，能让 CI 在跑完 UI 测试后自动判断“这次改动有没有引入新的内存泄漏”。
LeakCanary.config = LeakCanary.config.copy( onHeapAnalyzedListener = object : OnHeapAnalyzedListener { override fun onHeapAnalyzed(heapAnalysis: HeapAnalysis) { val leakCount = heapAnalysis.leaks.size if (leakCount > 0) { Log.e("LEAK_CI", "leak_count=$leakCount") } } } )这段代码在每次堆分析结束时统计泄漏数量，一旦大于 0 就打一条带固定标识的日志。CI 脚本在测试结束后执行一次 logcat 抓取即可：
adb logcat -d | grep LEAK_CI如果有输出，说明本轮测试存在泄漏，构建标记为失败；没有输出则视为通过。注意这种方式适合 debug 包和自动化测试机，release 包不引入 LeakCanary 相关逻辑，所以不会影响线上行为。
从那以后，我每次接手一个新项目，第一周都会先花半天把 LeakCanary 在 debug 包跑通，首屏、列表、详情页来回进出三五遍，先把 Activity 回收这条主链路看稳，再上线改内存问题。这个习惯看起来很笨，但遇到线上 OOM 时，手里至少有一张能复现的引用链图，排查效率完全不一样。希望帮到你。
本文还有配套的精品资源，点击获取
