此页面由 Cloud Translation API 翻译。

获取 Android NDK 崩溃报告

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

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

如果您正在寻找如何在您的 Unity 项目中开始使用 Crashlytics，请查看Unity 入门指南。

在你开始之前

如果您还没有，请将 Firebase 添加到您的 Android 项目中。如果您没有 Android 应用程序，可以下载示例应用程序。
推荐：要获得无崩溃用户、面包屑日志和速度警报等功能，您需要在 Firebase 项目中启用 Google Analytics。
- 如果您现有的 Firebase 项目没有启用 Google Analytics，您可以从 Firebase 控制台中 >项目设置的集成选项卡启用 Google Analytics。
- 如果您要创建新的 Firebase 项目，请在项目创建工作流程中启用 Google Analytics。

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

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

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

Kotlin+KTX

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

Java

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

第 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.2'
    }
}

在您的模块（应用程序级） 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`扩展添加到您的构建中

在您的模块（应用级）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
          }
      }
  }
}

第四步：设置原生符号自动上传

为了从 NDK 崩溃中生成可读的堆栈跟踪，Crashlytics 需要了解您的本机二进制文件中的符号。 Crashlytics Gradle 插件包括uploadCrashlyticsSymbolFile BUILD_VARIANT任务来自动执行此过程。

为了您可以访问自动符号上传任务，请确保在您的模块（应用程序级）Gradle 文件nativeSymbolUploadEnabled设置为true 。
要在堆栈跟踪中显示方法名称，您必须在每次构建 NDK 库后显式调用uploadCrashlyticsSymbolFile BUILD_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中使用以下代码向您的应用添加一个按钮，按下该按钮会导致崩溃。该按钮标记为“测试崩溃”。

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 仪表板中查看和调查崩溃报告和统计信息。

上传符号的替代选项

上面此页面上的主要工作流程适用于标准 Gradle 构建。但是，某些应用程序使用不同的配置或工具（例如 Gradle 以外的构建过程）。在这些情况下，以下选项可能有助于成功上传符号。

选项：上传库模块和外部依赖项的符号

此选项在以下情况下很有用：

如果您在 Gradle 中使用自定义的 NDK 构建过程
如果您的本机库是在库/功能模块中构建的或由第三方提供
如果自动符号上传任务失败或者您在仪表板中看到未符号化的崩溃

查看此选项的说明

标准的 Crashlytics 符号上传任务假设您使用标准的 NDK 构建工具（例如 CMake）构建您的原生库作为应用模块的 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
- 通过提供列表或FileCollection实例来实现单一构建风格的多个目录
最后，强制测试崩溃以完成 Crashlytics 的设置并在 Firebase 控制台的 Crashlytics 仪表板中查看初始数据。

选项：为非 Gradle 构建或无法访问的未剥离本机库上传符号

此选项在以下情况下很有用：

如果您使用 Gradle 以外的构建过程
如果您以某种方式向您提供未剥离的本机库，但在 Gradle 构建期间无法访问它们

查看此选项的说明

此选项要求您在创建发布版本或您希望在 Firebase 控制台中查看符号化堆栈跟踪的任何版本时运行 Firebase CLI 命令。

确保您已完成本页前面主要工作流中的以下初始任务：
1. 在 Firebase 控制台中启用 Crashlytics。
2. 添加了用于 NDK 的 Crashlytics 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" ... />
构建您的项目。

上传您的符号信息。

构建完成后，生成一个与 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文件中，你的App 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命令以上传您的符号文件。

故障排除

如果您在 Firebase 控制台和 logcat 中看到不同的堆栈跟踪，请参阅故障排除指南。

下一步

通过添加选择加入报告、日志、密钥和非致命错误跟踪来自定义您的崩溃报告设置。
与 Google Play 集成，以便您可以直接在 Crashlytics 仪表板中按 Google Play 跟踪过滤 Android 应用程序的崩溃报告。这使您可以更好地将仪表板集中在特定构建上。

获取 Android NDK 崩溃报告

在你开始之前

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

Kotlin+KTX

Java

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

第 3 步：将firebaseCrashlytics扩展添加到您的构建中

Kotlin+KTX

Java

第四步：设置原生符号自动上传

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

Kotlin+KTX

Java

上传符号的替代选项

选项：上传库模块和外部依赖项的符号

选项：为非 Gradle 构建或无法访问的未剥离本机库上传符号

故障排除

下一步

第 3 步：将`firebaseCrashlytics`扩展添加到您的构建中