在 Crashlytics 資訊主頁中取得可讀的當機報告


根據預設,Firebase Crashlytics 會自動檢測您的 Flutter 專案,上傳必要的符號檔案,確保當機報告經過去模糊處理,且可供人類閱讀。

很抱歉,在某些情況下,專案可能無法完全設定。本指南將概略說明自動化功能的運作方式,並提供偵錯專案設定的初步步驟。

Apple 平台

檢查上傳 dSYM 檔案的設定

新增 Crashlytics Flutter 外掛程式並執行 flutterfire configure 指令後,系統會嘗試在專案的 Xcode 工作區中新增執行指令碼,以便尋找並上傳必要的 dSYM 符號檔案至 Crashlytics。如果沒有這些檔案,Crashlytics 資訊主頁會顯示「缺少 dSYM」警示,後端會保留例外狀況,直到缺少的檔案上傳為止。

如果遇到這個問題,請先確認您已安裝執行指令碼:

  1. 在專案的 iOS 目錄 (FLUTTER_PROJECT_NAME/ios/Runner.xcworkspace) 中找出並開啟 Xcode 工作區檔案。

  2. 判斷是否已將名為 [firebase_crashlytics] Crashlytics Upload Symbols 的執行指令碼新增至 Runner 目標的建構階段。

    請參閱下方的適用章節,瞭解執行指令碼是否「不存在」執行指令碼是否存在

如果這個執行指令碼不存在,您可以手動新增:

  1. 找出 Apple 應用程式的 Firebase 應用程式 ID。您可以透過以下兩種方式找到這個 ID:

    • Firebase 主控台中,依序前往「」>「專案設定」向下捲動至「您的應用程式」資訊卡,然後按一下 Firebase Apple 應用程式,查看應用程式資訊,包括「應用程式 ID」

    • 在 Flutter 專案的頂層目錄中,找出 firebase_options.dart 檔案。Apple 應用程式的 Firebase 應用程式 ID 標示為 GOOGLE_APP_ID

  2. 依序按一下 >「New Run Script Phase」

    請確認這個新的「執行指令碼」階段是專案的最後一個建構階段。否則 Crashlytics 無法正確處理 dSYM。

  3. 展開新的「執行指令碼」部分。

  4. 在指令碼欄位 (位於「Shell」標籤下方) 中,新增下列執行指令碼。

    這些指令碼會處理 dSYM 檔案,並將檔案上傳至 Crashlytics

    $PODS_ROOT/FirebaseCrashlytics/upload-symbols --build-phase --validate -ai FIREBASE_APP_ID -- $DWARF_DSYM_FOLDER_PATH/App.framework.dSYM
    $PODS_ROOT/FirebaseCrashlytics/upload-symbols --build-phase -ai FIREBASE_APP_ID -- $DWARF_DSYM_FOLDER_PATH/App.framework.dSYM 
    • FIREBASE_APP_ID:您的 Firebase Apple 應用程式 ID (非 Apple 軟體包 ID)
      Firebase Apple 應用程式 ID 範例:1:1234567890:ios:321abc456def7890

    您可以透過以下兩種方式查看 Firebase 應用程式 ID:

    • GoogleService-Info.plist 檔案中,應用程式 ID 為 GOOGLE_APP_ID 值;或

    • Firebase 主控台中,前往專案設定。向下捲動至「您的應用程式」資訊卡,然後按一下所需 Firebase 應用程式,找出其應用程式 ID。

  5. 在「Input Files」專區中,新增下列檔案位置的路徑:

    ${DWARF_DSYM_FOLDER_PATH}/${DWARF_DSYM_FILE_NAME}
    ${DWARF_DSYM_FOLDER_PATH}/${DWARF_DSYM_FILE_NAME}/Contents/Resources/DWARF/${PRODUCT_NAME}
    ${DWARF_DSYM_FOLDER_PATH}/${DWARF_DSYM_FILE_NAME}/Contents/Info.plist
    $(TARGET_BUILD_DIR)/$(UNLOCALIZED_RESOURCES_FOLDER_PATH)/GoogleService-Info.plist
    $(TARGET_BUILD_DIR)/$(EXECUTABLE_PATH)

    Xcode 會在指定位置尋找這些輸入檔案,確保執行指令碼可使用建構檔案。此外,如果啟用使用者指令碼沙箱,Xcode 只會允許執行指令碼存取「Input Files」中指定的檔案。

    • 提供專案 dSYM 檔案的位置,即可讓 Crashlytics 處理 dSYM。
    • 提供應用程式已建構的 GoogleService-Info.plist 檔案位置,即可讓 Crashlytics 將 dSYM 與 Firebase 應用程式建立關聯。
    • 提供應用程式可執行檔的位置,可讓執行指令碼避免重複上傳相同的 dSYM。請注意,應用程式二進位檔不會上傳

如果確實有執行指令碼,請參閱Apple 專用指南,瞭解如何排解 dSYM 問題。如果您選擇透過上述程序上傳 dSYM 檔案,請務必執行下列額外步驟:

  1. 找出 Apple 應用程式的 Firebase 應用程式 ID。您可以透過以下兩種方式找到這個 ID:

    • Firebase 主控台中,依序前往「」>「專案設定」向下捲動至「您的應用程式」資訊卡,然後按一下 Firebase Apple 應用程式,查看應用程式資訊,包括「應用程式 ID」

    • 在 Flutter 專案的頂層目錄中,找出 firebase_options.dart 檔案。Apple 應用程式的 Firebase 應用程式 ID 標示為 GOOGLE_APP_ID

  2. 執行 upload-symbols 指令碼時,請使用 -ai FIREBASE_APPLE_APP_ID 而非 -gsp /path/to/GoogleService-Info.plist

檢查 Flutter 和 Crashlytics 的版本設定 (如果使用 --split-debug-info 標記)

如果您的 Flutter 專案使用 --split-debug-info 標記 (以及選用的 --obfuscate 標記),就必須採取額外步驟,才能顯示應用程式的可讀堆疊追蹤記錄。

請確認專案使用建議的版本設定 (Flutter 3.12.0 以上版本和 Crashlytics Flutter 外掛程式 3.3.4 以上版本),以便專案自動產生並上傳 Flutter 符號 (dSYM 檔案) 至 Crashlytics

Android

檢查依附元件設定

flutterfire configure 指令會嘗試在專案的 Gradle 建構檔案中新增必要的依附元件。如果沒有這些依附元件,如果啟用模糊處理功能,Firebase 主控台中的當機報告可能會遭到模糊處理。

請確認專案層級 build.gradle 和應用程式層級 build.gradle 中包含下列程式碼行:

  • 專案層級的建構檔案 (android/build.gradle) 中,檢查以下行:

    dependencies {
    // ... other dependencies
    
    classpath 'com.google.gms:google-services:4.3.5'
    classpath 'com.google.firebase:firebase-crashlytics-gradle:2.7.1'
    }
  • 應用程式層級的建構檔案 (android/app/build.gradle) 中,檢查以下這行:

    // ... other imports
    
    android {
    // ... your android config
    }
    
    dependencies {
    // ... your dependencies
    }
    
    // This section must appear at the bottom of the file
    apply plugin: 'com.google.gms.google-services'
    apply plugin: 'com.google.firebase.crashlytics'

確認您使用 CLI 上傳 Flutter 符號(如果使用 --split-debug-info 標記)

如果您的 Flutter 專案使用 --split-debug-info 標記 (以及選用的 --obfuscate 標記),就必須採取額外步驟,才能顯示應用程式的可讀堆疊追蹤記錄。

使用 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

    您可以透過以下兩種方式查看 Firebase 應用程式 ID:

    • google-services.json 檔案中,應用程式 ID 為 mobilesdk_app_id 值;或

    • Firebase 主控台中,前往專案設定。向下捲動至「您的應用程式」資訊卡,然後按一下所需 Firebase 應用程式,找出其應用程式 ID。

  • PATH/TO/symbols:建構應用程式時傳遞至 --split-debug-info 標記的相同目錄

如果問題仍未解決,請參閱 Android 專用指南,瞭解如何排解模糊化報表的問題