1. 从一次线上卡顿说起Android 内存泄漏到底怎么定位Android 内存泄漏这个词很多同学第一次遇到是在 App 用久了开始卡、滑动掉帧、甚至切后台回来直接白屏重启的时候。它的本质并不玄学一块本该被 GC 回收的内存因为某条引用链还活着被一直攥在手里。堆里的对象越积越多GC 越来越频繁单次停顿越来越长最后 OOM 崩掉。它和「内存不够用」是两回事——泄漏是引用关系出了问题不是物理内存消失了。我在排查这类问题时最头疼的从来不是「有没有泄漏」而是「泄漏在哪条引用链上」。LeakCanary 能告诉你某个 Activity 泄漏了但它给出的 trace 往往是一长串this$0、匿名内部类、静态集合你得自己顺着链子往回找。而真正定位根因通常要结合三样东西可复现的操作路径、堆转储hprof、以及能读懂引用链的分析工具。这篇聚焦 Android 应用内存泄漏的定位与分析方法会交付可复制的 LeakCanary 配置片段、MAT 分析步骤和验证动作。同时我会把调试链路里用到的统一 Key/API 通道接进来——当你在排查过程中需要调用模型辅助解读堆栈、生成分析脚本或者团队多人协作时统一管理调试用的 API 凭证一个统一的 Key 通道能省掉很多「谁的 Key 又过期了」的扯皮。适合已经能跑起 App、但对内存分析还停留在「看 Logcat 猜」阶段的 Android 开发者。先说清楚一个判断标准避免你走弯路单次 GC 后data object的 Total Size 不回落且随操作次数单调上涨才大概率是泄漏。如果只是操作时涨、停下来就回落那叫正常的内存抖动不用慌。这个判断方法后面会用 DDMS Heap 和 Memory Profiler 具体演示。2. 前置准备LeakCanary 接入与 TaoToken 统一 Key 通道配置在动手抓泄漏之前得先把「检测工具」和「调试链路」两件事准备好。检测工具是 LeakCanary调试链路是 TaoToken 的统一 Key 通道——后者不是内存分析必需的但在实际排查里很实用比如你 dump 出一份 hprof想快速让模型帮你梳理可疑引用链或者写个脚本批量解析 leak trace这时候有个稳定的 API 入口会顺手很多。2.1 LeakCanary 依赖与 Application 初始化LeakCanary 2.x 之后 API 变化较大网上很多老教程还在用debugCompile那是 1.x 的写法直接抄会编译不过。下面是当前可用的 Gradle 配置注意区分 debug 和 release// app/build.gradle dependencies { debugImplementation com.squareup.leakcanary:leakcanary-android:2.14 // release 不需要引入LeakCanary 2.x 默认只在 debug 生效 }LeakCanary 2.x 最大的变化是不需要手动 install。它通过 ContentProvider 自动初始化你只要加上依赖跑 debug 包它就会自动监控 Activity、Fragment、ViewModel、Service 等对象的回收情况。如果你确实需要手动拿到AppWatcher或ObjectWatcher来监控自定义对象可以这样写// 监控一个本该被回收的自定义对象 val watcher AppWatcher.objectWatcher watcher.expectWeaklyReachable(myObject, MyObject should be GCed after logout)expectWeaklyReachable的第二个参数是描述泄漏报告里会显示建议写清楚业务语义比如「退出登录后应回收的 UserSession」。2.2 TaoToken 统一 Key 通道的接入排查内存泄漏时我经常需要把 leak trace 丢给模型做初步归类或者让它帮我生成一段解析 hprof 引用链的脚本。团队里如果每个人都用自己的 Key额度、过期、权限都难管。TaoToken 提供统一 Key/API 通道把调试链路的凭证收敛到一处。接入方式很简单先到控制台创建 API Key控制台入口https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewriteAPI Key 管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite拿到 Key 之后Base URL 统一用https://taotoken.net/api注意这个地址不带 UTM 参数是给程序调用的。如果你在 Android 项目里想通过 OkHttp 调用配置片段如下// 统一从 BuildConfig 或本地配置读取不要硬编码进仓库 val client OkHttpClient.Builder() .addInterceptor { chain - val request chain.request().newBuilder() .addHeader(Authorization, Bearer ${BuildConfig.TAOTOKEN_API_KEY}) .addHeader(Content-Type, application/json) .build() chain.proceed(request) } .build()这里有个坑要提醒不要把 API Key 提交到 Git。用local.properties或者 CI 的环境变量注入然后在build.gradle里读出来写进BuildConfig。我见过太多人图省事直接写在代码里结果 Key 泄露被刷额度。如果你用的是 Claude Code 这类编码工具做辅助排查它需要三件套Base URL、API Key、Model ID。Base URL 填https://taotoken.net/apiKey 填上面创建的Model ID 按你实际使用的模型填。这三者缺一不可只填 Key 不填 Base URL 会走到默认端点报 401 或连接失败。2.3 一个容易忽略的前置动作确认 debug 包LeakCanary 只在 debug 包生效如果你在 release 包里测半天没反应先检查BuildConfig.DEBUG。另外有些项目会自定义debuggable变体比如staging这时候 LeakCanary 可能不自动初始化需要手动处理。确认方法跑起来后看通知栏有没有 LeakCanary 的图标或者看 Logcat 有没有LeakCanary相关日志。3. 可复制配置LeakCanary 自定义与 MAT 分析环境搭建工具装好了接下来是让它按你的需求工作。默认配置能覆盖大部分场景但真实项目里往往需要自定义——比如过滤掉已知的第三方库误报、调整保留的 trace 数量、把报告上传到内网服务器。这一节给出可直接复制的配置片段以及 MAT 分析环境的搭建步骤。3.1 LeakCanary 自定义配置LeakCanary 2.x 支持通过LeakCanary.Config定制行为。下面这段配置做了三件事保留最近 20 份 trace、忽略已知的第三方误报、设置 retained visible threshold可见对象保留阈值// 在 Application.onCreate 中配置 class MyApp : Application(), LeakCanary.ConfigFactory { override fun onCreate() { super.onCreate() LeakCanary.config LeakCanary.config.copy( retainedVisibleThreshold 3, maxStoredHeapDumps 20, dumpHeap true ) } override fun createConfig(): LeakCanary.Config { return LeakCanary.config.copy( // 忽略已知误报的引用链 referenceMatchers AndroidReferenceMatchers.appDefaults IgnoredReferenceMatcher( InstanceFieldReferenceMatcher( android.os.Build, TAG, java.lang.String ) ) ) } }retainedVisibleThreshold这个参数值得说一下它表示「一个对象被判定为泄漏前需要经历几次 GC 仍然存活」。默认是 5调低到 3 能更快出报告但误报率会上升调高则更准但更慢。调试阶段建议 3稳定后回到 5。如果你想把 trace 上传到自己的服务器做聚合分析可以实现OnHeapAnalyzedListenerLeakCanary.config LeakCanary.config.copy( onHeapAnalyzedListener OnHeapAnalyzedListener { heapAnalysis - // 这里可以把 heapAnalysis 序列化后上传 uploadToServer(heapAnalysis) // 别忘了调用默认行为否则通知栏不显示 DefaultOnHeapAnalyzedListener.create().onHeapAnalyzed(heapAnalysis) } )3.2 MAT 环境搭建与 hprof 转换LeakCanary 给的是「哪个对象泄漏了」MAT 给的是「为什么泄漏」——完整的引用链。MAT 现在叫 Eclipse Memory Analyzer独立客户端可以从官网下载。装好后第一步不是直接打开 hprof而是先转换格式。Android 的 hprof 和标准 Java hprof 格式不同直接导入 MAT 会报Unknown HPROF Version (JAVA PROFILE 1.0.3)。转换命令在 Android SDK 的 platform-tools 里# 找到 hprof-conv通常在 $ANDROID_HOME/platform-tools/ $ANDROID_HOME/platform-tools/hprof-conv input.hprof output.hprof转换完再导入 MAT。生成 hprof 有两种方式一是 LeakCanary 检测到泄漏后自动 dump文件在 App 的私有目录二是手动触发用 Android Studio 的 Profiler或者代码里调// 手动 dump注意要在子线程执行主线程会卡死 Thread { val file File(cacheDir, manual_dump.hprof) Debug.dumpHprofData(file.absolutePath) }.start()Debug.dumpHprofData会暂停整个进程Stop-The-World大堆可能卡几秒别在主线程调。3.3 用 TaoToken 辅助解析 traceMAT 的引用链视图对新手不太友好一屏几十个节点。我的做法是先把 leak trace 文本丢给模型做初步归类让它标出「最可能的持有者」。调用时用统一通道curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: your-model-id, messages: [ {role: user, content: 分析这段 Android leak trace指出最可能的泄漏持有者和修复方向\ntrace 内容} ] }注意model字段要填你实际可用的 Model ID不是随便写。如果返回 401先检查 Key 和 Base URL 是否配对如果返回reading choices相关错误通常是响应体解析问题检查返回 JSON 结构。4. 验证请求与成功结果从泄漏报告到根因确认配置齐了现在走一遍完整流程制造一个泄漏、让 LeakCanary 抓到、用 MAT 定位、修复后验证。这一节用前面 excerpt 里提到的静态字段泄漏做例子因为它最常见也最好复现。4.1 制造一个可复现的泄漏写一个单例持有 Activity 的 Viewobject StaticHolder { var leakedView: View? null } class LeakActivity : AppCompatActivity() { override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContentView(R.layout.activity_leak) val textView findViewByIdTextView(R.id.test_text_view) StaticHolder.leakedView textView // 泄漏点 } }StaticHolder是 objectKotlin 单例等价于 Java 静态实例它持有textView而textView持有 Activity 的 Context。Activity finish 后这条链还在Activity 无法回收。4.2 触发检测与读取报告跑 debug 包进入LeakActivity再退出反复几次。LeakCanary 会在后台做 GC 和 heap dump几秒后通知栏弹出泄漏报告。点进去能看到LeakActivity has leaked: * GC ROOT static StaticHolder.leakedView * references android.widget.TextView * leaks LeakActivity instance关键信息是GC ROOT static StaticHolder.leakedView——GC Root 是静态字段它引用了 TextViewTextView 又引用了 Activity。修复方向很明确在onDestroy里把leakedView置空。override fun onDestroy() { super.onDestroy() StaticHolder.leakedView null }4.3 用 MAT 确认引用链LeakCanary 的报告已经够用了但如果你想看完整链路比如中间隔了好几层就上 MAT。导入转换后的 hprof用Histogram找到LeakActivity的实例数右键Merge Shortest Paths to GC Roots→exclude weak/soft references就能看到从 GC Root 到 Activity 的最短路径。MAT 里有个实用功能叫Path to GC Roots配合Dominator Tree用。Dominator Tree 按 retained size 排序能快速找到「谁占的内存最多」。如果某个对象 retained size 异常大顺着它的引用链往下看往往就是泄漏点。4.4 验证修复修复后重新跑重复进入退出LeakActivity十几次。观察两个指标一是 LeakCanary 不再弹报告二是用 Android Studio Profiler 看内存曲线操作时上涨、停下来后回落并稳定。如果 LeakCanary 还报但报的是别的对象说明这个泄漏修好了还有下一个——内存泄漏往往是一窝修完一个继续抓。这里插一句验证阶段如果要用模型帮你对比修复前后的 hprof 差异同样走统一通道即可模型对话入口在 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite 把两份 trace 贴进去让它找差异比人眼快。5. 本篇常见错误排查401、local proxy failed 与 reading choices排查过程中踩的坑八成集中在工具链的连接和配置上。这一节把高频报错和对应解法列出来都是真实遇到过的。5.1 401 Unauthorized调用 API 时最常见。原因通常有三个Key 没带、Key 过期、Base URL 和 Key 不匹配。检查顺序# 先确认环境变量有没有值 echo $TAOTOKEN_API_KEY # 再确认请求头格式Bearer 后面有个空格 curl -v https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d {model:your-model-id,messages:[{role:user,content:hi}]}如果echo是空的说明环境变量没导出如果 Key 有值还 401去控制台确认 Key 状态和额度。注意 Base URL 用https://taotoken.net/api不要多加/v1之外的路径。5.2 local proxy failed这个报错通常出现在你本地配了代理但代理没起来或者端口不对。Android 项目里如果 OkHttp 走了系统代理而代理进程挂了就会报local proxy failed或Failed to connect to /127.0.0.1:xxxx。解法检查OkHttpClient有没有显式设置proxy或者系统代理设置是否残留。调试阶段建议先关掉代理直连确认链路通了再考虑代理。5.3 reading choices 相关解析错误调用返回 200 但解析失败报reading choices或Cannot read property choices of undefined说明响应体结构和预期不符。常见原因是请求体 JSON 格式错误导致服务端返回了错误对象而非标准响应。检查你的messages数组是否合法、model字段是否填了有效值。用curl先验证一遍确认返回结构里有choices数组再写进代码。5.4 LeakCanary 不报泄漏明明有泄漏却不报检查这几点是不是 release 包LeakCanary 只在 debug 生效retainedVisibleThreshold是不是设太高对象是不是被弱引用持有弱引用不算泄漏是不是在onDestroy之后立刻被回收了那本来就不是泄漏。还有一种情况泄漏对象太小LeakCanary 默认会忽略小于阈值的对象可以在 config 里调retainedVisibleThreshold。5.5 hprof 导入 MAT 报版本错误前面提过Unknown HPROF Version是因为没转换格式。用hprof-conv转一遍。如果转换后还报错检查 hprof 文件是不是完整——dump 过程中进程被杀会导致文件损坏重新 dump 一次。5.6 Claude Code / Codex 接入时的三件套缺失如果你用 Claude Code 或 Codex 辅助排查配置里必须同时有 Base URL、API Key、Model ID。只填 Key 会走默认端点导致 401只填 Base URL 没 Key 会 403Model ID 填错会报模型不存在。三件套齐全后如果还连不上检查网络是否能访问https://taotoken.net/api。Claude Code 的接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有完整的配置示例。6. 把排查链路固化下来长期编码与团队协作的接入方式单次排查靠手动操作没问题但如果内存泄漏是团队长期要面对的课题就得把链路固化。我的做法是把 LeakCanary 的报告聚合、MAT 分析脚本、以及模型辅助解读串成一条流水线新人接手时照着文档跑一遍就能上手。对于需要长期做编码和 Agent 辅助的团队Coding Plan 是个更省心的选择入口在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。它把额度、模型、Key 管理打包不用每次新建项目都重新配一遍。特别是多人协作时统一通道能避免「张三的 Key 能调、李四的不能」这种问题。具体到内存泄漏排查我固化的流程是这样的CI 上跑 monkey 测试触发各种页面跳转同时开启 LeakCanary 的自动 dumpdump 出来的 hprof 和 trace 上传到内网每天定时用脚本批量解析把新增的泄漏类型归类对于无法自动归类的人工用 MAT 看引用链必要时通过统一通道调模型辅助。这套流程跑下来新出现的泄漏基本能在一天内定位到具体代码。最后给一个实用技巧在onDestroy里加断言。对于你明确知道应该被回收的对象在 debug 包里加一段检查如果几秒后还在主动打日志。这比等 LeakCanary 异步报告更即时override fun onDestroy() { super.onDestroy() val ref WeakReference(this) Handler(Looper.getMainLooper()).postDelayed({ if (ref.get() ! null) { Log.e(LeakCheck, Activity not GCed after destroy!) } }, 5000) }这段代码用弱引用持有 Activity5 秒后检查是否被回收。如果还在说明有强引用链没断。配合 LeakCanary 的报告能快速缩小范围。注意这只是在 debug 包里用的辅助手段别带到 release。内存泄漏排查没有银弹核心就是「可复现路径 堆转储 引用链分析」这三板斧。工具会帮你省力但读懂引用链、判断哪条链是异常的还是得靠对业务和框架的理解。多抓几次手感就出来了。