firebase-crashlytics

Firebase Crashlytics 技能

本技能介绍如何在 Flutter 应用中正确使用 Firebase Crashlytics。

使用场景

使用本技能的场景：

• 在 Flutter 项目中实现崩溃报告。
• 捕获致命错误、非致命异常以及异步／隔离区错误。
• 使用键、日志和用户标识符自定义崩溃报告。
• 配置数据收集的主动选择，或在调试版本中停用报告。
• 为混淆版本上传符号文件。

---

1. 设置和配置

flutter pub add firebase_crashlytics
flutter pub add firebase_analytics  # enables breadcrumb logs for better crash context

运行 flutterfire configure，更新 Firebase 配置，并为 Android 添加所需的 Crashlytics Gradle 插件。

import 'package:firebase_crashlytics/firebase_crashlytics.dart';

混淆代码：

• 对于使用 --split-debug-info 和／或 --obfuscate 构建的应用，请上传符号文件，以便获得可读的堆栈跟踪。
• **iOS：**Flutter 3.12.0+ 和 Crashlytics Flutter 插件 3.3.4+ 会自动处理符号上传。
• **Android：**使用 Firebase CLI（v11.9.0+）上传 Flutter 调试符号：

firebase crashlytics:symbols:upload --app=FIREBASE_APP_ID PATH/TO/symbols

---

2. 错误处理

在 main() 中配置全面的错误捕获，以捕获来自所有来源的错误：

致命 Flutter 错误：

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp();

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

  // Catch async errors not handled by the Flutter framework
  PlatformDispatcher.instance.onError = (error, stack) {
    FirebaseCrashlytics.instance.recordError(error, stack, fatal: true);
    return true;
  };

  runApp(MyApp());
}

**非致命 Flutter 错误：**使用 recordFlutterError，而不是 recordFlutterFatalError。

隔离区错误：

Isolate.current.addErrorListener(RawReceivePort((pair) async {
  final List<dynamic> errorAndStacktrace = pair;
  await FirebaseCrashlytics.instance.recordError(
    errorAndStacktrace.first,
    errorAndStacktrace.last,
    fatal: true,
  );
}).sendPort);

已捕获的异常（非致命）：

await FirebaseCrashlytics.instance.recordError(
  error,
  stackTrace,
  reason: 'a non-fatal error',
  information: ['further diagnostic information about the error', 'version 2.0'],
);

• Crashlytics 每个会话仅存储最近的 8 个非致命异常，更早的异常会被丢弃。

---

3. 自定义崩溃报告

自定义键（最多 64 个键值对，每个最多 1 kB）：

FirebaseCrashlytics.instance.setCustomKey('str_key', 'hello');
FirebaseCrashlytics.instance.setCustomKey('bool_key', true);
FirebaseCrashlytics.instance.setCustomKey('int_key', 1);

自定义日志消息（每个会话上限：64 kB）：

FirebaseCrashlytics.instance.log("User tapped on payment button");

用户标识符：

FirebaseCrashlytics.instance.setUserIdentifier("user-123");
// Clear by setting to blank string
FirebaseCrashlytics.instance.setUserIdentifier("");

• 避免将唯一值（用户 ID、时间戳）直接写入异常消息；请改用自定义键。

---

4. 性能和优化

• Crashlytics 在专用后台线程上处理异常，以尽量降低对性能的影响。
• 致命报告会实时发送，无需重启应用。
• 非致命报告会写入磁盘，并在下次发生致命错误或应用重启时发送。
• 使用面包屑日志（需要 Firebase Analytics）了解导致崩溃的用户操作。

在调试版本中停用 Crashlytics：

if (kReleaseMode) {
  await FirebaseCrashlytics.instance.setCrashlyticsCollectionEnabled(true);
} else {
  await FirebaseCrashlytics.instance.setCrashlyticsCollectionEnabled(false);
}

---

5. 测试和调试

强制触发测试崩溃，以验证设置：

FirebaseCrashlytics.instance.crash();

验证工作流：

1. 以发布模式构建并运行应用。
2. 触发测试崩溃。
3. 重新打开应用，以便上传崩溃报告。
4. 在 5 分钟内检查 Firebase Console Crashlytics 信息中心。
5. 验证崩溃报告中是否显示自定义键、日志和用户标识符。

• 使用代码混淆时，请验证堆栈跟踪是否已正确还原符号。

---

6. 主动选择报告

默认情况下，Crashlytics 会自动收集所有用户的崩溃报告。

如需让用户控制数据收集：

• 停用自动报告，并仅在用户主动选择加入时通过 setCrashlyticsCollectionEnabled(true) 启用。
• 覆盖值会在之后的所有应用启动中持续生效。
• 如需让用户退出，请传入 false——该设置会从下次应用启动时生效。
• 停用时，崩溃信息会存储在本地；之后若重新启用，本地存储的崩溃信息会发送到 Crashlytics。

---

参考资料

• Firebase Crashlytics Flutter 文档
• 自定义崩溃报告