获取 Android NDK 崩溃报告

如果您的 Android 应用包含原生库，您可以通过对应用的 build 配置进行一些细微的更新，允许在 Firebase Crashlytics 中为您的原生代码生成完整堆栈轨迹和详细的崩溃报告。

本指南介绍如何使用 Firebase Crashlytics SDK for NDK 配置崩溃报告。

如果要了解如何在 Unity 项目中开始使用 Crashlytics，请参阅 Unity 版入门指南。

准备工作

  1. 将 Firebase 添加到您的 Android 项目（如果尚未添加）。如果您没有 Android 应用，可以下载一个示例应用。

  2. 建议：要自动获取路径日志以了解导致崩溃事件、非严重事件或 ANR 事件的用户操作，您需要在 Firebase 项目中启用 Google Analytics。

    • 如果您的现有 Firebase 项目未启用 Google Analytics，您可以访问 Firebase 控制台，依次点击 >“项目设置”，然后在集成标签页中启用 Google Analytics。

    • 如果您要创建新的 Firebase 项目，请在项目创建工作流中启用 Google Analytics。

  3. 确保您的应用使用了所需的以下最低版本：

    • Gradle 8.0
    • Android Gradle 插件 8.1.0
    • Google 服务 Gradle 插件 4.4.1

第 1 步：将 Crashlytics SDK for NDK 添加到您的应用

在模块（应用级）Gradle 文件（通常是 <project>/<app-module>/build.gradle.kts 或 <project>/<app-module>/build.gradle）中，添加 Crashlytics NDK 库的依赖项。我们建议使用 Firebase Android BoM 来实现库版本控制。

为了获得最佳的 Crashlytics 使用体验，我们建议您在 Firebase 项目中启用 Google Analytics，并将 Firebase SDK for Google Analytics 添加到您的应用中。 

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

    // 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 插件添加到您的应用

  1. 在您的根级（项目级）Gradle 文件（<project>/build.gradle.kts 或 <project>/build.gradle）中，将 Crashlytics Gradle 插件添加到 plugins 块：

    Kotlin 

    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 

    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
}

  2. 在您的模块（应用级）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 扩展程序添加到您的 build

在模块（应用级）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 任务，可自动完成此过程。

  1. 为了能够访问自动上传符号的任务，请确保在模块（应用级）Gradle 文件中将 nativeSymbolUploadEnabled 设置为 true。

  2. 如需在堆栈轨迹中显示方法名称，您必须在每次构建 NDK 库后明确调用 uploadCrashlyticsSymbolFileBUILD_VARIANT 任务。例如：

    >./gradlew app:assembleBUILD_VARIANT\
           app:uploadCrashlyticsSymbolFileBUILD_VARIANT

  3. Crashlytics SDK for NDK 和 Crashlytics Gradle 插件都依赖于原生共享对象中是否存在 GNU build ID。

    您可以对每个二进制文件运行 readelf -n 来验证此 ID 是否存在。如果此 build ID 不存在，请在构建系统的标志中添加 -Wl,--build-id 来解决此问题。

第 5 步：强制造成一次测试崩溃以完成设置

如需完成 Crashlytics 设置并在 Firebase 控制台的 Crashlytics 信息中心内查看初始数据，您需要强制造成一次测试崩溃。

  1. 向应用添加可用于强制造成测试崩溃的代码。

    您可以在应用的 MainActivity 中使用以下代码，向应用添加一个按下即会导致崩溃的按钮。该按钮标有“测试崩溃”。

    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));

  2. 构建并运行您的应用。

  3. 强制造成测试崩溃以发送应用的第一个崩溃报告：

    1. 在测试设备或模拟器上打开应用。

    2. 在您的应用中，按下您使用上述代码添加的“测试崩溃”按钮。

    3. 应用崩溃后，请将其重启，这样应用便可以将崩溃报告发送到 Firebase。

  4. 前往 Firebase 控制台的 Crashlytics 信息中心，查看您的测试崩溃报告。

    如果您已刷新控制台，但在五分钟后仍未看到测试崩溃报告，请启用调试日志记录，查看您的应用是否正在发送崩溃报告。


大功告成！Crashlytics 现在会监控您的应用是否发生崩溃，您可以在 Crashlytics 信息中心内查看和调查崩溃报告和统计信息。

后续步骤

  • （推荐）收集 GWP-ASan 报告，以帮助调试由原生内存错误引起的崩溃。这些内存相关错误可能与应用内的内存损坏有关，这也是导致应用安全漏洞的主要原因。如需充分利用此调试功能，请确保您的应用已明确启用 GWP-ASan，并使用最新版 Crashlytics SDK for NDK（即 v18.3.6+ 或 Firebase BoM v31.3.0+）。

  • 您可以通过添加自选式报告、日志、键以及跟踪非严重错误来自定义崩溃报告设置。

  • 与 Google Play 集成，以便您可以直接在 Crashlytics 信息中心内按 Google Play 轨道过滤 Android 应用的崩溃报告。这样可让 Crashlytics 信息中心更有侧重地显示特定 build 的崩溃信息。

问题排查

如果您在 Firebase 控制台和 logcat 中看到的堆栈轨迹不同，请参阅问题排查指南。


上传符号的其他方式

本页面上文所述的主工作流适用于标准 Gradle build。不过，有些应用使用其他的配置或工具（例如，除 Gradle 以外的构建流程）。在这些情况下，以下方式可能有助于成功上传符号。

方式：为库模块和外部依赖项上传符号

在以下情况下，此方式非常有用：

  • 如果您在 Gradle 中使用自定义 NDK 构建流程
  • 如果您的原生库是在某个库/功能模块中构建的或是由第三方提供
  • 如果自动上传符号任务失败，或者您在信息中心中看到未经过符号化解析的崩溃报告

方式：为非 Gradle build 或无法访问的未剥离的原生库上传符号

在以下情况下，此方式非常有用：

  • 如果您使用的是 Gradle 以外的构建流程

  • 提供给您的未剥离的原生库在 Gradle 构建期间因为某种原因无法访问