内容
description bug_report

Flutter 中的错误处理

内容

Flutter 框架会捕获由框架本身触发的回调期间发生的错误，包括构建、布局和绘制阶段遇到的错误。未在 Flutter 的回调中发生的错误无法被框架捕获，但你可以通过在 PlatformDispatcher 上设置错误处理程序来处理这些错误。

Flutter 捕获的所有错误都会路由到 FlutterError.onError 处理程序。默认情况下，这会调用 FlutterError.presentError，它会将错误转储到设备日志中。从 IDE 运行时，检查器会覆盖此行为，以便错误也可以路由到 IDE 的控制台，让你可以检查消息中提到的对象。

当在构建阶段发生错误时，将调用 ErrorWidget.builder 回调来构建用于替换失败的小组件。默认情况下，在调试模式下，它会显示一条红色的错误消息，在发布模式下，它会显示一个灰色背景。

当错误发生在没有 Flutter 回调的调用堆栈上时，它们将由 PlatformDispatcher 的错误回调处理。默认情况下，这只会打印错误，而不会执行其他操作。

你可以自定义这些行为，通常是通过在 void main() 函数中将它们设置为值来实现的。

下面解释了每种错误类型的处理方法。底部有一个处理所有类型错误的代码片段。即使你可以直接复制粘贴该片段，我们也建议你首先熟悉每种错误类型。

Flutter 捕获的错误

例如，要让你的应用程序在发布模式下捕获到任何错误时立即退出，你可以使用以下处理程序

import 'dart:io';

import 'package:flutter/foundation.dart';
import 'package:flutter/material.dart';

void main() {
  FlutterError.onError = (details) {
    FlutterError.presentError(details);
    if (kReleaseMode) exit(1);
  };
  runApp(const MyApp());
}

// rest of `flutter create` code...

此处理程序还可用于向日志记录服务报告错误。有关更多详细信息，请参阅我们的食谱章节，了解 向服务报告错误。

为构建阶段错误定义自定义错误小组件

要定义一个自定义错误小组件，以便在构建器无法构建小组件时显示，请使用 MaterialApp.builder。

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      builder: (context, widget) {
        Widget error = const Text('...rendering error...');
        if (widget is Scaffold || widget is Navigator) {
          error = Scaffold(body: Center(child: error));
        }
        ErrorWidget.builder = (errorDetails) => error;
        if (widget != null) return widget;
        throw StateError('widget is null');
      },
    );
  }
}

Flutter 未捕获的错误

考虑一个 onPressed 回调，它调用异步函数，例如 MethodChannel.invokeMethod（或几乎任何插件）。例如

OutlinedButton(
  child: const Text('Click me!'),
  onPressed: () async {
    const channel = MethodChannel('crashy-custom-channel');
    await channel.invokeMethod('blah');
  },
)

如果 invokeMethod 抛出错误，它将不会转发到 FlutterError.onError。相反，它会转发到 PlatformDispatcher。

要捕获此类错误，请使用 PlatformDispatcher.instance.onError。

import 'package:flutter/material.dart';
import 'dart:ui';

void main() {
  MyBackend myBackend = MyBackend();
  PlatformDispatcher.instance.onError = (error, stack) {
    myBackend.sendError(error, stack);
    return true;
  };
  runApp(const MyApp());
}

处理所有类型的错误

假设你希望在出现任何异常时退出应用程序，并在小组件构建失败时显示自定义错误小组件 - 你的错误处理可以基于以下代码片段

import 'package:flutter/material.dart';
import 'dart:ui';

Future<void> main() async {
  await myErrorsHandler.initialize();
  FlutterError.onError = (details) {
    FlutterError.presentError(details);
    myErrorsHandler.onErrorDetails(details);
  };
  PlatformDispatcher.instance.onError = (error, stack) {
    myErrorsHandler.onError(error, stack);
    return true;
  };
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      builder: (context, widget) {
        Widget error = const Text('...rendering error...');
        if (widget is Scaffold || widget is Navigator) {
          error = Scaffold(body: Center(child: error));
        }
        ErrorWidget.builder = (errorDetails) => error;
        if (widget != null) return widget;
        throw StateError('widget is null');
      },
    );
  }
}