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

iOS+ Android Flutter Unity

根據預設，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 目標的建構階段。

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

執行自動上傳 dSYM 的指令碼不存在

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

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. 展開新的「執行指令碼」部分。

   注意： 對於其餘的子步驟，請依照指定方式複製及貼上路徑，Xcode 會將其解析。不過，如果 Xcode 無法解析這些路徑或專屬專案結構，您可以改為手動指定路徑。

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 嗎？

   您可以透過以下兩種方式查看 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。請注意，應用程式二進位檔不會上傳。

執行自動上傳 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 嗎？

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

  • 在 google-services.json 檔案中，應用程式 ID 為 mobilesdk_app_id 值；或

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

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

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