Flutter未预期异常通用处理方案实现技术问询

1. 自定义友好错误页面组件 #

先实现一个可复用的错误页面，包含通用提示和返回首页的导航功能：

import 'package:flutter/material.dart';

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

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('应用出错'),
        leading: IconButton(
          icon: const Icon(Icons.arrow_back),
          onPressed: () => _navigateToHome(context),
        ),
      ),
      body: Center(
        child: Padding(
          padding: const EdgeInsets.symmetric(horizontal: 24),
          child: Column(
            mainAxisAlignment: MainAxisAlignment.center,
            crossAxisAlignment: CrossAxisAlignment.center,
            children: [
              const Icon(
                Icons.error_outline,
                size: 64,
                color: Colors.redAccent,
              ),
              const SizedBox(height: 16),
              const Text(
                '抱歉，应用出现了未预期的问题',
                style: TextStyle(fontSize: 18, fontWeight: FontWeight.w500),
                textAlign: TextAlign.center,
              ),
              const SizedBox(height: 8),
              const Text(
                '点击下方按钮返回首页继续使用',
                style: TextStyle(fontSize: 14, color: Colors.grey),
                textAlign: TextAlign.center,
              ),
              const SizedBox(height: 32),
              ElevatedButton(
                onPressed: () => _navigateToHome(context),
                child: const Text('返回首页'),
              ),
            ],
          ),
        ),
      ),
    );
  }

  void _navigateToHome(BuildContext context) {
    // 清空导航栈，确保用户无法返回错误页面
    Navigator.of(context).pushNamedAndRemoveUntil('/home', (route) => false);
  }
}

2. 配置 ErrorWidget.builder #

替换Flutter构建阶段出错时默认显示的红屏：

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

void setupErrorHandling() {
  // 自定义构建错误时的显示组件
  ErrorWidget.builder = (FlutterErrorDetails details) {
    // 开发环境保留默认错误详情，方便调试
    if (kDebugMode) {
      return ErrorWidget(details.exception);
    }
    // 生产环境显示友好错误页面
    return const CustomErrorPage();
  };
}

3. 配置 FlutterError.onError #

捕获Flutter框架内部抛出的未处理异常（如Widget构建、渲染阶段的错误）：

void setupErrorHandling() {
  // ... 上述ErrorWidget配置代码
  
  FlutterError.onError = (FlutterErrorDetails details) {
    if (kDebugMode) {
      // 开发环境打印完整错误信息
      FlutterError.presentError(details);
    } else {
      // 生产环境将异常转发到平台级错误处理器统一处理
      PlatformDispatcher.instance.onError(details.exception, details.stack);
    }
  };
}

4. 配置 PlatformDispatcher.instance.onError #

捕获平台级别的未处理异常（如异步操作中未捕获的错误、原生层抛出的异常）：

void setupErrorHandling() {
  // ... 上述所有配置代码
  
  PlatformDispatcher.instance.onError = (Object error, StackTrace stack) {
    // 可选：添加错误日志上报逻辑（比如发送到服务器）
    // reportErrorToServer(error.toString(), stack.toString());

    // 强制切换到错误页面
    WidgetsBinding.instance.addPostFrameCallback((_) {
      final context = WidgetsBinding.instance.context;
      if (context != null) {
        Navigator.of(context).pushNamedAndRemoveUntil('/error', (route) => false);
      }
    });
    return true; // 标记异常已处理，阻止系统默认弹窗
  };
}

5. 集成到应用入口 #

在main函数中初始化错误处理，并注册路由：

void main() {
  // 确保WidgetsBinding初始化完成
  WidgetsFlutterBinding.ensureInitialized();
  
  // 启动错误处理配置
  setupErrorHandling();

  runApp(const MyApp());
}

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

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter 错误处理示例',
      initialRoute: '/home',
      routes: {
        '/home': (context) => const HomePage(), // 你的首页组件
        '/error': (context) => const CustomErrorPage(),
      },
    );
  }
}

// 示例首页组件
class HomePage extends StatelessWidget {
  const HomePage({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('首页')),
      body: const Center(child: Text('正常页面')),
    );
  }
}

核心注意事项 #

• 环境区分: 开发环境保留原生错误信息便于调试，生产环境切换为友好提示。
• 路由清理: 使用pushNamedAndRemoveUntil清空导航栈，避免用户回到错误状态页面。
• 复用性: 整个错误处理逻辑封装在setupErrorHandling函数中，可直接复制到其他Flutter项目使用。
• 日志上报: 可在PlatformDispatcher.onError中添加自定义日志上报，便于后续排查生产环境问题。

内容的提问来源于stack exchange，提问作者santos