在 Crashlytics 資訊主頁中取得淺顯易懂的當機報告 (Flutter)

選取平台：

iOS+ Android Flutter Unity

根據預設，Firebase Crashlytics 會自動檢測 Flutter 專案，並上傳必要的符號檔案，確保當機報告經過去模糊化處理，且淺顯易懂。

很抱歉，有時專案可能無法完成設定。本指南會說明自動化作業的用途，並提供專案設定的偵錯初步步驟。

Apple 平台

檢查上傳 dSYM 檔案的設定

新增 Crashlytics Flutter 外掛程式並執行 flutterfire configure 指令後，系統會嘗試將執行指令新增至專案的 Xcode 工作區，找出並將必要的 dSYM 符號檔案上傳至 Crashlytics。如果沒有這些檔案，Crashlytics資訊主頁就會顯示「缺少 dSYM」警示，後端也會暫緩處理例外狀況，直到您上傳缺少的檔案為止。

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

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

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

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

沒有用於自動上傳 dSYM 的指令碼

如果沒有這個執行指令碼，可以手動新增：

1. 找出 Apple 應用程式的 Firebase 應用程式 ID。您可以在下列兩個位置找到這個 ID：

   • 在 Firebase 控制台中，依序前往 settings >「專案設定」。前往「您的應用程式」資訊卡，然後按一下 Firebase Apple 應用程式，即可查看應用程式資訊，包括「應用程式 ID」。

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

2. 依序點選 add >「New Run Script Phase」。

   請確認這個新的「Run Script」階段是專案的最後一個建構階段。否則 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 嗎？

   以下提供兩種方法，可找出 Firebase 應用程式 ID：

   • 在 GoogleService-Info.plist 檔案中，應用程式 ID 是 GOOGLE_APP_ID 值；或

   • 在 Firebase 控制台中，前往「Project settings」(專案設定)。前往「您的應用程式」資訊卡，然後按一下目標 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 只會允許執行指令碼存取「輸入檔案」中指定的檔案。

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

執行指令碼，自動上傳現有的 dSYM

如果執行指令碼存在，請參閱 Apple 專屬指南，瞭解如何排解 dSYM 問題。如果選擇透過上述程序上傳 dSYM 檔案，則必須採取下列額外步驟：

1. 找出 Apple 應用程式的 Firebase 應用程式 ID。您可以在下列兩個位置找到這個 ID：

   • 在 Firebase 控制台中，依序前往 settings >「專案設定」。前往「您的應用程式」資訊卡，然後按一下 Firebase Apple 應用程式，即可查看應用程式資訊，包括「應用程式 ID」。

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

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 控制台中，前往「Project settings」(專案設定)。前往「您的應用程式」資訊卡，然後按一下目標 Firebase 應用程式，找出其應用程式 ID。

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

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