【Flutter】程序报错导致的灰屏总结

一、前言

在 Flutter 中，出现“灰屏”（grey screen）通常意味着 应用发生了未捕获的错误，导致框架无法正确构建 UI。

这也是在面试过程中常常问到的。

二、错误分类

常见的会导致灰屏的错误主要集中在以下几类：

1. Widget 构建异常

常见场景：
- build() 方法中抛出异常；
- 使用了不存在的属性或传入非法值；
- 使用了 null 导致构建崩溃。

示例错误：

@override
Widget build(BuildContext context) {return Text(null); // Text 的参数不能为空
}

日志表现：

Error building widget: NoSuchMethodError: The method '[]' was called on null.

2. 异步错误未捕获

比如 FutureBuilder 中异步调用抛出异常，但没有处理。

示例：

FutureBuilder(future: fetchData(), // 如果这个方法抛异常builder: (context, snapshot) {return Text(snapshot.data); // snapshot.data 为 null 或出错},
);

3. 状态管理错误

常见场景：
- setState 调用时 widget 已经被 dispose；
- Provider, Bloc, Riverpod 等状态访问不当。

示例：

setState(() {// 此时 widget 已经 dispose，Flutter 崩溃
});

4. 路由错误

常见场景：
- 路由名称未注册；
- 参数传递有误；

示例：

Navigator.pushNamed(context, "/non_existing_route");

5. 资源加载失败

比如图片路径写错、字体加载失败；

示例：

Image.asset('assets/images/xxx.png') // 图片不存在

6. 平台通道 (Platform Channel) 错误

调用了 native 方法，但没有注册、回调类型错误；
导致 MethodChannel 调用失败而没有处理。

三、异常处理

1、全局异常未处理

没有设置 FlutterError.onError；

建议：

FlutterError.onError = (FlutterErrorDetails details) {FlutterError.presentError(details);// 上报错误或处理逻辑
};

2、开启调试辅助功能

在 main() 中添加以下代码可以更好捕捉错误：

void main() {FlutterError.onError = (FlutterErrorDetails details) {FlutterError.presentError(details);// 可在此上报日志};runZonedGuarded(() {runApp(MyApp());}, (Object error, StackTrace stackTrace) {// 捕捉 zone 范围内的未处理异常print('Uncaught zone error: $error');});
}