Firebase Crashlytics 使用入门


此快速入门介绍了如何使用 Crashlytics Flutter 插件在应用中设置 Firebase Crashlytics,以便您可以在 Firebase 控制台中获得全面的崩溃报告。

设置 Crashlytics 需要用到命令行工具和 IDE。为了完成设置,您需要强制抛出一个测试异常,以便向 Firebase 发送您的第一个崩溃报告。

准备工作

  1. 在 Flutter 项目中配置并初始化 Firebase(如果尚未执行此操作)。

  2. 建议:要自动获取路径日志以了解导致崩溃事件、非严重事件或 ANR 事件的用户操作,您需要在 Firebase 项目中启用 Google Analytics

    • 如果您的现有 Firebase 项目未启用 Google Analytics,您可以访问 Firebase 控制台,依次点击 >“项目设置”,然后在集成标签页中启用 Google Analytics

    • 如果您要创建新的 Firebase 项目,请在项目创建工作流中启用 Google Analytics

    请注意,面包屑导航日志适用于 Crashlytics 支持的所有 Android 和 Apple 平台(watchOS 除外)。

第 1 步:将 Crashlytics 添加到您的 Flutter 项目

  1. 从 Flutter 项目的根目录运行以下命令,以安装适用于 Crashlytics 的 Flutter 插件。

    如需利用路径日志,还可以将适用于 Google Analytics 的 Flutter 插件添加到您的应用中。确保您的 Firebase 项目中启用了 Google Analytics

    flutter pub add firebase_crashlytics && flutter pub add firebase_analytics
    
  2. 从 Flutter 项目的根目录运行以下命令:

    flutterfire configure
    

    运行此命令可确保您的 Flutter 应用的 Firebase 配置是最新的,对于 Android,还会向您的应用添加所需的 Crashlytics Gradle 插件。

  3. 完成后,重新构建您的 Flutter 项目:

    flutter run
    
  4. (可选)如果您的 Flutter 项目使用 --split-debug-info 标记(以及可选的 --obfuscate 标记),您需要执行其他步骤才能显示应用的可读堆栈轨迹。

    • Apple 平台:确保您的项目使用的是推荐的版本配置(Flutter 3.12.0 及更高版本和 Crashlytics Flutter 插件 3.3.4 及更高版本),以便您的项目可以自动生成 Flutter 符号(dSYM 文件)并将其上传到 Crashlytics

    • Android:使用 Firebase CLI (v.11.9.0+) 上传 Flutter 调试符号。在报告经过混淆处理的代码 build 的崩溃之前,您需要先上传调试符号。

      从 Flutter 项目的根目录运行以下命令:

      firebase crashlytics:symbols:upload --app=FIREBASE_APP_ID PATH/TO/symbols
      • FIREBASE_APP_ID:您的 Firebase Android 应用 ID(而不是您的软件包名称)
        示例 Firebase Android 应用 ID:1:567383003300:android:17104a2ced0c9b9b

      • PATH/TO/symbols:您在构建应用时传递给 --split-debug-info 标志的同一目录

第 2 步:配置崩溃处理程序

您可以使用 FirebaseCrashlytics.instance.recordFlutterFatalError 替换 FlutterError.onError,自动捕获 Flutter 框架中抛出的所有错误:

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await Firebase.initializeApp();

  // Pass all uncaught "fatal" errors from the framework to Crashlytics
  FlutterError.onError = FirebaseCrashlytics.instance.recordFlutterFatalError;

  runApp(MyApp());
}

如需捕获未由 Flutter 框架处理的异步错误,请使用 PlatformDispatcher.instance.onError

Future<void> main() async {
    WidgetsFlutterBinding.ensureInitialized();
    await Firebase.initializeApp();
    FlutterError.onError = (errorDetails) {
      FirebaseCrashlytics.instance.recordFlutterFatalError(errorDetails);
    };
    // Pass all uncaught asynchronous errors that aren't handled by the Flutter framework to Crashlytics
    PlatformDispatcher.instance.onError = (error, stack) {
      FirebaseCrashlytics.instance.recordError(error, stack, fatal: true);
      return true;
    };
    runApp(MyApp());

}

如需查看有关如何处理其他类型错误的示例,请参阅自定义崩溃报告

第 3 步:强制造成一次测试崩溃以完成设置

如需完成 Crashlytics 设置并在 Firebase 控制台的 Crashlytics 信息中心内查看初始数据,您需要强制抛出一个测试异常。

  1. 向您的应用添加可用于强制抛出测试异常的代码。

    如果您添加了一个对顶级 Zone 调用 FirebaseCrashlytics.instance.recordError(error, stack, fatal: true) 的错误处理程序,可以使用以下代码向应用添加一个按下即会抛出测试异常的按钮:

    TextButton(
        onPressed: () => throw Exception(),
        child: const Text("Throw Test Exception"),
    ),
    
  2. 构建并运行您的应用。

  3. 强制抛出测试异常,以便发送您的应用的第一个报告:

    1. 在测试设备或模拟器上打开应用。

    2. 在您的应用中,按下您使用上述代码添加的测试异常按钮。

  4. 前往 Firebase 控制台的 Crashlytics 信息中心,查看您的测试崩溃报告。

    如果您已刷新控制台,但在五分钟后仍未看到测试崩溃报告,请启用调试日志记录,查看您的应用是否正在发送崩溃报告。


大功告成!Crashlytics 现在会监控您的应用是否发生崩溃,以及 Android 中的非严重错误和 ANR。您可以访问 Crashlytics 信息中心以查看和调查所有报告和统计信息。

后续步骤

  • 您可以添加自选式报告、日志、键以及跟踪其他非严重错误来自定义崩溃报告设置

  • Google Play 集成,以便您可以直接在 Crashlytics 信息中心内按 Google Play 轨道过滤 Android 应用的崩溃报告。这样可让 Crashlytics 信息中心更有侧重地显示特定 build 的崩溃信息。

  • 在 Android Studio 的“App Quality Insights”(应用质量分析)窗口中查看堆栈轨迹、崩溃统计信息以及代码(从 Electric Eel 2022.1.1 开始提供)。