Fluttertpc Catcher 在鸿蒙系统上的使用指南

Fluttertpc Catcher 是一款强大的 Flutter 错误捕获插件，支持自动捕获未处理异常并提供多种报告模式（静默/通知/对话框/页面）和处理方式（控制台输出/邮件发送/HTTP请求等）。该插件支持多语言本地化和自定义配置，适用于开发调试和生产环境错误收集。安装需通过 Git 引入依赖，集成简单。插件提供丰富的 API，包括四种报告模式和十种处理方式，并支持手动报告错误。在鸿蒙系统中

b13053810049

513人浏览 · 2025-12-21 21:55:14

b13053810049 · 2025-12-21 21:55:14 发布

插件介绍

Fluttertpc Catcher 是一个功能强大的 Flutter 插件，用于自动捕获和处理应用程序中的错误和异常。它提供了多种错误处理方式和报告模式，可以帮助开发者快速定位和解决应用程序中的问题。

核心功能

自动捕获错误：自动捕获应用程序中未处理的异常和错误
多种报告模式：支持静默模式、通知模式、对话框模式和页面模式
多种处理方式：支持控制台输出、邮件发送、HTTP 请求、文件存储等
本地化支持：支持多语言本地化
自定义配置：可以根据开发环境和生产环境配置不同的错误处理策略

适用场景

开发过程中的错误调试
生产环境中的错误收集和分析
应用程序崩溃报告
用户反馈收集

安装与集成

添加依赖

由于这是一个自定义修改版本的三方库，需要以 Git 形式引入。在 pubspec.yaml 中添加以下配置：

dependencies:
  catcher:
    git:
      url: "https://atomgit.com/openharmony-sig/fluttertpc_catcher.git"
      path: "fluttertpc_catcher"

安装依赖

运行以下命令安装依赖：

flutter pub get

导入插件

在需要使用的 Dart 文件中导入插件：

import 'package:catcher/catcher.dart';

API 用法

基本用法

以下是一个基本的使用示例：

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

void main() {
  // 配置调试模式
  CatcherOptions debugOptions = CatcherOptions(
    DialogReportMode(), // 使用对话框模式显示错误
    [
      ConsoleHandler(), // 输出到控制台
    ],
  );

  // 配置发布模式
  CatcherOptions releaseOptions = CatcherOptions(
    PageReportMode(), // 使用页面模式显示错误
    [
      ConsoleHandler(), // 输出到控制台
      HttpHandler(HttpRequestType.post, Uri.parse("https://your-server.com/report"), printLogs: true), // 发送到服务器
    ],
  );

  // 启动应用并启用 Catcher
  Catcher(
    rootWidget: MyApp(),
    debugConfig: debugOptions,
    releaseConfig: releaseOptions,
  );
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      navigatorKey: Catcher.navigatorKey, // 添加 Catcher 的导航键
      home: Scaffold(
        appBar: AppBar(
          title: Text('Catcher Example'),
        ),
        body: Center(
          child: TextButton(
            child: Text('Generate Error'),
            onPressed: () => Catcher.sendTestException(), // 生成测试错误
          ),
        ),
      ),
    );
  }
}

报告模式

Fluttertpc Catcher 提供了四种报告模式：

SilentReportMode：静默模式，不显示任何提示
NotificationReportMode：通知模式，在通知栏显示错误信息
DialogReportMode：对话框模式，弹出对话框显示错误信息
PageReportMode：页面模式，跳转到新页面显示错误信息

处理方式

Fluttertpc Catcher 提供了多种处理方式：

ConsoleHandler：输出到控制台
EmailManualHandler：手动发送邮件
EmailAutoHandler：自动发送邮件
HttpHandler：发送 HTTP 请求
FileHandler：保存到文件
ToastHandler：显示 Toast 提示
SentryHandler：发送到 Sentry
SlackHandler：发送到 Slack
DiscordHandler：发送到 Discord
SnackbarHandler：显示 Snackbar 提示

自定义配置

可以根据需要自定义配置：

CatcherOptions options = CatcherOptions(
  DialogReportMode(),
  [
    ConsoleHandler(),
    HttpHandler(
      HttpRequestType.post,
      Uri.parse("https://your-server.com/report"),
      printLogs: true,
      headers: {"Authorization": "Bearer token"},
    ),
  ],
  localizationOptions: [
    LocalizationOptions.buildDefaultChineseOptions(),
  ],
  customParameters: {"app_version": "1.0.0"},
  handleSilentError: true,
);

手动报告错误

可以在 try-catch 块中手动报告错误：

try {
  // 可能会出错的代码
} catch (error, stackTrace) {
  Catcher.reportCheckedError(error, stackTrace);
}

鸿蒙系统适配

权限配置

在鸿蒙系统中，需要在 module.json5 中添加以下权限：

{
  "module": {
    "reqPermissions": [
      {
        "name": "ohos.permission.INTERNET",
        "reason": "用于发送错误报告到服务器",
        "usedScene": {
          "ability": ["*"],
          "when": "always"
        }
      }
    ]
  }
}