Flutter错误捕获插件——Catcher完全指南

Flutter错误捕获插件——Catcher完全指南

catcher Flutter error catching & handling plugin. Handles and reports exceptions in your app! 项目地址: https://gitcode.com/gh_mirrors/ca/catcher

项目介绍

Catcher是一款专为Flutter设计的错误捕获与处理插件。它自动捕捉应用程序中的错误和异常，并提供了多种方式来管理和报告这些问题。受ACRA（Android Crash Reporting）启发，Catcher支持Android、iOS、Web、Linux、Windows以及macOS等多个平台，提供了一站式的解决方案来增强您的应用稳定性。

项目快速启动

安装步骤

1. 在您的pubspec.yaml文件中添加依赖：

   dependencies:
     catcher: ^1.0.0-dev1
   

2. 运行命令安装依赖：

   flutter packages get
   

3. 导入Catcher到您的Dart文件中：

   import 'package:catcher/catcher.dart';
   

基础配置与启动

在您的main.dart文件中，配置并初始化Catcher：

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

void main() {
  // 步骤1: 创建Catcher配置
  CatcherOptions debugOptions = CatcherOptions(
    DialogReportMode(),
    handlers: [ConsoleHandler()],
  );
  
  CatcherOptions releaseOptions = CatcherOptions(
    DialogReportMode(),
    handlers: [
      EmailManualHandler(["support@example.com"]),
    ],
  );

  // 步骤2: 使用配置启动Catcher
  runApp(Catcher(
    rootWidget: MyApp(),
    debugConfig: debugOptions,
    releaseConfig: releaseOptions,
  ));

  // 设置导航器关键以支持报告页面跳转
  Catcher.navigatorKey.currentContext;
}

class MyApp extends StatefulWidget {
  @override
  _MyAppState createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      navigatorKey: Catcher.navigatorKey, // 步骤3: 添加导航器键
      home: Scaffold(body: ChildWidget()),
    );
  }
}

class ChildWidget extends StatelessWidget {
  void generateError() async {
    throw "Test exception";
  }

  @override
  Widget build(BuildContext context) {
    return TextButton(
      child: Text("生成错误"),
      onPressed: generateError,
    );
  }
}

当您点击“生成错误”按钮时，Catcher将捕获异常并通过配置的处理程序处理。

应用案例和最佳实践

错误报告模式

• Dialog Report Mode: 用户交互式报告，显示对话框让用户决定是否报告。
• Notification Report Mode: 通过系统通知报告错误。
• Silent Report Mode: 静默报告，不打扰用户，后台发送报告。
• Page Report Mode: 显示一个专门的报告页面给用户详情。

最佳实践：

• 在调试阶段使用DebugReportMode配合ConsoleHandler以便快速定位问题。
• 生产环境应启用多种报告模式，包括电子邮件自动发送，确保重要异常得以追踪。
• 考虑使用SentryHandler或CrashlyticsHandler集成更专业的崩溃分析服务。

典型生态项目整合

虽然本示例直接关注于Catcher本身的使用，但在实际项目中，结合如Sentry、Firebase Crashlytics等第三方错误报告工具是提高报告质量和分析效率的常见做法。例如，集成Sentry只需简单配置Catcher的SentryHandler：

// 引入sentry相关依赖
dependencies:
  sentry_flutter: ^版本号

// 在Catcher配置中加入SentryHandler
handlers: [
  SentryHandler(DiagnosticsCollector(true)), // 确保收集足够的诊断信息
],

通过这种方式，您可以利用Sentry强大的错误跟踪能力，同时享受Catcher带来的便利性，有效提升您的应用健壮性和用户体验。

---

本指南提供了Catcher插件的基本到进阶的使用方法，覆盖了从安装、基本配置到生态集成的最佳实践，帮助您在Flutter项目中高效地管理错误和异常。

catcher Flutter error catching & handling plugin. Handles and reports exceptions in your app! 项目地址: https://gitcode.com/gh_mirrors/ca/catcher