Flutter Framework 泄漏追踪(Leak Tracking)实战指南:让 Widget 测试自动发现未释放对象

原创2026-10-14 11:59:551,612 阅读
文章标签:跨平台移动开发OpenHarmony图形学开发工具UI组件构建工具

Flutter Framework 泄漏追踪(Leak Tracking)实战指南:让 Widget 测试自动发现未释放对象

本指南以 docs/contributing/testing/Leak-tracking.md 为骨架,结合 CPF-Flutter OpenHarmony 适配仓库(flutter_flutter)中 packages/flutter 与 packages/flutter_test 的实际源码,系统讲解 Flutter Framework 的泄漏追踪机制:如何在本地一键开启、失败信息如何解读、默认行为是什么,以及何时可以安全地对单个测试豁免泄漏检查。读完本文,你将掌握一套可立即落地到日常 widget 测试中的内存泄漏检测工作流。

快速上手:一行命令开启泄漏追踪

在 Flutter Framework 的 widget 测试中开启泄漏追踪非常简单,只需在运行 flutter test 时传入一个编译期参数:

flutter test --dart-define LEAK_TRACKING=true

该参数对当前目录下的所有 testWidgets 生效。也可以改用环境变量方式(见下文“配置入口”一节),二者效果等价。

说明:本仓库是 Flutter SDK/Engine 的 OpenHarmony 适配版,上述命令适用于本地开发机上的 Framework 测试;若你在 OpenHarmony 环境下运行测试,请以本仓库 ci/scripts/run_parallel_shards.sh 中的实际调用方式为准。

泄漏追踪做了什么

Flutter Framework 的 widget 测试借助 Dart 生态的 leak_tracker 系列包来检测未被 dispose 的对象。其核心思想是:测试过程中创建的 Disposable 对象(如 FocusNode、AnimationController、各种 ChangeNotifier 等)应在测试结束前完成释放;凡是创建了却没有被释放、且仍被引用(无法被 GC 回收)的对象,都会被报告为泄漏。

在本仓库中,相关依赖声明在 packages/flutter/pubspec.yaml:

leak_tracker_flutter_testing: any
leak_tracker_testing: any
leak_tracker: any

而 flutter_test 包的 packages/flutter_test/pubspec.yaml 同样依赖 leak_tracker_flutter_testing,testWidgets 测试框架在底层与它联动(详见 packages/flutter_test/lib/src/test_compat.dart)。

解读失败信息:泄漏长什么样

开启泄漏追踪后,如果某个测试存在泄漏,失败信息大致如下:

Expected: leak free
    Actual: <Instance of 'Leaks'>
     Which: contains leaks:
            # The text is generated by leak_tracker.
            # For leak troubleshooting tips open:
            # https://github.com/flutter/flutter/blob/main/docs/contributing/testing/Leak-tracking.md
            notDisposed:
              total: 1
              objects:
                FocusNode:
                  test: Align smoke test
                  identityHashCode: 82308154

逐字段解读:

  • notDisposed:统计“已创建但未释放”的泄漏对象。与之相对的是 notGCed(已释放却仍被引用、无法被 GC 回收)。两类泄漏都会被 leak_tracker 区分统计。
  • total: 1:该类别下泄漏对象总数。
  • FocusNode:泄漏对象的运行时类型。
  • test: Align smoke test:泄漏发生在哪个测试中。
  • identityHashCode: 82308154:该对象的身份哈希,用于在调试器中定位具体实例。

值得留意的是,失败信息中自带的排查文档链接,正是由本仓库的测试配置注入的(见下文“配置入口”)。

配置入口:flutter_test_config.dart 源码解析

本仓库中,泄漏追踪的全局配置位于 packages/flutter/test/flutter_test_config.dart,它对 packages/flutter/test 目录下每一个测试库生效(即每个测试文件运行前都会执行其中的 testExecutable)。

开启判断的核心函数如下(flutter_test_config.dart):

bool _isLeakTrackingEnabled() {
  if (kIsWeb) {
    return false;
  }
  // The values can be different, one is compile time, another is run time.
  return const bool.fromEnvironment('LEAK_TRACKING') ||
      (bool.tryParse(Platform.environment['LEAK_TRACKING'] ?? '') ?? false);
}

这里揭示了两个关键事实:

  1. 两种开启方式:编译期参数 --dart-define LEAK_TRACKING=true 通过 bool.fromEnvironment 读取;运行期环境变量 LEAK_TRACKING=true 通过 Platform.environment 读取。二者取“或”关系,任一为真即开启。
  2. Web 平台默认关闭:kIsWeb 时直接返回 false,原因是 Web 引擎存在已知的泄漏场景(详见 testWidgets 源码中的相关注释,见 packages/flutter_test/lib/src/widget_tester.dart)。

开启后执行的具体配置(flutter_test_config.dart):

if (_isLeakTrackingEnabled()) {
  LeakTesting.enable();
  LeakTracking.warnForUnsupportedPlatforms = false;
  // Customized link to documentation on how to troubleshoot leaks,
  // to print in the error message.
  LeakTracking.troubleshootingDocumentationLink =
      'https://github.com/flutter/flutter/blob/main/docs/contributing/testing/Leak-tracking.md';
  LeakTesting.settings = LeakTesting.settings.withIgnored(createdByTestHelpers: true);
}

配置要点:

  • LeakTesting.enable():全局启用泄漏追踪。
  • LeakTracking.troubleshootingDocumentationLink:定制失败信息中打印的排查文档链接,这正是上面失败输出中那一行注释的来源。
  • LeakTesting.settings.withIgnored(createdByTestHelpers: true):忽略由测试辅助工具(test helpers)创建的对象,避免测试框架自身的临时对象被误报为泄漏。

默认行为:CI 与本地默认值

上游 CI 的两个专用分片

在原版 Flutter 的测试基础设施中,泄漏追踪默认在两个 CI 分片上开启:

  • Windows framework_tests_libraries_leak_tracking
  • Windows framework_tests_widgets_leak_tracking

即 Framework 的“libraries”测试与“widgets”测试各有一个专属的泄漏追踪分片。本仓库(OHOS 适配版)的 CI 采用了不同的组织方式:framework 测试的并行分片由 ci/scripts/run_parallel_shards.sh 统一启动,其中包含 framework_tests libraries 与 framework_tests widgets 等多个分片(run_parallel_shards.sh)。需要在本仓库 CI 中开启泄漏追踪时,可在对应分片的启动命令中追加 --dart-define LEAK_TRACKING=true。

本地默认值

本地运行 flutter test 时,泄漏追踪默认关闭。要让所有 widget 测试启用泄漏检查,执行:

flutter test --dart-define LEAK_TRACKING=true

或设置环境变量后运行:

export LEAK_TRACKING=true
flutter test

两种方式效果相同(源码中二者是“或”关系)。

何时可以豁免(opt-out)某个测试

总的原则是:泄漏追踪应当保持开启,以验证所有 disposable 对象都被正确释放。若确实需要对某个测试豁免,必须在注释中清晰说明原因。

唯一明确允许豁免的场景是:测试抛出了异常,导致代码路径没有正常完成 finalize。虽然从理想角度讲,异常路径中的 disposable 也应被妥善释放,但 Flutter 团队尚未将“保证异常代码路径下对象全部释放”作为优先事项(参见上游 issue #157470)。因此,这类因异常中断而“非自愿”产生的泄漏,可以豁免。

豁免的三种粒度

从 flutter_test 的源码可以看到,泄漏追踪支持不同粒度的控制:

  1. 按测试豁免(推荐):testWidgets 提供了实验性参数 experimentalLeakTesting,将其设为 LeakTrackingForTests.ignore() 即可关闭单个测试的泄漏检查。相关说明见 packages/flutter_test/lib/src/widget_tester.dart:

    /// To turn off leak tracking just for one test, set [experimentalLeakTesting] to
    /// `LeakTrackingForTests.ignore()`.
    
  2. 按文件/包调整全局设置:在测试文件的 main() 中(注意:不要放在 setUp 或 setUpAll 里)修改 LeakTesting.settings;对整个目录生效的设置则放在对应目录的 flutter_test_config.dart 中。

  3. 豁免测试辅助对象:全局配置已通过 withIgnored(createdByTestHelpers: true) 忽略由测试 helpers 创建的对象。

测试生命周期中的挂钩时机

testWidgets 在每个测试执行前后都会调用泄漏追踪的挂钩:

另外,当 LeakTesting.enabled 为真时,flutter_test 会自动在每个测试文件末尾追加一次 tearDownAll,调用 maybeTearDownLeakTrackingForAll() 汇总该文件所有测试的泄漏结果(见 packages/flutter_test/lib/src/test_compat.dart)。这保证了即使单个测试未显式校验,文件级汇总报告也不会遗漏。

仓库内测试基建:如何验证泄漏检测本身

本仓库自带了一套用于验证泄漏检测机制自身的测试,可作为理解其行为的绝佳样例。

基准测试用例集

packages/flutter_test/test/utils/memory_leak_tests.dart 定义了 memoryLeakTests 用例集,覆盖了四种典型场景:

用例名 行为 预期泄漏
no leaks pump 一个普通 Container 无
not disposed disposable 创建 InstrumentedDisposable 但从不释放 notDisposedTotal: 1
not GCed disposable 释放后仍被全局 _retainer 引用 notGCedTotal: 1
leaking widget 创建会泄漏的 StatelessLeakingWidget notDisposedTotal: 1、notGCedTotal: 1

此外还有 dispose in tear down 等用例,验证通过 addTearDown 释放对象是否能被正确识别。这些用例直观展示了 notDisposed(未释放)与 notGCed(已释放但未被 GC)两类泄漏的判定边界——这也是你排查真实泄漏时首先要区分的两种情况。

驱动这些用例的测试入口

packages/flutter_test/test/widget_tester_leaks_test.dart 是上述用例的执行入口:它启用 LeakTesting.enable(),并针对每一条用例、每一种 LeakTesting 设置组合运行 testWidgets(..., experimentalLeakTesting: settings, ...),最后通过自定义的 _verifyLeaks 校验结果(见该文件 widget_tester_leaks_test.dart)。

Framework 内的真实使用

在 packages/flutter 的各类测试中,experimentalLeakTesting: LeakTesting.settings 被广泛使用——例如 packages/flutter/test/widgets/async_lifecycle_test.dart、packages/flutter/test/material/app_test.dart、packages/flutter/test/widgets/framework_test.dart 等,用于让特定测试显式参与泄漏检查(即使全局默认未开启时也能单独验证)。当你需要为某个测试单独开启/关闭泄漏检查时,可以直接仿照这种写法。

实践建议与排查思路

  1. 本地开启、CI 兜底:本地开发时优先使用 flutter test --dart-define LEAK_TRACKING=true 全量运行,第一时间发现新增泄漏;在 CI 中为 libraries/widgets 分片常驻开启泄漏追踪,防止回归。
  2. 优先排查 notDisposed:失败输出中的 notDisposed 通常指向某个忘记调用 dispose() 的 controller、FocusNode 或 StreamSubscription,修复方式是在测试内显式 dispose 或通过 addTearDown 注册释放。
  3. 区分 notGCed:对象已释放却仍被全局/静态引用持有,属于引用清理问题,检查是否有静态容器或单例缓存了该对象。
  4. 豁免要写注释:对确需豁免的测试,用 experimentalLeakTesting: LeakTrackingForTests.ignore() 关闭并注明原因(例如“该测试预期抛异常,异常路径尚未保证 finalize”),不要无理由地大范围关闭泄漏检查。
  5. 以本仓库源码为最终依据:本文涉及的所有行为均可直接在本仓库源码中验证——全局配置见 packages/flutter/test/flutter_test_config.dart,testWidgets 的挂钩逻辑见 packages/flutter_test/lib/src/widget_tester.dart,文件级汇总见 packages/flutter_test/lib/src/test_compat.dart。具体版本行为请以当前仓库实际代码为准。
登录后查看全文
flutter_flutter