在 Crashlytics 信息中心内获取易于理解的崩溃报告

iOS+ Android Flutter Unity

默认情况下，Firebase Crashlytics 会自动对您的 Flutter 项目进行插桩测试，以上传必要的符号文件，确保崩溃报告经过去混淆处理，方便用户阅读。

遗憾的是，存在一些可能导致项目未得到完全配置的情况。本指南概述了自动化执行的操作，并提供了调试项目设置的前期步骤。

Apple 平台

检查用于上传 dSYM 文件的配置

添加 Crashlytics Flutter 插件并运行 flutterfire configure 命令时，系统将尝试向项目的 Xcode 工作区添加运行脚本 (run script)，该脚本会查找必要的 dSYM 符号文件并将其上传到 Crashlytics。如果没有这些文件，Crashlytics 信息中心会显示“dSYM 缺失”提醒。在上传缺失文件之前，后端将保留异常。

如果您遇到此问题，请先确保已安装了运行脚本：

1. 在项目的 iOS 目录 (FLUTTER_PROJECT_NAME/ios/Runner.xcworkspace) 中找到并打开 Xcode 工作区文件。

2. 确定名为 [firebase_crashlytics] Crashlytics Upload Symbols 的运行脚本是否已添加到 Runner 目标的构建阶段。

   请参阅下文相应部分，了解运行脚本不存在以及运行脚本存在的情况分别对应的处理方式。

用于自动上传 dSYM 的运行脚本不存在

如果此运行脚本不存在，您可以按如下步骤手动进行添加：

1. 找到 Apple 应用的 Firebase 应用 ID。您可以在以下两个位置找到此 ID：

   • 在 Firebase 控制台中，前往 > 项目设置。向下滚动到“您的应用”卡片，然后点击您的 Firebase Apple 应用以查看该应用的信息，包括其应用 ID。

   • 在 Flutter 项目的顶层目录中，找到您的 firebase_options.dart 文件。您的 Apple 应用的 Firebase 应用 ID 带有 GOOGLE_APP_ID 标签。

2. 依次点击 > New Run Script Phase（新建运行脚本阶段）。

   确保这个新“运行脚本”阶段是项目的最后一个构建阶段；否则 Crashlytics 将无法正确处理 dSYM。

3. 展开新的“Run Script”（运行脚本）部分。

   注意：对于其余的子步骤，请完全按照本文中所述复制并粘贴路径，Xcode 将解析这些路径。不过，如果 Xcode 在解析这些路径或独特的项目结构时遇到问题，您可以手动指定路径。

4. 在脚本字段（位于“Shell”标签下）中，添加以下运行脚本。

   这些脚本会处理您的 dSYM 文件，并将文件上传到 Crashlytics。

   $PODS_ROOT/FirebaseCrashlytics/upload-symbols --build-phase --validate -ai FIREBASE_APP_ID -- $DWARF_DSYM_FOLDER_PATH/App.framework.dSYM

   $PODS_ROOT/FirebaseCrashlytics/upload-symbols --build-phase -ai FIREBASE_APP_ID -- $DWARF_DSYM_FOLDER_PATH/App.framework.dSYM 

   • FIREBASE_APP_ID：您的 Firebase Apple 应用 ID（而不是您的 Apple 软件包 ID）
     示例 Firebase Apple 应用 ID：1:1234567890:ios:321abc456def7890

   需要查找您的 Firebase 应用 ID？

   您可以通过以下两种方法查找 Firebase 应用 ID：

   • 在 GoogleService-Info.plist 文件中，您的应用 ID 是 GOOGLE_APP_ID 值；或者

   • 在 Firebase 控制台中，前往项目设置。向下滚动到“您的应用”卡片，然后点击所需的 Firebase 应用以查找其应用 ID。

5. 在“Input Files”（输入文件）部分，添加以下文件的位置路径：

   ${DWARF_DSYM_FOLDER_PATH}/${DWARF_DSYM_FILE_NAME}

   ${DWARF_DSYM_FOLDER_PATH}/${DWARF_DSYM_FILE_NAME}/Contents/Resources/DWARF/${PRODUCT_NAME}

   ${DWARF_DSYM_FOLDER_PATH}/${DWARF_DSYM_FILE_NAME}/Contents/Info.plist

   $(TARGET_BUILD_DIR)/$(UNLOCALIZED_RESOURCES_FOLDER_PATH)/GoogleService-Info.plist

   $(TARGET_BUILD_DIR)/$(EXECUTABLE_PATH)

   了解为什么需要提供这些文件的位置

   Xcode 会在指定位置查找这些输入文件，确保 build 文件可供运行脚本使用。此外，如果启用了“User Script Sandboxing”（用户脚本沙盒保护功能），Xcode 将仅允许运行脚本访问“Input Files”（输入文件）中指定的文件。

   • 提供项目的 dSYM 文件位置，可方便 Crashlytics 处理 dSYM。
   • 提供应用已构建 GoogleService-Info.plist 文件的位置，可方便 Crashlytics 将 dSYM 与您的 Firebase 应用关联。
   • 提供应用的可执行文件位置，可让运行脚本避免重复上传同一 dSYM。请注意，应用的二进制文件不会上传。

用于自动上传 dSYM 的运行脚本存在

如果运行脚本存在，请参阅 dSYM 问题排查指南（Apple）。如果您选择通过上述流程上传 dSYM 文件，还需要执行以下额外步骤：

1. 找到 Apple 应用的 Firebase 应用 ID。您可以在以下两个位置找到此 ID：

   • 在 Firebase 控制台中，前往 > 项目设置。向下滚动到“您的应用”卡片，然后点击您的 Firebase Apple 应用以查看该应用的信息，包括其应用 ID。

   • 在 Flutter 项目的顶层目录中，找到您的 firebase_options.dart 文件。您的 Apple 应用的 Firebase 应用 ID 带有 GOOGLE_APP_ID 标签。

2. 运行 upload-symbols 脚本时，请使用 -ai FIREBASE_APPLE_APP_ID 而不是 -gsp /path/to/GoogleService-Info.plist。

检查 Flutter 和 Crashlytics 的版本配置（如果使用 --split-debug-info 标志）

如果您的 Flutter 项目使用 --split-debug-info 标志（或者视需要使用 --obfuscate 标志），则需要执行额外的步骤来显示应用的可读堆栈轨迹。

确保您的项目使用的是推荐的版本配置（Flutter 3.12.0 及更高版本和 Crashlytics Flutter 插件 3.3.4 及更高版本），以便您的项目可以自动生成 Flutter 符号（dSYM 文件）并将其上传到 Crashlytics。

Android

检查依赖项配置

flutterfire configure 命令尝试向项目的 Gradle build 文件添加必要的依赖项。如果没有这些依赖项且启用了混淆功能，Firebase 控制台中的崩溃报告可能会经过混淆处理。

确保项目级 build.gradle 和应用级 build.gradle 中存在以下几行内容：

• 在项目级 build 文件 (android/build.gradle) 中，检查是否有以下一行内容：

  dependencies {
  // ... other dependencies
  
  classpath 'com.google.gms:google-services:4.3.5'
  classpath 'com.google.firebase:firebase-crashlytics-gradle:2.7.1'
  }

• 在应用级 build 文件 (android/app/build.gradle) 中，检查是否有以下一行内容：

  // ... other imports
  
  android {
  // ... your android config
  }
  
  dependencies {
  // ... your dependencies
  }
  
  // This section must appear at the bottom of the file
  apply plugin: 'com.google.gms.google-services'
  apply plugin: 'com.google.firebase.crashlytics'

检查您是否在使用 CLI 上传 Flutter 符号（如果使用 --split-debug-info 标志）

如果您的 Flutter 项目使用 --split-debug-info 标志（或者视需要使用 --obfuscate 标志），则需要执行额外的步骤来显示应用的可读堆栈轨迹。

使用 Firebase CLI (v.11.9.0+) 上传 Flutter 调试符号。在报告经过混淆处理的代码 build 的崩溃之前，您需要先上传调试符号。

从 Flutter 项目的根目录运行以下命令：

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：您在构建应用时传递给 --split-debug-info 标志的同一目录

如果问题仍然存在，请参阅混淆报告问题排查指南 (Android)。