跨平台开发 / 系统课时
捕获 Flutter 框架异常
捕获 Flutter 框架异常
本篇介绍如何接住 Flutter 框架层产生的异常,让构建失败、布局错误、框架回调异常等问题能够被统一记录。完成后可以建立基础错误入口,为线上日志和崩溃追踪提供可靠数据。
学习目标
- 理解 FlutterError 在框架异常处理中的作用。
- 配置全局 Flutter 框架异常入口并记录错误信息。
- 掌握常见框架异常的定位方式。
Flutter 框架异常的来源
Flutter 应用运行过程中,很多错误并不是 Dart 未捕获异常,而是由 Flutter 框架主动检测后报告。例如 Widget 构建失败、布局约束冲突、绘制阶段异常等,这些错误会通过 FlutterError 体系暴露。
默认情况下,Flutter 会将异常输出到调试控制台。在线上环境中,如果没有接入统一处理逻辑,这些错误可能无法进入日志系统,导致问题难以追踪。
Flutter 提供 FlutterError.onError 作为框架异常入口,可以在应用启动阶段替换默认处理行为。
配置全局异常入口
通常会在 main 方法中完成初始化,在运行应用前设置异常回调。
import 'package:flutter/material.dart';
void main() {
FlutterError.onError = (FlutterErrorDetails details) {
// 这里可以接入日志系统或错误追踪服务
FlutterError.presentError(details);
reportFlutterError(details);
};
runApp(const MyApp());
}
void reportFlutterError(FlutterErrorDetails details) {
final exception = details.exception;
final stackTrace = details.stack;
debugPrint('Flutter error: $exception');
debugPrint('Stack trace: $stackTrace');
}
class MyApp extends StatelessWidget {
const MyApp({super.key});
@override
Widget build(BuildContext context) {
return const MaterialApp(
home: Scaffold(
body: Center(child: Text('Flutter error handling')),
),
);
}
}预期结果
应用启动成功。
发生 Flutter 框架异常时,FlutterError.onError 会收到 FlutterErrorDetails。
日志中输出异常信息和堆栈信息。FlutterErrorDetails 包含异常对象、堆栈信息以及触发位置等上下文,可以将这些内容转换为错误事件发送给监控平台。
处理框架异常时的注意事项
FlutterError.onError 主要覆盖 Flutter 框架主动报告的问题,并不能捕获所有 Dart 异常。例如普通异步任务中的 Future 异常、原生平台异常等,需要其他入口处理。
生产环境中通常保留 FlutterError.presentError(details),这样仍能维持 Flutter 默认的错误输出能力,同时增加自己的上报逻辑。
什么时候使用 FlutterError
当问题发生在 Widget 生命周期、渲染流程、布局计算或 Flutter 框架内部调用链中时,优先检查 FlutterError.onError 是否收到事件。
如果线上日志显示页面构建失败但没有 Dart 未捕获异常记录,通常应该先确认 FlutterError 是否已经接入统一收集系统。