開始使用 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：在 Flutter 專案中新增 Crashlytics

  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 偵錯符號。您必須上傳偵錯符號，才能回報從模糊化的程式碼版本回報當機事件。

      在 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. 在應用程式中新增程式碼，可用來強制擲回測試例外狀況。

    如果您已新增會呼叫 FirebaseCrashlytics.instance.recordError(error, stack, fatal: true) 至頂層 Zone 的錯誤處理常式，可以使用以下程式碼在應用程式中新增按鈕，當按下按鈕時，系統會擲回測試例外狀況：

    TextButton(
    onPressed: () => throw Exception(),
    child: const Text("Throw Test Exception"),
),

  2. 建構並執行應用程式。

  3. 強制擲回測試例外狀況，以便傳送應用程式的第一個報表：

    1. 透過測試裝置或模擬器開啟應用程式。

    2. 在應用程式中，按下使用上述程式碼新增的測試例外狀況按鈕。

  4. 請前往 Firebase 控制台的 Crashlytics 資訊主頁，查看測試當機情況。

    如果您已重新整理主控台，但五分鐘後仍未看到測試當機情況，請啟用偵錯記錄功能，確認應用程式是否會傳送當機報告。


大功告成！Crashlytics 現在會監控應用程式的當機問題，以及 Android 裝置上的一般錯誤和 ANR 情形。請前往 Crashlytics 資訊主頁，查看及調查所有報表和統計資料。

後續步驟