【Flutter】程序報錯導致的灰屏總結
一、前言
在 Flutter 中，出現“灰屏”（grey screen）通常意味著 應用發生了未捕獲的錯誤，導致框架無法正確構建 UI。
這也是在面試過程中常常問到的。
二、錯誤分類
常見的會導致灰屏的錯誤主要集中在以下幾類：
1. Widget 構建異常
-
常見場景：
build()方法中拋出異常；- 使用了不存在的屬性或傳入非法值；
- 使用了
null導致構建崩潰。
-
示例錯誤：
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');});
}
3、灰屏排查
- 查看終端或 IDE 輸出日志；
- 使用 Flutter DevTools，查看 Widget 樹和性能分析；
- 打開
debugShowCheckedModeBanner = true保持調試標志； - 分段注釋掉 widget，逐步排查是哪段代碼導致的錯誤；
flutter run --verbose可以獲取更詳細日志。
四、關于作者(ZFJ_張福杰)
- 官網：https://zfjsafe.com
- 博客：https://zfj1128.blog.csdn.net
- Github：https://github.com/zfjsyqk
- Gitee：https://gitee.com/zfj1128
- 打賞：https://zfjsafe.com/paycode
