Crashlytics 疑難排解與常見問題

在「問題」表格中，某些問題會顯示不同的格式 (有時是「變化版本」)

您可能會發現，Firebase 控制台的「問題」表格中列出的問題有兩種不同格式。此外，您可能也會在部分問題中看到「變化版本」功能。原因如下：

2023 年初，我們推出改良版分析引擎，用於將事件分組，並更新設計，以及為新問題提供一些進階功能 (例如變化版本！)。如要瞭解所有詳情，請參閱我們最近發布的網誌文章，或閱讀下方的重點摘要。

Crashlytics 會分析應用程式的所有事件 (例如當機、非致命錯誤和 ANR)，並建立稱為「問題」的事件群組，其中所有事件都有共同的故障點。

為了將事件分組到這些問題中，改良後的分析引擎現在會查看事件的多個面向，包括堆疊追蹤中的框架、例外狀況訊息、錯誤代碼，以及其他平台或錯誤類型特徵。

不過，在這組事件中，導致失敗的堆疊追蹤可能不同。堆疊追蹤不同，可能代表根本原因不同。 為呈現問題中可能存在的差異，我們現在會在問題中建立子類，每個子類都是問題中故障點相同且堆疊追蹤相似的一組事件。有了子類，您就能對問題中最常見的堆疊追蹤進行偵錯，並判斷失敗是否出自其他根本原因。

以下是這些改善項目帶來的體驗：

• 問題列中顯示的中繼資料經過翻新
  現在，您可以更輕鬆地瞭解及分類應用程式中的問題。

• 減少重複問題
  行號變更不會導致新問題。

• 輕鬆對多種根本原因造成的複雜問題進行偵錯
  使用子類對問題中最常見的堆疊追蹤進行偵錯。

• 更具意義的警示和信號
  新問題確實代表新錯誤。

• 更強大的搜尋功能
  每個問題都包含更多可搜尋的中繼資料，例如例外狀況類型和套件名稱。

以下是這些改善項目的推出方式：

• 收到應用程式的新事件時，我們會檢查是否與現有問題相符。

• 如果沒有相符項目，系統會自動對事件套用更聰明的事件分組演算法，並建立新問題，採用重新設計的中繼資料。

這是我們首次對事件分組進行重大更新。如有任何意見或問題，請 提交報告 。

看不到當機前使用者動作記錄

如果沒有看到當機前使用者動作記錄 (iOS+ | Android | Flutter | Unity)，建議您檢查應用程式的 Google Analytics 設定。請確認符合下列規定：

• 您已在 Firebase 專案中啟用 Google Analytics。

• 您已為「Google Analytics」啟用資料共用功能。如要進一步瞭解這項設定，請參閱「管理 Analytics 資料共用設定」

• 您已在應用程式中加入 Google Analytics 的 Firebase SDK：iOS+ | Android | Flutter | Unity。
  除了 Crashlytics SDK 之外，您還必須新增這個 SDK。

• 應用程式使用的所有產品，都採用最新版 Firebase SDK (iOS+ | Android | Flutter | Unity)。

  如果是 Apple 平台和 Android 應用程式，請特別確認您至少使用下列 Google Analytics 專用 Firebase SDK 版本： iOS+ - v6.3.1+ (macOS 和 tvOS 則為 v8.9.0+) | Android - v17.2.3+ (BoM v24.7.1+)。

未看到當機風險驟升警告

如果沒有看到速度快訊，請確認您使用的是

未顯示無當機指標 (或顯示不可靠的指標)

如果未看到無當機指標 (例如無當機使用者和工作階段)，或看到不可靠的指標，請檢查下列事項：

• 請確認您使用的是

• 請確認資料收集設定不會影響無當機指標的品質：

  • 如果停用自動當機回報功能，啟用選擇加入回報功能，則只有在使用者明確選擇加入資料收集時，系統才會將當機資訊傳送至 Crashlytics。因此，無當機指標的準確度會受到影響，因為 Crashlytics 只有這些選擇加入的使用者 (而非所有使用者) 的當機資訊。這表示未發生當機情形的指標可能較不可靠，也較無法反映應用程式的整體穩定性。

  • 如果停用自動資料收集功能，可以使用 sendUnsentReports 將裝置端快取的報表傳送至 Crashlytics。使用這個方法會將當機資料傳送至 Crashlytics，但不會傳送工作階段資料，導致控制台圖表顯示無當機指標的值偏低或為零。

如何計算未發生當機的使用者人數？

請參閱「瞭解未發生當機情形的指標」。

誰可以查看、撰寫及刪除問題附註？

專案成員可以透過附註，針對特定問題發表評論，例如提問、更新狀態等。

專案成員張貼附註時，系統會加上其 Google 帳戶的電子郵件標籤。所有有權查看附註的專案成員，都能看到這個電子郵件地址和附註。

以下說明查看、寫入和刪除記事所需的存取權：

• 具備下列任一角色的專案成員，可以查看及刪除現有附註，以及在問題中撰寫新附註。

  • 專案擁有者或編輯者、Firebase 管理員、品質管理員或 Crashlytics 管理員

• 具備下列任一角色的專案成員可以查看問題中張貼的附註，但無法刪除或撰寫附註。

  • 專案檢視者、Firebase 檢視者、品質檢視者或 Crashlytics 檢視者

什麼是復發問題？

如果問題先前已關閉，但 Crashlytics 收到新報告指出問題再次發生，就表示問題已迴歸。Crashlytics 會自動重新開啟這些復發問題，方便您視應用程式情況採取適當措施。

以下範例說明 Crashlytics 如何將問題歸類為迴歸：

1. Crashlytics 首次收到當機「A」的當機報告。Crashlytics 會為該當機事件 (問題「A」) 開啟對應的問題。
2. 您很快就修正了這個錯誤，關閉問題「A」，然後發布新版應用程式。
3. 您關閉問題後，Crashlytics 收到關於問題「A」的其他回報。
   • 如果回報來自您關閉問題時 Crashlytics 已知的應用程式版本 (也就是該版本已傳送「任何」當機事件的回報)，則 Crashlytics 不會將問題視為復發。問題將維持關閉狀態。
   • 如果回報來自 Crashlytics 在您關閉問題時「不」知道的應用程式版本 (也就是說，該版本「從未」傳送過「任何」當機回報)，則 Crashlytics 會將問題視為迴歸，並重新開啟問題。

當問題復發時，我們會傳送復發偵測快訊，並在問題中加入復發信號，讓您知道 Crashlytics 已重新開啟問題。如果您不希望問題因迴歸演算法而重新開啟，請「忽略」問題，而非關閉問題。

為什麼我會看到舊版應用程式的復發問題？

如果回報來自舊版應用程式，且在您關閉問題時從未傳送任何當機報告，則 Crashlytics 會將問題視為迴歸，並重新開啟問題。

這種情況可能發生在以下情況：您已修正錯誤並發布新版應用程式，但仍有使用者使用未修正錯誤的舊版。如果關閉問題時，其中一個舊版本從未傳送任何當機報告，而使用者開始遇到錯誤，則這些當機報告會觸發迴歸問題。

如果您不希望問題因迴歸演算法而重新開啟，請「忽略」問題，而非關閉問題。

缺少 dSYM/未上傳

如要上傳專案的 dSYM 並取得詳細輸出內容，請檢查下列項目：

1. 請確認專案的建構階段包含 Crashlytics 執行指令碼，讓 Xcode 可以在建構時上傳專案的 dSYM (如需新增指令碼的操作說明，請參閱「初始化 Crashlytics」)。更新專案後，請強制當機，並確認當機事件顯示在 Crashlytics 資訊主頁中。

2. 如果 Firebase 控制台顯示「缺少 dSYM」快訊，請檢查 Xcode，確認是否正確產生版本適用的 dSYM。

3. 如果 Xcode 能正確產生 dSYM，但您仍看到 dSYM 遺失，可能是執行指令碼工具在上傳 dSYM 時卡住。在這種情況下，請嘗試下列各項做法：

   • 確認您使用的是最新版本 Crashlytics。

   • 手動上傳缺少的 dSYM 檔案：

     • 選項 1：使用控制台的「拖放」選項，在「dSYM」分頁中上傳包含遺失 dSYM 檔案的 ZIP 封存檔。
     • 方法 2：使用 upload-symbols 指令碼，為「dSYM」分頁中提供的 UUID 上傳缺少的 dSYM 檔案。

4. 如果仍有缺少的 dSYM，或上傳作業仍未成功，請與 Firebase 支援團隊聯絡，並務必附上記錄。

當機符號化不佳

如果堆疊追蹤似乎未正確符號化，請檢查下列事項：

• 如果應用程式程式庫中的框架缺少應用程式程式碼的參照，請確認 -fomit-frame-pointer 未設為編譯旗標。

• 如果應用程式程式庫有多個 (Missing) 框架，請在 Firebase 控制台的「Crashlytics dSYM 分頁」中，查看是否有選用的 dSYM 遺失 (針對受影響的應用程式版本)。如果是，請按照本頁「缺少 dSYM/未上傳常見問題」中的「缺少 dSYM 警告」疑難排解步驟操作。請注意，上傳這些 dSYM 不會符號化「已發生」的當機事件，但有助於確保「未來」當機事件的符號化。

Crashlytics 支援 macOS 或 tvOS 嗎？

可以，您可以在 macOS 和 tvOS 專案中導入 Crashlytics。請務必加入 Google Analytics 適用的 Firebase SDK 8.9.0 以上版本，這樣當機事件才能存取 Google Analytics 收集的指標 (未發生當機情形的使用者、最新版本、速度快訊和當機前使用者動作記錄)。

我可以在 Firebase 專案中使用 Crashlytics，並在不同 Apple 平台上執行多個應用程式嗎？

現在，您可以在單一 Firebase 專案中回報多個應用程式的當機情形，即使這些應用程式是針對不同 Apple 平台 (例如 iOS、tvOS 和 Mac Catalyst) 建構也沒問題。先前，如果應用程式含有相同的軟體包 ID，您必須將這些應用程式分到個別的 Firebase 專案。

為什麼只回報 Android 11 以上版本的 ANR？

Crashlytics 支援 Android 應用程式的 ANR 報告，適用於搭載 Android 11 以上版本的裝置。我們用來收集 ANR 的基礎 API (getHistoricalProcessExitReasons) 比 SIGQUIT 或以守護程式為基礎的方法更可靠。這個 API 僅適用於 Android 11 以上版本的裝置。

為什麼有些 ANR 沒有 BuildId？

如果部分 ANR 缺少 BuildId，請按照下列步驟排解問題：

• 請確認您使用的是最新版 Crashlytics Android SDK 和 Crashlytics Gradle 外掛程式。

  如果 Android 11 和部分 Android 12 ANR 缺少 BuildId，可能是因為您使用的 SDK 和/或 Gradle 外掛程式版本過舊。如要正確收集這些 ANR 的 BuildId，請使用下列版本：

  • Crashlytics Android SDK 18.3.5 以上版本 (Firebase BoM 31.2.2 以上版本)
  • Crashlytics Gradle 外掛程式 2.9.4 以上版本

• 檢查是否使用非標準位置存放共用資料庫。

  如果應用程式的共用程式庫只缺少BuildId，可能是因為您未使用共用程式庫的標準預設位置。在這種情況下，Crashlytics 可能無法找到相關聯的 BuildId。建議您考慮使用共用程式庫的標準位置。

• 請確認您在建構程序中並未移除 BuildId。

  請注意，下列疑難排解提示適用於 ANR 和原生程式碼發生錯誤。

  • 對二進位檔執行 readelf -n，檢查 BuildId 是否存在。如果沒有 BuildId，請將 -Wl,--build-id 新增至建構系統的旗標。

  • 請確認您並非為了縮減 APK 大小，而意外移除 BuildId。

  • 如果您同時保留已移除和未移除符號的程式庫版本，請務必在程式碼中指向正確的版本。

Crashlytics 資訊主頁和 Google Play 管理中心的 ANR 報告差異

Google Play 和Crashlytics的 ANR 計數可能不一致。這是預期中的情況，因為收集和回報 ANR 資料的機制不同。Crashlytics 會在應用程式下次啟動時回報 ANR，而 Android Vitals 則會在 ANR 發生後傳送 ANR 資料。

此外，Crashlytics 只會顯示搭載 Android 11 以上版本的裝置上發生的 ANR，而 Google Play 則會顯示搭載 Google Play 服務且已接受資料收集同意聲明的裝置上發生的 ANR。

為什麼我會看到標示為 .java 問題的 .kt 檔案當機？

如果應用程式使用的模糊處理工具不會公開副檔名，Crashlytics 預設會產生副檔名為 .java 的問題。

為確保 Crashlytics 能產生正確副檔名的問題，請確認應用程式採用下列設定：

• 使用 Android Gradle 4.2.0 以上版本
• 使用 R8 並開啟模糊處理功能。如要將應用程式更新至 R8，請按照這份文件操作。

請注意，更新至上述設定後，您可能會開始看到新的 .kt 問題，這些問題是現有 .java 問題的重複項目。如要進一步瞭解這種情況，請參閱常見問題。

為什麼我會看到與現有 .java 問題重複的 .kt 問題？

自 2021 年 12 月中旬起，Crashlytics 改善了對使用 Kotlin 的應用程式的支援。

直到最近，可用的模糊處理工具仍未公開副檔名，因此 Crashlytics 預設會產生副檔名為 .java 的每個問題。不過，自 Android Gradle 4.2.0 起，R8 支援檔案副檔名。

本次更新後，Crashlytics 現在可以判斷應用程式中使用的每個類別是否以 Kotlin 編寫，並在問題簽章中加入正確的檔案名稱。如果應用程式採用下列設定，當機問題現在會正確歸因於 .kt 檔案 (如適用)：

• 應用程式使用 Android Gradle 4.2.0 以上版本。
• 應用程式使用 R8，且已開啟模糊處理功能。

由於新的當機問題現在會在問題簽章中包含正確的副檔名，因此您可能會看到新的 .kt 問題，但實際上只是現有 .java 標籤問題的重複項目。在 Firebase 控制台中，我們會嘗試找出新的 .kt 問題是否可能與現有標示為 .java 的問題重複，並通知您。

使用 Dexguard 時未發生當機

如果看到以下例外狀況，可能是您使用的 DexGuard 版本與 Firebase Crashlytics SDK 不相容：

java.lang.IllegalArgumentException: Transport backend 'cct' is not registered

這項例外狀況不會導致應用程式當機，但會阻止應用程式傳送當機報告。修正方法如下：

1. 請確認您使用的是最新版 DexGuard 8.x。最新版本包含 Firebase Crashlytics SDK 所需的規則。

2. 如果不想變更 DexGuard 版本，請嘗試在 DexGuard 設定檔的模糊處理規則中，加入以下程式碼：

   -keepresourcexmlelements manifest/application/service/meta-data@value=cct

如何升級至 Crashlytics Gradle 外掛程式第 3 版？

Crashlytics Gradle 外掛程式的最新版本是主要版本 (v3.0.0)，並停止支援較低版本的 Gradle 和 Android Gradle 外掛程式，讓 SDK 更加現代化。此外，這個版本中的變更解決了 AGP 8.1 以上版本的問題，並改善對原生應用程式和自訂建構作業的支援。

基本規定

Crashlytics Gradle 外掛程式第 3 版有下列最低需求：

• Android Gradle 外掛程式 8.1 以上版本
  請在最新版 Android Studio 中，使用 Android Gradle 外掛程式升級工具升級這個外掛程式。

• Firebase 的 google-services Gradle 外掛程式 4.4.1 以上版本
  如要升級這個外掛程式，請在專案的 Gradle 建構檔案中指定最新版本，如下所示：

plugins {
  id("com.android.application") version "8.1.4" apply false
  id("com.google.gms.google-services") version "4.5.0" apply false
  ...
}

plugins {
  id 'com.android.application' version '8.1.4' apply false
  id 'com.google.gms.google-services' version '4.5.0' apply false
  ...
}

Crashlytics 擴充功能異動

在 Crashlytics Gradle 外掛程式第 3 版中，Crashlytics 擴充功能有下列破壞性變更：

• 已從 defaultConfig Android 區塊中移除擴充功能。請改為設定每個變化版本。

• 移除已淘汰的欄位 mappingFile。現在系統會自動提供合併的對應檔。

• 移除已淘汰的欄位 strippedNativeLibsDir。請改用 unstrippedNativeLibsDir 處理所有原生程式庫。

• 將 unstrippedNativeLibsDir 欄位變更為累計。

  查看多個目錄的範例

  buildTypes {
    release {
      configure<CrashlyticsExtension> {
        nativeSymbolUploadEnabled = true
        unstrippedNativeLibsDir = file("MY/NATIVE/LIBS")
      }
    }
    productFlavors {
      flavorDimensions += "feature"
      create("basic") {
        dimension = "feature"
        // ...
      }
      create("featureX") {
        dimension = "feature"
        configure<CrashlyticsExtension> {
          unstrippedNativeLibsDir = file("MY/FEATURE_X/LIBS")
        }
      }
    }
  }

  uploadCrashlyticsSymbolFilesBasicRelease 工作只會上傳 MY/NATIVE/LIBS 中的符號，但 uploadCrashlyticsSymbolFilesFeatureXRelease 會上傳 MY/NATIVE/LIBS 和 MY/FEATURE_X/LIBS 中的符號。

• 將關閉欄位 symbolGenerator 替換為兩個新的頂層欄位：

  • symbolGeneratorType：字串，可以是 "breakpad" (預設) 或 "csym"。
  • breakpadBinary，本機 dump_syms 二進位檔覆寫的檔案。

擴充功能升級方法示例

        buildTypes {
          release {
            configure<CrashlyticsExtension> {
              // ...
              symbolGenerator(
                closureOf<SymbolGenerator> {
                  symbolGeneratorType = "breakpad"
                  breakpadBinary = file("/PATH/TO/BREAKPAD/DUMP_SYMS")
                }
              )
            }
          }
        }
      

        buildTypes {
          release {
            configure<CrashlyticsExtension> {
              // ...
              symbolGeneratorType = "breakpad"
              breakpadBinary = file("/PATH/TO/BREAKPAD/DUMP_SYMS")
            }
          }
        }
      

        buildTypes {
          release {
            firebaseCrashlytics {
              // ...
              symbolGenerator {
                breakpad {
                  binary file("/PATH/TO/BREAKPAD/DUMP_SYMS")
                }
              }
            }
          }
        }
      

        buildTypes {
          release {
            firebaseCrashlytics {
              // ...
              symbolGeneratorType "breakpad"
              breakpadBinary file("/PATH/TO/BREAKPAD/DUMP_SYMS")
            }
          }
        }
      

Crashlytics 資訊主頁和 logcat 中 NDK 堆疊追蹤的差異

LLVM 和 GNU 工具鍊對應用程式二進位檔的唯讀區隔有不同的預設值和處理方式，可能會在 Firebase 控制台中產生不一致的堆疊追蹤。為降低這類風險，請在建構程序中加入下列連結器旗標：

• 如果您使用的是 LLVM 工具鍊中的 lld 連結器，請新增：

  -Wl,--no-rosegment

• 如果您使用 GNU 工具鍊中的 ld.gold 連結器，請新增：

  -Wl,--rosegment

如果堆疊追蹤仍不一致 (或兩個標記都與工具鍊無關)，請改為在建構程序中加入以下內容：

-fno-omit-frame-pointer

如何使用自己的 Breakpad 符號檔案產生器二進位檔，為 NDK 產生符號檔案？

Crashlytics 外掛程式會隨附自訂 Breakpad 符號檔案產生器。如果您偏好使用自己的二進位檔產生 Breakpad 符號檔案 (例如，如果您偏好從來源建構建構鏈中的所有原生執行檔)，請使用選用的 symbolGeneratorBinary 擴充功能屬性指定執行檔的路徑。

您可以透過下列兩種方式之一，指定 Breakpad 符號檔案產生器二進位檔的路徑：

• 方法 1：在 build.gradle 檔案中，透過 firebaseCrashlytics 擴充功能指定路徑

  在應用程式層級的 build.gradle.kts 檔案中，新增以下內容：

  Gradle 外掛程式 3.0.0 以上版本

  android {
    buildTypes {
      release {
        configure<CrashlyticsExtension> {
          nativeSymbolUploadEnabled = true
          // Add these optional fields to specify the path to the executable
          symbolGeneratorType = "breakpad"
          breakpadBinary = file("/PATH/TO/BREAKPAD/DUMP_SYMS")
        }
      }
    }
  }

  較低的外掛程式版本

  android {
    // ...
    buildTypes {
      // ...
      release {
        // ...
        firebaseCrashlytics {
          // existing; required for either symbol file generator
          nativeSymbolUploadEnabled true
          // Add this optional new block to specify the path to the executable
          symbolGenerator {
            breakpad {
              binary file("/PATH/TO/BREAKPAD/DUMP_SYMS")
            }
          }
        }
     }
  }

• 方法 2：在 Gradle 屬性檔案中，透過屬性行指定路徑

  您可以使用 com.google.firebase.crashlytics.breakpadBinary 屬性指定執行檔的路徑。

  您可以手動更新 Gradle 屬性檔案，也可以透過指令列更新。舉例來說，如要透過指令列指定路徑，請使用類似下方的指令：

  ./gradlew -Pcom.google.firebase.crashlytics.symbolGenerator=breakpad \
    -Pcom.google.firebase.crashlytics.breakpadBinary=/PATH/TO/BREAKPAD/DUMP_SYMS \
    app:assembleRelease app:uploadCrashlyticsSymbolFileRelease
  

Crashlytics 是否支援 armeabi？

Firebase Crashlytics NDK 不支援 ARMv5 (armeabi)。NDK r17 已停止支援這個 ABI。

在 Crashlytics 資訊主頁中看到 Android 應用程式未符號化的堆疊追蹤

如果您使用 Unity IL2CPP，且看到未符號化的堆疊追蹤，請嘗試下列步驟：

1. 請確認您使用的是 Crashlytics Unity SDK 8.6.1 以上版本。

2. 請確認您已設定並執行 Firebase CLI crashlytics:symbols:upload 指令，以產生及上傳符號檔案。

   每次建立發布子版本，或任何要在 Firebase 控制台中查看符號化堆疊追蹤的子版本時，都必須執行這項 CLI 指令。詳情請參閱「取得可讀取的當機報告」。

Crashlytics 是否可與使用 IL2CPP 的應用程式搭配使用？

可以，Crashlytics 可為使用 IL2CPP 的應用程式顯示符號化堆疊追蹤。這項功能適用於在 Android 或 Apple 平台上發布的應用程式。請採取以下行動：

1. 請確認您使用的是 Crashlytics Unity SDK 8.6.0 以上版本。

2. 請依據所用平台完成必要工作：

   • Apple 平台應用程式：不需特別操作。如果是 Apple 平台應用程式，Firebase Unity 編輯器外掛程式會自動設定 Xcode 專案，以便上傳符號。

   • Android 應用程式：請確認您已設定並執行 Firebase CLI crashlytics:symbols:upload 指令，以產生及上傳符號檔。

     每次建立發布子版本，或任何想在 Firebase 控制台中查看符號化堆疊追蹤的子版本時，都必須執行這個 CLI 指令。詳情請參閱「取得可讀取的當機報告」。

為什麼應用程式應將未偵測到的例外狀況回報為嚴重事件？

將未偵測到的例外狀況回報為嚴重事件，可更準確地指出哪些例外狀況可能導致遊戲無法遊玩，即使應用程式繼續執行也一樣。

請注意，如果開始回報嚴重錯誤，未發生當機的使用者 (CFU) 百分比可能會降低，但 CFU 指標會更準確地反映使用者對應用程式的體驗。

哪些例外狀況會回報為嚴重錯誤？

如要讓 Crashlytics 將未偵測到的例外狀況回報為嚴重事件，必須同時符合下列兩項條件：

• 在應用程式初始化期間，ReportUncaughtExceptionsAsFatal 屬性必須設為 true。

• 您的應用程式 (或內含的程式庫) 擲回未捕捉的例外狀況。如果例外狀況已建立，但未擲回，則不視為未偵測到。

啟用將未偵測到的例外狀況回報為嚴重事件的功能後，現在有許多新的嚴重事件。如何妥善處理這些例外狀況？

當您開始收到未偵測到的例外狀況報告 (視為嚴重錯誤) 時，可以採取下列幾種方式處理這些未偵測到的例外狀況：

• 思考如何開始擷取及處理這些未擷取的例外狀況。
• 考慮將例外狀況記錄到 Unity 偵錯控制台和 Crashlytics 的不同選項。

攔截並處理擲回的例外狀況

系統會建立並擲回例外狀況，以反映非預期或例外狀態。如要解決擲回例外狀況反映的問題，必須將程式恢復至已知狀態 (這個程序稱為例外狀況處理)。

除非程式無法返回已知狀態，否則最佳做法是擷取並處理「所有」預期例外狀況。

如要控制哪些例外狀況會由哪些程式碼擷取及處理，請將可能產生例外狀況的程式碼包裝在 try-catch 區塊中。請確保 catch 陳述式中的條件盡可能精確，以便妥善處理特定例外狀況。

在 Unity 或 Crashlytics 中記錄例外狀況

您可以透過多種方式在 Unity 或 Crashlytics 中記錄例外狀況，協助偵錯。

使用 Crashlytics 時，以下是兩種最常見且建議的選項：

• 選項 1：在開發或疑難排解期間，在 Unity 控制台中列印，但不回報給 Crashlytics

  • 使用 Debug.Log(exception)、Debug.LogWarning(exception) 和 Debug.LogError(exception) 列印至 Unity 控制台，這會將例外狀況的內容列印至 Unity 控制台，且不會重新擲回例外狀況。

• 選項 2：在下列情況下，上傳至 Crashlytics，以便在 Crashlytics 資訊主頁中查看合併報表：

  • 如果例外狀況值得記錄，以便偵錯後續可能發生的 Crashlytics 事件，請使用 Crashlytics.Log(exception.ToString())。
  • 如果即使例外狀況已擷取並處理，仍應回報給 Crashlytics，請使用 Crashlytics.LogException(exception) 將其記錄為非致命事件。

不過，如果您想手動向 Unity Cloud Diagnostics 回報嚴重事件，可以使用 Debug.LogException。這個選項會將例外狀況輸出至 Unity 控制台 (如選項 1)，但也會擲回例外狀況 (無論是否已擲回或擷取)。它會在本機以外擲回錯誤。這表示即使使用 try-catch 區塊包圍 Debug.LogException(exception)，仍會導致未攔截的例外狀況。

因此，只有在您想執行下列所有操作時，才呼叫 Debug.LogException：

• 將例外狀況輸出至 Unity 控制台。
• 將例外狀況上傳至 Crashlytics，做為嚴重事件。
• 如要擲回例外狀況，請將其視為「未偵測到」的例外狀況，並回報給 Unity Cloud Diagnostics。

請注意，如果您想將攔截到的例外狀況輸出至 Unity 控制台，並上傳至 Crashlytics 做為非致命事件，請改為執行下列操作：

try
{
    methodThatThrowsMyCustomExceptionType();
}
catch(MyCustomExceptionType exception)
{
    // Print the exception to the Unity console at the error level.
    Debug.LogError(exception);
    // Upload the exception to Crashlytics as a non-fatal event.
    Crashlytics.LogException(exception); // not Debug.LogException
    //
    // Code that handles the exception
    //
}

應用程式也使用 Google Mobile Ads SDK，但未發生當機

如果專案同時使用 Crashlytics 和 Google Mobile Ads SDK，當機回報工具可能會在註冊例外狀況處理常式時造成干擾。如要修正問題，請呼叫 disableSDKCrashReporting，關閉 Mobile Ads SDK 的當機回報功能。

我的 BigQuery 資料集位於何處？

Firebase 會將資料匯出至您設定資料匯出至 BigQuery 時選取的資料集位置。

• 這個位置適用於 Crashlytics 資料集和 Firebase 工作階段資料集 (如果已啟用工作階段資料匯出功能)。

• 這個位置僅適用於匯出至 BigQuery 的資料，不會影響 Firebase 控制台 Crashlytics 資訊主頁或 Android Studio 中儲存的資料位置。

• 資料集建立後，位置就無法變更，不過您可以將資料集複製到其他位置，或手動將資料集移動 (重新建立) 至其他位置。詳情請參閱「變更現有匯出作業的位置」。

升級至BigQuery的新匯出基礎架構後，是否遇到問題？

2024 年 10 月中旬，Crashlytics推出新的基礎架構，可將Crashlytics資料批次匯出至BigQuery。

自 2026 年 3 月 2 日起，所有 Firebase 專案都已自動升級至新的批次匯出基礎架構。

新舊匯出基礎架構的重要差異

• 新的基礎架構支援美國境外的 Crashlytics 資料集位置。

  • 在 2024 年 10 月中旬之前啟用匯出功能，並升級至新的匯出基礎架構：您現在可以視需要變更資料匯出位置。

  • 2024 年 10 月中旬或之後啟用匯出功能：系統會在設定期間提示您選取資料匯出位置。

• 新基礎架構不支援回填啟用匯出「之前」的資料。

  • 舊版基礎架構支援回填啟用匯出日期前最多 30 天的資料。

  • 新基礎架構支援補充過去 30 天內或啟用匯出至 BigQuery 的最近日期 (以最近者為準) 的資料。

• 新基礎架構會使用 Firebase 專案中為 Firebase 應用程式設定的 ID，命名BigQuery批次表格。

  • 舊基礎架構會根據應用程式二進位檔中的軟體包 ID 或套件名稱，將資料寫入批次資料表。

  • 新基礎架構會根據在 Firebase 專案中為已註冊 Firebase 應用程式設定的軟體包 ID 或套件名稱，將資料寫入批次資料表。

如果舊版批次資料表名稱與 Firebase 應用程式 ID 不符

如果舊版批次資料表名稱與已註冊 Firebase 應用程式設有的軟體包 ID 或套件名稱「不符」，請採用下列其中一種做法，避免匯出的批次資料進一步中斷。

瞭解匯出基礎架構如何使用 ID 將資料寫入 BigQuery 資料表

以下說明兩種匯出基礎架構如何將 Crashlytics 資料寫入 BigQuery 批次表格：

• 舊版匯出基礎架構：將資料寫入資料表，資料表名稱取決於應用程式二進位檔中的軟體包 ID 或套件名稱。

• 新版匯出基礎架構：根據在 Firebase 專案中為已註冊 Firebase 應用程式設定的軟體包 ID 或套件名稱，將資料寫入資料表。

不過，有時應用程式二進位檔中的軟體包 ID 或套件名稱，與在 Firebase 專案中為已註冊 Firebase 應用程式設定的軟體包 ID 或套件名稱不符。這通常是因為有人在註冊應用程式時，未輸入實際 ID。

如果升級前未修正這個問題，會發生什麼情況？

如果這兩個位置的 ID 不相符，則表示發生下列情況：

• Crashlytics 資料現在會寫入新的 BigQuery批次資料表，也就是在 Firebase 專案中，根據已註冊 Firebase 應用程式設有的軟體包 ID 或套件名稱，命名的新資料表。

• 任何現有的「舊版」資料表 (名稱以應用程式二進位檔中的 ID 為基礎) 都不會再寫入資料。

ID 不符的情境範例

請注意，BigQuery 批次表格名稱會自動附加 _IOS 或 _ANDROID，表示應用程式的平台。

^{* 如果應用程式二進位檔中的 ID 與 Firebase 應用程式設定的其中一個 ID 相符，新的匯出基礎架構就不會為該 ID 建立新資料表。而是會繼續將該特定應用程式的資料寫入其中。其他應用程式則會寫入新資料表。}

^{** 如果應用程式二進位檔中的其中一個 ID 與 Firebase 應用程式設定的 ID 相符，新的匯出基礎架構就不會建立新資料表。而是會保留該資料表，並開始將所有應用程式的資料寫入其中。}

減少服務中斷影響的選項

• 選項 1：
  使用新匯出基礎架構建立的新資料表。您會將舊版資料表的資料複製到新資料表。

  1. 在 Google Cloud 控制台中，將舊資料表中的所有資料複製到基礎架構升級期間建立的新資料表。

  2. 如果您有任何下游依附元件依賴批次資料表，請將其變更為使用新資料表。

• 選項 2：
  重新設定，再次寫入舊版資料表。您必須覆寫 BigQuery 設定中的部分預設值，才能達成這個目標。

  1. 在 Firebase 控制台中，找出並記下批次表格名稱和 ID 不符的應用程式 Firebase 應用程式 ID (例如 1:1234567890:ios:321abc456def7890)：
     前往 settings 專案設定，然後前往「您的應用程式」資訊卡，查看所有 Firebase 應用程式及其資訊。

  2. 在 Google Cloud 控制台中，變更基礎架構升級作業建立的新「資料移轉設定」，讓資料寫入舊版資料表：

     1. 依序前往 「BigQuery」 > 「Data transfers」 (資料移轉) ，查看「資料移轉設定」。

     2. 選取來源為 Firebase Crashlytics with Multi-Region Support 的設定。

     3. 按一下右上角的「編輯」。

     4. 在「Data source details」(資料來源詳細資料) 部分，找出 gmp_app_id 和 client_namespace 的清單。

        在 BigQuery 中，Firebase 應用程式 ID 稱為 gmp_app_id。根據預設，BigQuery 中的 client_namespace 值是應用程式對應的專屬軟體包 ID / 套件名稱，但您會覆寫這項預設設定。

        BigQuery 會使用 client_namespace 值做為批次表格的名稱，每個連結的 Firebase 應用程式都會寫入這個表格。

     5. 找出要覆寫預設設定的 Firebase 應用程式 gmp_app_id。將 client_namespace 值變更為要讓 Firebase 應用程式寫入的資料表名稱 (通常是應用程式使用舊版匯出基礎架構寫入的舊版資料表名稱)。

     6. 儲存設定變更。

  3. 安排回填作業，補足舊版表格缺少的資料。

  4. 補充作業完成後，請刪除新匯出基礎架構自動建立的新資料表。