Watch demos on how to build & run AI-powered apps with Firebase at Demo Day '24. Watch now.

本頁面由 Cloud Translation API 翻譯而成。

取得 Android NDK 當機報告

如果您的 Android 應用程式含有原生程式庫，您可以透過對應用程式建構設定進行幾項小更新，為 Firebase Crashlytics 啟用原生程式碼的完整堆疊追蹤和詳細當機報告。

本指南說明如何使用 NDK 的 Firebase Crashlytics SDK 設定當機回報功能。

如果您想瞭解如何在 Unity 專案中開始使用 Crashlytics，請參閱 Unity 入門指南。

事前準備

如果您尚未將 Firebase 新增至 Android 專案，請先新增。如果您沒有 Android 應用程式，可以下載範例應用程式。
建議：如要自動取得導覽標記記錄，瞭解導致當機、非致命或 ANR 事件的使用者動作，您必須在 Firebase 專案中啟用 Google Analytics。
- 如果現有的 Firebase 專案未啟用 Google Analytics，您可以前往 Firebase 控制台的 >「專案設定」整合分頁標籤，啟用 Google Analytics。
- 如果您要建立新的 Firebase 專案，請在專案建立工作流程中啟用 Google Analytics。
請確認應用程式具備以下最低必要版本：
- Gradle 8.0
- Android Gradle 外掛程式 8.1.0 版
- Google 服務 Gradle 外掛程式 4.4.1 版

步驟 1：在應用程式中加入 NDK 適用的 Crashlytics SDK

在模組 (應用程式層級) Gradle 檔案 (通常是 <project>/<app-module>/build.gradle.kts 或 <project>/<app-module>/build.gradle) 中，加入 Android 專用的 Crashlytics NDK 程式庫依附元件。建議您使用 Firebase Android BoM 來控制程式庫版本。

為提供最佳的 Crashlytics 體驗，建議您在 Firebase 專案中啟用 Google Analytics，並將 Google Analytics 專用 Firebase SDK 新增至應用程式。

dependencies {
    // Import the BoM for the Firebase platform
    implementation(platform("com.google.firebase:firebase-bom:33.6.0"))

    // Add the dependencies for the Crashlytics NDK and Analytics libraries
    // When using the BoM, you don't specify versions in Firebase library dependencies
    implementation("com.google.firebase:firebase-crashlytics-ndk")
    implementation("com.google.firebase:firebase-analytics")
}

只要使用 Firebase Android BoM，應用程式就會一律使用相容的 Firebase Android 程式庫版本。

(替代做法) 不使用 BoM 新增 Firebase 程式庫依附元件

如果您選擇不使用 Firebase BoM，則必須在依附元件行中指定每個 Firebase 程式庫版本。

請注意，如果您在應用程式中使用多個 Firebase 程式庫，強烈建議您使用 BoM 來管理程式庫版本，確保所有版本皆相容。

dependencies {
    // Add the dependencies for the Crashlytics NDK and Analytics libraries
    // When NOT using the BoM, you must specify versions in Firebase library dependencies
    implementation("com.google.firebase:firebase-crashlytics-ndk:19.2.1")
    implementation("com.google.firebase:firebase-analytics:22.1.2")
}

想找 Kotlin 專屬的程式庫模組嗎？自 2023 年 10 月 (Firebase BoM 32.5.0)起，Kotlin 和 Java 開發人員皆可依賴主要程式庫模組 (詳情請參閱這項計畫的常見問題)。

步驟 2：將 Crashlytics Gradle 外掛程式新增至應用程式

在根層級 (專案層級) Gradle 檔案 (<project>/build.gradle.kts 或 <project>/build.gradle) 中，將 Crashlytics Gradle 外掛程式新增至 plugins 區塊：

Kotlin

您是否仍在使用 buildscript 語法？瞭解如何使用這個語法新增 Firebase 外掛程式。

plugins {
    // Make sure that you have the AGP plugin 8.1+ dependency
    id("com.android.application") version "8.1.4" apply false
    // ...

    // Make sure that you have the Google services Gradle plugin 4.4.1+ dependency
    id("com.google.gms.google-services") version "4.4.2" apply false

    // Add the dependency for the Crashlytics Gradle plugin
    id("com.google.firebase.crashlytics") version "3.0.2" apply false
}

Groovy

您是否仍在使用 buildscript 語法？瞭解如何使用這個語法新增 Firebase 外掛程式。

plugins {
    // Make sure that you have the AGP plugin 8.1+ dependency
    id 'com.android.application' version '8.1.4' apply false
    // ...

    // Make sure that you have the Google services Gradle plugin 4.4.1+ dependency
    id 'com.google.gms.google-services' version '4.4.2' apply false

    // Add the dependency for the Crashlytics Gradle plugin
    id 'com.google.firebase.crashlytics' version '3.0.2' apply false
}

在模組 (應用程式層級) Gradle 檔案 (通常是 <project>/<app-module>/build.gradle.kts 或 <project>/<app-module>/build.gradle) 中，新增 Crashlytics Gradle 外掛程式：

Kotlin

plugins {
  id("com.android.application")
  // ...

  // Make sure that you have the Google services Gradle plugin
  id("com.google.gms.google-services")

  // Add the Crashlytics Gradle plugin
  id("com.google.firebase.crashlytics")
}

Groovy

plugins {
  id 'com.android.application'
  // ...

  // Make sure that you have the Google services Gradle plugin
  id 'com.google.gms.google-services'

  // Add the Crashlytics Gradle plugin
  id 'com.google.firebase.crashlytics'
}

步驟 3：在建構中加入 Crashlytics 擴充功能

在模組 (應用程式層級) Gradle 檔案 (通常是 <project>/<app-module>/build.gradle.kts 或 <project>/<app-module>/build.gradle) 中，設定 Crashlytics 擴充功能。

Kotlin

import com.google.firebase.crashlytics.buildtools.gradle.CrashlyticsExtension

// ...

android {
  // ...
  buildTypes {
      getByName("release") {
          // Add this extension
          configure<CrashlyticsExtension> {
              // Enable processing and uploading of native symbols to Firebase servers.
              // By default, this is disabled to improve build speeds.
              // This flag must be enabled to see properly-symbolicated native
              // stack traces in the Crashlytics dashboard.
              nativeSymbolUploadEnabled = true
          }
      }
  }
}

Groovy

// ...

android {
  // ...
  buildTypes {
      release {
          // Add this extension
          firebaseCrashlytics {
              // Enable processing and uploading of native symbols to Firebase servers.
              // By default, this is disabled to improve build speeds.
              // This flag must be enabled to see properly-symbolicated native
              // stack traces in the Crashlytics dashboard.
              nativeSymbolUploadEnabled true
          }
      }
  }
}

步驟 4：設定原生符號的自動上傳功能

為了從 NDK 當機情形產生可讀取的堆疊追蹤，Crashlytics 需要瞭解原生二進位檔中的符號。Crashlytics Gradle 外掛程式包含 uploadCrashlyticsSymbolFileBUILD_VARIANT 工作，可自動執行這項程序。

為便您存取自動上傳符號的工作，請確認模組 (應用程式層級) Gradle 檔案中的 nativeSymbolUploadEnabled 已設為 true。
如要讓方法名稱顯示在堆疊追蹤中，您必須在每次建構 NDK 程式庫後，明確叫用 uploadCrashlyticsSymbolFileBUILD_VARIANT 工作。例如：
```
>./gradlew app:assembleBUILD_VARIANT\
           app:uploadCrashlyticsSymbolFileBUILD_VARIANT
```
NDK 適用的 Crashlytics SDK 和 Crashlytics Gradle 外掛程式都需要原生共用物件中存在 GNU 建構 ID。

您可以對每個二進位檔執行 readelf -n，驗證是否有這個 ID。如果沒有版本 ID，請將 -Wl,--build-id 新增至建構系統的標記，以便修正問題。

步驟 5：強制測試當機以完成設定

您需要強制測試當機，才能完成設定 Crashlytics，並在 Firebase 控制台的 Crashlytics 資訊主頁中看見初始資料。

在應用程式中新增可用於強制測試當機的程式碼。

您可以在應用程式的 MainActivity 中使用以下程式碼，為應用程式新增按鈕，當按下按鈕時會導致應用程式當機。按鈕標示為「Test Crash」。

Kotlin+KTX

val crashButton = Button(this)
crashButton.text = "Test Crash"
crashButton.setOnClickListener {
   throw RuntimeException("Test Crash") // Force a crash
}

addContentView(crashButton, ViewGroup.LayoutParams(
       ViewGroup.LayoutParams.MATCH_PARENT,
       ViewGroup.LayoutParams.WRAP_CONTENT))

Java

Button crashButton = new Button(this);
crashButton.setText("Test Crash");
crashButton.setOnClickListener(new View.OnClickListener() {
   public void onClick(View view) {
       throw new RuntimeException("Test Crash"); // Force a crash
   }
});

addContentView(crashButton, new ViewGroup.LayoutParams(
       ViewGroup.LayoutParams.MATCH_PARENT,
       ViewGroup.LayoutParams.WRAP_CONTENT));

建構並執行應用程式。
強制執行測試當機，以便傳送應用程式的首份當機報告：
1. 透過測試裝置或模擬器開啟應用程式。
2. 在應用程式中，按下您使用上述程式碼新增的「Test Crash」按鈕。
3. 應用程式當機後，請重新啟動應用程式，以便將當機報告傳送至 Firebase。
前往 Firebase 主控台的 Crashlytics 資訊主頁，查看測試異常終止情形。

如果您已重新整理控制台，但五分鐘後仍未看到測試異常終止，請啟用偵錯記錄，看看應用程式是否會傳送異常終止報告。

就是這樣！Crashlytics 現在會監控應用程式的當機情形，您可以在 Crashlytics 資訊主頁中查看及調查當機報告和統計資料。

後續步驟

(建議) 收集 GWP-ASan 報告，協助偵錯因原生記憶體錯誤而導致的當機情形。這些記憶體相關錯誤可能與應用程式中的記憶體毀損問題有關，而這類問題是造成應用程式安全漏洞的主要原因。如要充分利用這項偵錯功能，請確認應用程式已明確啟用 GWP-ASan，並使用最新的 Crashlytics SDK for NDK (18.3.6 以上版本或 Firebase BoM 31.3.0 以上版本)。
自訂當機報告設定，新增選擇加入的回報、記錄、鍵和非致命錯誤追蹤。
整合 Google Play，即可直接在 Crashlytics 資訊主頁中，依據 Google Play 追蹤記錄篩選 Android 應用程式的當機報告。這樣一來，您就能更專注於特定版本的資訊主頁。

疑難排解

如果您在 Firebase 主控台和 Logcat 中看到不同的堆疊追蹤，請參閱疑難排解指南。

上傳符號的其他方法

本頁上方的主要工作流程適用於標準 Gradle 建構作業。不過，有些應用程式會使用不同的設定或工具 (例如 Gradle 以外的建構程序)。在這種情況下，您可以使用下列選項來順利上傳符號。

選項：上傳程式庫模組和外部依附元件的符號

在下列情況下，這個選項會很實用：

如果您在 Gradle 中使用自訂的 NDK 建構程序
如果原生資料庫是在程式庫/功能模組中建構，或由第三方提供
如果自動符號上傳工作失敗，或您在資訊主頁中看到未符號化的當機情形

查看這個選項的操作說明

標準 Crashlytics 符號上傳工作會假設您使用 CMake 等標準 NDK 建構工具，將原生程式庫建構為應用程式模組的 Gradle 建構作業的一部分。

不過，如果您在 Gradle 中使用自訂的 NDK 建構程序，或是原生程式庫是在程式庫/功能模組中建構，或是由第三方提供，您可能需要明確指定未經精簡的程式庫路徑。如要達成這項目標，您可以在 Gradle 建構檔案的 Crashlytics 擴充功能中新增 unstrippedNativeLibsDir 屬性。

請確認您已完成本頁稍早提到的主要工作流程中的下列初始工作：

為了讓自動符號上傳工作能夠找到符號資訊，請在模組 (應用程式層級) Gradle 檔案 (通常為 <project>/<app-module>/build.gradle.kts 或 <project>/<app-module>/build.gradle) 中加入以下內容：

Kotlin

import com.google.firebase.crashlytics.buildtools.gradle.CrashlyticsExtension

// ...

android {
    // ...
    buildTypes {
        release {
            configure<CrashlyticsExtension> {
                nativeSymbolUploadEnabled = true
                unstrippedNativeLibsDir = file("PATH/TO/UNSTRIPPED/DIRECTORY")
            }
        }
    }
}

Groovy

// ...

android {
    // ...
    buildTypes {
        release {
            firebaseCrashlytics {
                nativeSymbolUploadEnabled true
                unstrippedNativeLibsDir file("PATH/TO/UNSTRIPPED/DIRECTORY")
            }
        }
    }
}

Crashlytics 外掛程式會遞迴搜尋指定目錄，找出使用 .so 副檔名的原生程式庫。Crashlytics 接著會從所有這類程式庫中擷取偵錯符號，並上傳至 Firebase 伺服器。

以下是您可以在 unstrippedNativeLibsDir 屬性中指定的內容：

org.gradle.api.Project#files(Object...) 允許的任何引數，包括：java.lang.String、java.io.File 或 org.gradle.api.file.FileCollection
為單一建構變化版本提供多個目錄，方法是提供清單或 FileCollection 例項
(自 Crashlytics Gradle 外掛程式 3.0.0 版起) 在個別產品和建構變種版本中累積多個目錄。

查看包含多個目錄的範例

  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 中的符號。

最後，請強制測試當機，完成 Crashlytics 設定，並在 Firebase 控制台的 Crashlytics 資訊主頁中查看初始資料。

選項：上傳非 Gradle 版本或無法存取的未經精簡的原生資料庫的符號

在下列情況下，這個選項會很實用：

如果您使用 Gradle 以外的建構程序
如果您以某種方式取得未經精簡的原生資料庫，但在 Gradle 建構期間無法存取這些資料庫

查看這個選項的操作說明

使用這個選項時，您必須在建立發布子版本或任何要在 Firebase 控制台中查看符號化堆疊追蹤記錄的版本時，執行 Firebase CLI 指令。

請確認您已完成本頁稍早提到的主要工作流程中的下列初始工作：
1. 在 Firebase 控制台中啟用 Crashlytics。
2. 新增 Crashlytics NDK SDK 和 Crashlytics Gradle 外掛程式。
請注意，使用這個選項時，您不需要新增 firebaseCrashlytics 擴充功能或設定自動上傳符號功能，因為您可以改用 Firebase CLI (下方後續步驟) 產生及上傳符號檔案。
設定符號上傳環境和專案：
1. 按照操作說明安裝 Firebase CLI。
  
  如果您已安裝 CLI，請務必更新至最新版本。
2. (僅適用於使用 Android API 級別 30 以上的應用程式) 更新應用程式的 AndroidManifest.xml 範本，以停用指標標記：
  1. 依序勾選「Android Player Settings」>「Publishing Settings」>「Build」>「Custom Main Manifest」方塊。
  2. 開啟位於 Assets/Plugins/Android/AndroidManifest.xml 的資訊清單範本。
  3. 在應用程式標記中加入下列屬性： <application android:allowNativeHeapPointerTagging="false" ... />
建構專案。

上傳符號資訊。

建置完成後，請執行下列 Firebase CLI 指令，產生 Crashlytics 相容的符號檔案，並將其上傳至 Firebase 伺服器：

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：CLI 產生的符號檔案路徑
- 匯出至 Android Studio 專案：PATH/TO/SYMBOLS 可以是任何目錄。Firebase CLI 會遞迴搜尋指定目錄，找出使用 .so 副檔名的原生程式庫。
- 直接在 Unity 中建構 APK：PATH/TO/SYMBOLS 是建構完成後在專案根目錄中產生的壓縮符號檔案路徑 (例如：myproject/myapp-1.0-v100.symbols.zip)。

查看使用 Firebase CLI 指令產生及上傳符號檔案的進階選項

標記	說明
`--generator=csym`	使用舊版 cSYM 符號檔案產生器，而非預設的 Breakpad 產生器不建議使用。建議您使用預設的 Breakpad 符號檔案產生器。
`--generator=breakpad`	使用 Breakpad 符號檔案產生器請注意，符號檔案產生的預設值為 Breakpad。只有在您在建構設定中新增 `symbolGenerator { csym() }` 且想要覆寫該值，改用 Breakpad 時，才使用這個標記。
`--dry-run`	產生符號檔案，但不會上傳如果您想檢查傳送的檔案內容，這個旗標就非常實用。
`--debug`	提供其他偵錯資訊

最後，請強制測試當機，完成 Crashlytics 設定，並在 Firebase 控制台的 Crashlytics 資訊主頁中查看初始資料。

建立應用程式以強制發生當機後，請務必執行 Firebase CLI crashlytics:symbols:upload 指令，上傳符號檔案。