flutter-debugging

日志记录

• 使用集中式 AppLogger 类记录所有日志：绝不使用 print() 或原始 debugPrint()
• 定义日志级别：verbose、debug、info、warning、error、fatal
• 在 dev flavor 中：记录所有级别的日志（从 verbose 及以上）
• 在 staging 中：记录 info 及以上级别的日志
• 在 production 中：仅记录 warning 及以上级别的日志，并发送至 Crashlytics
• 在日志中包含上下文：AppLogger.error('Failed to fetch user', error: e, stackTrace: st)
• 绝不记录任何级别的敏感数据（密码、令牌、个人身份信息）

Flutter DevTools

• 使用 Widget Inspector 调试布局问题并找出不必要的重建
• 使用 Performance Overlay（showPerformanceOverlay: true）监控帧率
• 使用 Timeline View 找出卡顿：目标为每帧 16ms（60fps）
• 使用 Memory View 检测内存泄漏并监控分配模式
• 使用 Network Profiler 在开发期间检查 Dio 请求/响应

调试策略

• 布局问题：使用 debugPaintSizeEnabled = true 可视化组件边界（参见 flutter-devtools）。
• 溢出错误：检查 RenderFlex overflowed：使用 Expanded、Flexible 或限制尺寸
• 高度无界：将 ListView 放入 SizedBox，或搭配 NeverScrollableScrollPhysics 使用 shrinkWrap: true
• 重建跟踪：临时添加 debugPrint('$runtimeType rebuild') 以找出过度重建（提交前移除）
• Agentic 热重载：在 Flutter 3.44+/Dart 3.12+ 中，AI 编码 Agent 和 MCP 服务会检测代码修改并自动触发热重载。保持调试守护进程运行（flutter run），以启用实时更新。
• 异步错误：始终在 try-catch 块中捕获并记录错误，同时附带堆栈跟踪
• 使用 assert() 检查开发时的不变量，这些检查会在发布构建中被移除

内存管理

• 在 dispose() 中释放所有控制器、订阅、Timer 和 AnimationController
• 在 initState() 中使用 late 初始化：绝不要内联初始化需要释放的对象
• 对不应阻止垃圾回收的缓存使用 WeakReference
• 使用 DevTools 的 Memory 标签页分析内存：留意分配量是否持续增长
• 留意常见的泄漏情况：未释放的监听器、捕获 BuildContext 的闭包、未取消的全局流

性能分析

• 始终在 --profile 模式（而非 debug 模式）下进行性能分析：flutter run --profile --flavor dev
• 对关键路径使用 Timeline.startSync / Timeline.finishSync 进行自定义性能跟踪
• Impeller 图形：Impeller 是 iOS 和 Android 上的默认渲染引擎。预编译着色器（SkSL 预热）已弃用，不再需要。如果出现渲染异常，请在终端中检查编译日志。
• 显示设备的目标指标：
  • 60Hz 屏幕：帧构建时间 < 16.6ms。
  • 90Hz 屏幕：帧构建时间 < 11.1ms。
  • 120Hz 屏幕：帧构建时间 < 8.3ms。
  • 屏幕切换：< 100ms。
  • 冷启动：< 2s。

错误边界

• 在 staging/prod 中将路由错误发送至 Crashlytics（FlutterError.onError = FirebaseCrashlytics.instance.recordFlutterFatalError）
• 设置 FlutterError.onError 和 PlatformDispatcher.instance.onError，以捕获框架错误和异步错误
• 在关键组件子树外包一层自定义错误边界组件，在发生错误时显示备用 UI，而不是红屏
• 在发布模式下：绝不向用户显示堆栈跟踪，只显示易于理解的错误消息

运行时错误分类

结合静态分析和类型系统知识，系统地分类并修复 Dart 运行时错误。

类型系统健全性

• 方法重写：保持返回类型（协变）和参数类型（逆变）的健全性。有意收紧参数类型时，使用 covariant 关键字。
• 泛型：为泛型类添加显式类型注解（使用 List<int>，而不是 List<dynamic>）。切勿将 List<dynamic> 赋给有类型的列表。
• 向下转型：避免从 dynamic 隐式向下转型。仅在运行时类型有保证时，使用显式强制转换（as Type）。
• 启用严格强制转换：在 analysis_options.yaml 中添加：

  analyzer:
    language:
      strict-casts: true
  

空安全错误模式

错误	原因	修复方法
Property cannot be accessed on nullable receiver	访问 Type? 的成员	使用 ?. 或进行空值检查
Non-nullable instance field must be initialized	非空字段未初始化	使用 late 或将其设为可空
The argument type can't be assigned	将 Type? 传给需要 Type 的位置	添加空值检查或使用 !（谨慎使用）

规则：

• 避免使用 ! 运算符：优先使用模式匹配或提前返回。
• 仅在首次访问前能保证已完成初始化时，才使用 late。
• 对未使用的变量使用 _ 通配符（Dart 3.7+）。

自动化解决工作流

# 1. Identify all errors
dart analyze . --fatal-infos

# 2. Preview automated fixes
dart fix --dry-run

# 3. Apply automated fixes
dart fix --apply