Flutter异常捕获与日志管理插件catcher_2的使用

介绍

Catcher 2 是一个Flutter插件，它可以自动捕捉错误/异常，并提供多种处理这些异常的方式。它是基于Jakub Homlala开发的Catcher进行改进和修复后的版本。

它受到ACRA（ACRA）的启发，支持Android、iOS、Web、Linux、Windows和MacOS平台。

安装

pubspec.yaml 添加依赖

dependencies:
  catcher_2: ^2.0.0-alpha.0

获取包

$ flutter packages get

导入

import 'package:catcher_2/catcher_2.dart';

升级自catcher

如果您之前正确使用了catcher，则只需替换以下字符串：

• Catcher -> Catcher2
• catcher -> catcher_2 (在少数地方需要使用catcher2)

注意：

• HttpHandler由于升级到dio 5.x有一些破坏性更改。

如果不确定或遇到问题，请提交新问题。

基本示例

下面是一个完整的例子，展示了如何配置和使用Catcher 2来捕捉异常并处理它们。

示例代码

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

void main() {
  /// 配置调试选项（开发模式下使用的设置）
  final debugOptions = Catcher2Options(
    /// 在对话框中显示捕获到的错误信息
    DialogReportMode(),
    [
      /// 将日志发送到HTTP服务器
      HttpHandler(
        HttpRequestType.post,
        Uri.parse('https://jsonplaceholder.typicode.com/posts'),
        printLogs: true,
      ),
      /// 在控制台打印日志
      ConsoleHandler(),
    ],
  );

  /// 配置生产选项（发布模式下使用的设置）
  final releaseOptions = Catcher2Options(
    /// 显示新页面，包含捕获到的错误信息
    PageReportMode(),
    [
      /// 将日志发送到Sentry
      SentryHandler(
        SentryClient(
          SentryOptions(dsn: '<DSN>'),
        ),
      ),
      /// 在控制台打印日志
      ConsoleHandler(),
    ],
  );

  /// 启动Catcher并启动应用程序。现在Catcher将守护并报告任何错误到您配置的服务！
  Catcher2(
    runAppFunction: () {
      runApp(const MyApp());
    },
    ensureInitialized: true,
    debugConfig: debugOptions,
    releaseConfig: releaseOptions,
  );
}

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

  @override
  State<MyApp> createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  @override
  void initState() {
    super.initState();
  }

  @override
  Widget build(BuildContext context) => MaterialApp(
        /// 最后一步：在这里添加Catcher的navigator key，以便Catcher可以显示页面和对话框！
        navigatorKey: Catcher2.navigatorKey,
        home: Scaffold(
          appBar: AppBar(
            title: const Text('Catcher example'),
          ),
          body: const ChildWidget(),
        ),
      );
}

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

  @override
  Widget build(BuildContext context) => TextButton(
        onPressed: generateError,
        child: const Text('Generate error'),
      );

  /// 触发一些错误。
  Future<void> generateError() async {
    Catcher2.sendTestException();
  }
}

更多功能

报告模式

Catcher 2 支持四种报告模式：

• Silent Report Mode：静默模式，不会询问用户是否处理崩溃日志，而是直接发送给处理器。
• Dialog Report Mode：对话框模式，通过对话框提示用户是否发送错误报告。
• Page Report Mode：页面模式，通过新页面提示用户是否发送错误报告。
• Notification Report Mode：通知模式（已移除，因为与Firebase不兼容）。

处理器

Catcher 2 提供了多种处理器用于处理错误报告：

• Console Handler：在控制台打印错误日志。
• Email Manual Handler：手动发送邮件。
• Email Auto Handler：自动发送邮件。
• Http Handler：通过HTTP请求发送日志。
• File Handler：将日志保存到文件。
• Toast Handler：以Toast形式显示短消息。
• Sentry Handler：发送错误报告到Sentry.io。
• Slack Handler：发送消息到Slack。
• Discord Handler：发送消息到Discord。
• Snackbar Handler：显示定制化的Snackbar消息。
• Crashlytics Handler：已被移除，但可以通过自定义报告模式重新启用。

错误小部件

您可以添加一个错误小部件来替代红色死亡屏幕。具体方法如下：

builder: (BuildContext context, Widget widget) {
  Catcher2.addDefaultErrorWidget(
    showStacktrace: true,
    title: "Custom error title",
    description: "Custom error description",
    maxWidthForSmallMode: 150,
  );
  return widget;
},

获取当前配置

获取当前使用的配置：

Catcher2Options options = catcher2.getCurrentConfig();

更新配置

在运行时更新Catcher 2配置：

catcher2.updateConfig(
  debugConfig: Catcher2Options(
    PageReportMode(),
    [ConsoleHandler()],
  ),
);

截图功能

Catcher 2可以在报告中自动创建并包含截图。只需要用Catcher2Screenshot包装您的根组件，并提供截图存储路径即可。

MaterialApp(
  navigatorKey: Catcher2.navigatorKey,
  home: Catcher2Screenshot(
    catcher2: Catcher2.getInstance(),
    child: Scaffold(
      appBar: AppBar(
        title: const Text('Plugin example app'),
      ),
      body: ChildWidget(),
    ),
  ),
);

final Catcher2Options debugOptions = Catcher2Options(
  DialogReportMode(),
  [ToastHandler()],
  screenshotsPath: path,
);

以上就是关于Flutter异常捕获与日志管理插件catcher_2的基本使用说明。希望对您有所帮助！