Catch up on everything we announced at this year's Firebase Summit. Learn more

获取 Android NDK 崩溃报告

如果您的 Android 应用包含原生库,您可以通过对应用的构建配置进行一些小规模更新,从 Firebase Crashlytics 为您的原生代码启用完整堆栈轨迹和详细的崩溃报告。

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

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

准备工作

  1. 将 Firebase 添加到您的 Android 项目(如果尚未添加)。如果您没有任何 Android 应用,可以下载一个示例应用

  2. 建议做法:若要使用“未遇到崩溃问题的用户”、“面包屑导航日志”和“疾速崩溃提醒”等功能,您需要在 Firebase 项目中启用 Google Analytics(分析)。

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

    • 如果您要创建新的 Firebase 项目,请在项目创建工作流内启用 Google Analytics(分析)。

第 1 步:在 Firebase 控制台中启用 Crashlytics

  1. 转到 Firebase 控制台中的 Crashlytics 信息中心

  2. 确保从页面顶部的 Crashlytics 旁边的下拉列表中选择您的应用。

  3. 点击启用 Crashlytics

第 2 步:将适用于 NDK 的 Firebase Crashlytics SDK 添加到您的应用

使用 Firebase Android BoM模块(应用级)Gradle 文件(通常为 app/build.gradle)中声明 Crashlytics NDK Android 库的依赖项。

为了获得最佳的 Crashlytics 使用体验,我们建议您在 Firebase 项目中启用 Google Analytics(分析),并将适用于 Google Analytics(分析)的 Firebase SDK 添加到您的应用中。

Java

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

    // Declare 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 {
    // Declare 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:18.2.4'
    implementation 'com.google.firebase:firebase-analytics:20.0.0'
}

Kotlin+KTX

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

    // Declare 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-ktx'
}

借助 Firebase Android BoM,可确保您的应用使用的始终是 Firebase Android 库的兼容版本。

(替代方法) 在不使用 BoM 的情况下声明 Firebase 库依赖项

如果您选择不使用 Firebase BoM,则必须在每个 Firebase 库的依赖项行中指定相应的库版本。

请注意,如果您在应用中使用多个 Firebase 库,我们强烈建议您使用 BoM 来管理库版本,从而确保所有版本都兼容。

dependencies {
    // Declare 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:18.2.4'
    implementation 'com.google.firebase:firebase-analytics-ktx:20.0.0'
}

第 3 步:将 Firebase Crashlytics 插件添加到您的应用

  1. 项目级 build.gradle 文件中,将 Crashlytics Gradle 插件添加为 buildscript 依赖项。

    buildscript {
        repositories {
            // Check that you have Google's Maven repository (if not, add it).
            google()
        }
    
        dependencies {
            // ...
    
            // Check that you have the Google services Gradle plugin v4.3.2 or later
            // (if not, add it).
            classpath 'com.google.gms:google-services:4.3.10'
    
            // Add the Crashlytics Gradle plugin
            classpath 'com.google.firebase:firebase-crashlytics-gradle:2.8.0'
        }
    }
    
    allprojects {
        repositories {
            // Check that you have Google's Maven repository (if not, add it).
            google()
        }
    }
  2. 应用级 build.gradle 文件中,应用 Crashlytics Gradle 插件:

    apply plugin: 'com.android.application'
    apply plugin: 'com.google.gms.google-services' // Google services Gradle plugin
    
    // Apply the Crashlytics Gradle plugin
    apply plugin: 'com.google.firebase.crashlytics'
    

第 4 步:将 firebaseCrashlytics 扩展程序添加到您的 build

模块(应用级)Gradle 文件(通常为 app/build.gradle)中,添加 firebaseCrashlytics 扩展程序。

Java

// ...

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
          }
      }
  }
}

Kotlin+KTX

// ...

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
          }
      }
  }
}

targetSdkLevel 30 及更高版本中的必需项:您必须通过在 AndroidManifest.xml 中添加以下代码来停用应用中的指针标记功能:

<application android:allowNativeHeapPointerTagging="false">
...
</application>

如需了解详情,请参阅针对已标记指针的开发者支持

第 5 步:设置原生符号的自动上传操作

为了生成可读的 NDK 崩溃堆栈轨迹,Crashlytics 需要了解您的原生二进制文件中的符号。Crashlytics Gradle 插件包含 uploadCrashlyticsSymbolFileBUILD_VARIANT 任务,可自动完成此过程。

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

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

    >./gradlew app:assembleBUILD_VARIANT\
               app:uploadCrashlyticsSymbolFileBUILD_VARIANT
    
  3. 适用于 NDK 的 Crashlytics SDK 和 Crashlytics Gradle 插件都依赖于原生共享对象中是否存在 GNU build ID。

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

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

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

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

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

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

    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))
    
  2. 构建并运行您的应用。

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

    1. 通过测试设备或模拟器打开应用。

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

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

  4. 请转到 Firebase 控制台的 Crashlytics 信息中心 以查看您的测试崩溃报告。

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


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



上传符号的其他方式

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

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

在以下情况下,此方式非常有用:

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

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

在以下情况下,此方式非常有用:

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

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



问题排查

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

后续步骤