获取 Android NDK 崩溃报告

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

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

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

准备工作

将 Firebase 添加到您的 Android 项目（如果尚未添加）。如果您没有 Android 应用，可以下载一个示例应用。
建议做法：如需使用“未遇到崩溃问题的用户”“面包屑导航日志”和“疾速崩溃提醒”等功能，您需要在 Firebase 项目中启用 Google Analytics（分析）。
- 如果您的现有 Firebase 项目未启用 Google Analytics（分析），您可以访问 Firebase 控制台，依次点击 >“项目设置”，然后在集成标签页中启用 Google Analytics（分析）。
- 如果您要创建新的 Firebase 项目，请在项目创建过程中启用 Google Analytics（分析）。

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

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

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

Kotlin+KTX

dependencies {
    // Import the BoM for the Firebase platform
    implementation platform('com.google.firebase:firebase-bom:32.0.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-ktx'
}

借助 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:18.3.7'
    implementation 'com.google.firebase:firebase-analytics-ktx:21.2.2'
}

Java

dependencies {
    // Import the BoM for the Firebase platform
    implementation platform('com.google.firebase:firebase-bom:32.0.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:18.3.7'
    implementation 'com.google.firebase:firebase-analytics:21.2.2'
}

第 2 步：将 Crashlytics Gradle 插件添加到您的应用

在您的根级（项目级）Gradle 文件 (<project>/build.gradle) 中，将 Crashlytics Gradle 插件添加为 buildscript 依赖项：

buildscript {
    repositories {
      // Make sure that you have the following two repositories
      google()  // Google's Maven repository
      mavenCentral()  // Maven Central repository
    }

    dependencies {
        ...
        classpath 'com.android.tools.build:gradle:7.2.0'

        // Make sure that you have the Google services Gradle plugin dependency
        classpath 'com.google.gms:google-services:4.3.15'

        // Add the dependency for the Crashlytics Gradle plugin
        classpath 'com.google.firebase:firebase-crashlytics-gradle:2.9.5'
    }
}

在您的模块（应用级）Gradle 文件（通常是 <project>/<app-module>/build.gradle）中，添加 Crashlytics Gradle 插件：

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 步：将 `firebaseCrashlytics` 扩展程序添加到您的 build

在模块（应用级）Gradle 文件（通常为 app/build.gradle）中，添加 firebaseCrashlytics 扩展程序。

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

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

第 4 步：设置自动上传原生符号任务

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

为了能够访问自动上传符号的任务，请确保在模块（应用级）Gradle 文件中将 nativeSymbolUploadEnabled 设置为 true。
如需在堆栈轨迹中显示方法名称，您必须在每次构建 NDK 库后明确调用 uploadCrashlyticsSymbolFileBUILD_VARIANT 任务。例如：
```
>./gradlew app:assembleBUILD_VARIANT\
           app:uploadCrashlyticsSymbolFileBUILD_VARIANT
```
Crashlytics SDK for NDK 和 Crashlytics Gradle 插件都依赖于原生共享对象中是否存在 GNU build ID。

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

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

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

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

您可以在应用的 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));

构建并运行您的应用。
强制造成测试崩溃以发送应用的第一个崩溃报告：
1. 在测试设备或模拟器上打开应用。
2. 在您的应用中，按下您使用上述代码添加的“测试崩溃”按钮。
3. 应用崩溃后，请将其重启，这样应用便可以将崩溃报告发送到 Firebase。
前往 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 构建流程
如果您的原生库是在某个库/功能模块中构建的或是由第三方提供
如果自动上传符号任务失败，或者您在信息中心中看到未经过符号化解析的崩溃报告

查看关于此方式的说明

标准 Crashlytics 上传符号任务假设您使用 CMake 之类的标准 NDK 构建工具，在应用模块的 Gradle 构建过程中构建原生库。

但是，如果您在 Gradle 中使用自定义 NDK 构建流程，或者您的原生库是在某个库/功能模块中构建的或是由第三方提供，那么您可能需要明确指定未剥离的库的路径。为此，您可以在 build.gradle 文件的 firebaseCrashlytics 扩展程序内添加 unstrippedNativeLibsDir 属性。

确保您已在本页面上文所述的主工作流中完成以下初始任务：
为了让自动上传符号任务能够找到您的符号信息，请将以下内容添加到您的模块（应用级）build.gradle 文件中：
```
// ...

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
- 单个 build 变种的多个目录（通过提供列表或 FileCollection 实例）
最后，强制造成一次测试崩溃以完成 Crashlytics 设置，并在 Firebase 控制台的 Crashlytics 信息中心内查看初始数据。

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

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

如果您使用的是 Gradle 以外的构建流程
提供给您的未剥离的原生库在 Gradle 构建期间因为某种原因无法访问

查看关于此方式的说明

此方式有如下要求：当您创建发布 build 或希望在 Firebase 控制台中看到其经过符号化解析的堆栈轨迹的任何 build 时，需要运行一条 Firebase CLI 命令。

确保您已在本页面上文所述的主工作流中完成以下初始任务：
1. 已在 Firebase 控制台中启用 Crashlytics。
2. 已添加 Crashlytics SDK for NDK 和 Crashlytics Gradle 插件。
请注意，通过此方式，您无需添加 firebaseCrashlytics 扩展或设置自动符号上传，因为您将改用 Firebase CLI（后续步骤见下文）生成并上传符号文件。
设置您的环境和项目以进行符号上传：
1. 按照说明安装 Firebase CLI。
  
  如果您已安装 CLI，请务必将其更新为最新版本。
2. （仅适用于使用 Android API 级别 30 及更高级别的应用）更新应用的 AndroidManifest.xml 模板以停用指针标记：
  1. 依次勾选 Android Player Settings（Android 播放器设置）> Publishing Settings（发布设置）> Build（构建）> Custom Main Manifest（自定义主清单）对应的复选框。
  2. 打开位于 Assets/Plugins/Android/AndroidManifest.xml 的清单模板。
  3. 将以下特性添加到应用标记：<application android:allowNativeHeapPointerTagging="false" ... />
构建您的项目。

上传您的符号信息。

构建完成后，生成与 Crashlytics 兼容的符号文件，然后通过运行以下 Firebase CLI 命令将其上传到 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。只有当您已经在 build 配置中添加了 `symbolGenerator { csym() }`，并且想要替换它以改用 Breakpad 时，才需要使用此标志。
`--dry-run`	生成符号文件，但不将其上传如果您要检查所发送文件的内容，此标志将非常有用。
`--debug`	提供额外的调试信息

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

在构建应用（作为强制造成崩溃的一部分）后，请务必运行 Firebase CLI crashlytics:symbols:upload 命令以上传您的符号文件。

获取 Android NDK 崩溃报告

准备工作

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

Kotlin+KTX

Java

第 2 步：将 Crashlytics Gradle 插件添加到您的应用

第 3 步：将 firebaseCrashlytics 扩展程序添加到您的 build

Kotlin+KTX

Java

第 4 步：设置自动上传原生符号任务

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

Kotlin+KTX

Java

后续步骤

问题排查

上传符号的其他方式

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

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

第 3 步：将 `firebaseCrashlytics` 扩展程序添加到您的 build