如果您的 Android 应用包含原生库,您可以通过对应用的 build 配置进行一些细微的更新,允许在 Firebase Crashlytics 中为您的原生代码生成完整堆栈轨迹和详细的崩溃报告。
本指南介绍如何使用 Firebase Crashlytics SDK for NDK 配置崩溃报告。
如果要了解如何在 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 步:将 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.7.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.3.0") implementation("com.google.firebase:firebase-analytics:22.1.2") }
第 2 步:将 Crashlytics Gradle 插件添加到您的应用
在您的根级(项目级)Gradle 文件(
<project>/build.gradle.kts
或<project>/build.gradle
)中,将 Crashlytics Gradle 插件添加到plugins
块: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 }
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 插件: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") }
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 扩展程序。
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 } } } }
// ... 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:assemble
BUILD_VARIANT \ app:uploadCrashlyticsSymbolFileBUILD_VARIANT Crashlytics SDK for NDK 和 Crashlytics Gradle 插件都依赖于原生共享对象中是否存在 GNU build ID。
您可以对每个二进制文件运行
来验证此 ID 是否存在。如果此 build ID 不存在,请在构建系统的标志中添加readelf -n
来解决此问题。-Wl,--build-id
第 5 步:强制造成一次测试崩溃以完成设置
如需完成 Crashlytics 设置并在 Firebase 控制台的 Crashlytics 信息中心内查看初始数据,您需要强制造成一次测试崩溃。
向应用添加可用于强制造成测试崩溃的代码。
您可以在应用的
MainActivity
中使用以下代码,向应用添加一个按下即会导致崩溃的按钮。该按钮标有“测试崩溃”。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))
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));
构建并运行您的应用。
强制造成测试崩溃以发送应用的第一个崩溃报告:
在测试设备或模拟器上打开应用。
在您的应用中,按下您使用上述代码添加的“测试崩溃”按钮。
应用崩溃后,请将其重启,这样应用便可以将崩溃报告发送到 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 构建流程,或者您的原生库是在某个库/功能模块中构建的或是由第三方提供,那么您可能需要明确指定未剥离的库的路径。为此,您可以在 Gradle build 文件的 Crashlytics 扩展程序内添加 unstrippedNativeLibsDir
属性。
确保您已在本页面上文所述的主工作流中完成以下初始任务:
为了让自动上传符号任务能够找到您的符号信息,请将以下内容添加到您的模块(应用级)Gradle 文件(通常为
<project>/<app-module>/build.gradle.kts
或<project>/<app-module>/build.gradle
)中:import com.google.firebase.crashlytics.buildtools.gradle.CrashlyticsExtension // ... android { // ... buildTypes { release { configure<CrashlyticsExtension> { nativeSymbolUploadEnabled = true unstrippedNativeLibsDir = file("
PATH/TO/UNSTRIPPED/DIRECTORY ") } } } }// ... 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 Gradle 插件 v3.0.0 开始)累积单个产品和 build 变种中的多个目录。
查看包含多个目录的示例
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 build 或无法访问的未剥离的原生库上传符号
在以下情况下,此方式非常有用:
如果您使用的是 Gradle 以外的构建流程
提供给您的未剥离的原生库在 Gradle 构建期间因为某种原因无法访问
查看关于此方式的说明
此方式有如下要求:当您创建发布 build 或希望在 Firebase 控制台中看到其经过符号化解析的堆栈轨迹的任何 build 时,需要运行一条 Firebase CLI 命令。
确保您已在本页面上文所述的主工作流中完成以下初始任务:
请注意,通过此方式,您无需添加
firebaseCrashlytics
扩展或设置自动符号上传,因为您将改用 Firebase CLI(后续步骤见下文)生成并上传符号文件。设置您的环境和项目以进行符号上传:
按照说明安装 Firebase CLI。
如果您已安装 CLI,请务必将其更新为最新版本。
(仅适用于使用 Android API 级别 30 及更高级别的应用)更新应用的
AndroidManifest.xml
模板以停用指针标记:依次勾选 Android Player Settings(Android 播放器设置)> Publishing Settings(发布设置)> Build(构建)> Custom Main Manifest(自定义主清单)对应的复选框。
打开位于
Assets/Plugins/Android/AndroidManifest.xml
的清单模板。将以下属性添加到应用标记:
<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 配置中添加了
,并且想要替换它以改用 Breakpad 时,才需要使用此标志。symbolGenerator { csym() }
--dry-run
生成符号文件,但不将其上传
如果您要检查所发送文件的内容,此标志将非常有用。
--debug
提供额外的调试信息 最后,强制造成一次测试崩溃以完成 Crashlytics 设置,并在 Firebase 控制台的 Crashlytics 信息中心内查看初始数据。
在构建应用(作为强制造成崩溃的一部分)后,请务必运行 Firebase CLI
crashlytics:symbols:upload
命令以上传您的符号文件。