---
metadata:
  - name: generator
    content: Diplodoc Platform v5.70.0
alternate:
  - https://appmetrica.yandex.by/docs/en/data-collection/about-crashes-and-errors.md
  - https://appmetrica.yandex.by/docs/ru/data-collection/about-crashes-and-errors.md
  - https://appmetrica.yandex.by/docs/zh/data-collection/about-crashes-and-errors.md
  - href: https://appmetrica.yandex.by/docs/zh/data-collection/about-crashes-and-errors.md
    type: text/markdown
    title: Markdown version
  - href: https://appmetrica.yandex.by/docs/zh/llms.txt?revision=r22089357
    rel: describedby
---
> **Documentation Index:** Fetch the complete configuration index at https://appmetrica.yandex.by/docs/zh/llms.txt?revision=r22089357

# 崩溃和错误

本部分帮助您了解哪些故障阻碍了用户使用应用，并将修复信息传递给开发团队。

## 崩溃与错误的区别 {#crash-vs-error}

**崩溃** — 应用的异常终止。例如，用户打开商品卡片，应用意外关闭。

**错误** — 应用可以继续运行的问题。例如，商品卡片未加载，但用户可以返回目录。如果开发人员配置了相关消息的发送，此类信息将出现在 AppMetrica 中。

这些只是示例：跟踪哪些错误由团队根据应用的任务决定。

## 如何开始收集 {#how-to-start}

请开发人员检查崩溃收集，并与他们一起配置对产品重要的错误发送。在您这边，请描述需要跟踪的情况：用户试图做什么、出了什么问题以及这如何阻碍完成操作。

例如，对于在线商店，您可以单独跟踪商品卡片未加载或无法将商品添加到购物车的情况。与开发人员商定错误的名称和描述，以便之后在报告中识别它们。

## 如何获得清晰的故障描述 {#readable-crash}

有时应用会发送一条故障消息，其中看不到问题具体发生在哪里。为了让 AppMetrica 能够解码此类消息，开发人员会上传与应用一起准备的专用文件。它们有助于找到错误位置并了解其原因。

Android 和 iOS 需要不同的文件，但任务相同：使故障信息可用于调查。分析师或产品经理无需自行准备这些文件。

{% note warning %}

如果报告中出现故障描述未解码的警告，请将其连同应用版本一起传递给开发人员。请他们检查所需文件是否已上传，并在准备新版本时配置其上传。

{% endnote %}

开发人员连接故障收集并上传用于解码的文件。这有助于获得清晰的问题描述并找到其原因。

{% cut "面向开发人员：收集崩溃和错误、调试文件及验证" %}

下载开发人员说明（TXT）：{% file src="../../_assets/instructions/crashes-developer-zh.txt" name="crashes-developer-zh.txt" type="text/plain; charset=utf-8" %}

#### 如何配置收集 {#setup-collection}

AppMetrica SDK 中提供了崩溃收集。请检查您平台的集成和传输设置。对于自定义错误消息，开发人员会添加对相应 SDK 方法的调用。

例如，如果应用处理了失败的操作并向用户显示了消息，开发人员可以传输错误以供后续分析。发送哪些情况由应用团队决定。

Android、iOS、Flutter、React Native 和 Unity 方法的链接见[错误发送说明](#send-errors-platforms)。

#### 用于解码 Android 和 iOS 故障的文件 {#symbol-files}

请使用与发生故障的应用构建版本匹配的文件。各平台的要求和上传方法如下。

##### Android：mapping 文件和调试符号 {#android-mapping}

AppMetrica 允许您收集有关原生和 Java 崩溃的信息。您可以在[崩溃和错误](https://appmetrica.yandex.by/docs/zh/mobile-reports/crashes-and-errors.md)报告中分析它们。另请参阅[在不同平台上发送错误](#send-errors-platforms)部分。

为了减小应用大小，代码会在发布构建期间被[优化](https://developer.android.com/studio/build/shrink-code)。

如果在构建 Android 应用时压缩并混淆了代码，则崩溃信息会以混淆形式传输。为了从此类崩溃日志中提取数据进行分析，AppMetrica 会在服务器端执行反混淆。

为此，请将 mapping 文件或 SO 文件的调试符号上传到 AppMetrica：在应用构建时自动上传，或通过网页界面手动上传。

要发送文件，请连接 [AppMetrica Gradle Plugin](https://appmetrica.yandex.by/docs/zh/sdk/android/analytics/android-gradle-plugin.md)。

{% note info %}

如果您使用 [ProGuard](https://www.guardsquare.com/en/products/proguard/manual) 或 [R8](https://r8.googlesource.com/r8/)，请上传 mapping 文件。如果您不压缩或混淆代码，则无需连接插件。

{% endnote %}

###### 了解更多 {#learn-more-android}

- [崩溃和错误报告](https://appmetrica.yandex.by/docs/zh/mobile-reports/crashes-and-errors.md)
- [Android 文档](https://developer.android.com/topic/performance/vitals/crash)

##### iOS：dSYM 文件 {#ios-dsym}

iOS 上的崩溃信息以[符号化](https://developer.apple.com/library/archive/technotes/tn2151/_index.html)形式发送。从此类崩溃日志中很难提取数据进行分析。为了使崩溃日志可分析，请将 dSYM 文件上传到 AppMetrica。

要将 dSYM 文件上传到 AppMetrica SDK，内置了命令行工具 [helper](#helper)。对于使用 [fastlane](https://docs.fastlane.tools) 的构建，支持[上传插件](https://github.com/yandexmobile/metrica-plugin-fastlane)。借助它们，您可以配置在应用构建时自动上传 dSYM 文件。

请仅为您想要发布的应用发送 dSYM 文件。

###### 构建时自动上传 {#auto-upload}

使用 [fastlane](https://docs.fastlane.tools) 构建应用：

1. 安装 `appmetrica` fastlane 插件：

   ```
   fastlane add_plugin appmetrica
   ```

   有关添加插件的更多信息，请参阅 [fastlane 文档](https://docs.fastlane.tools/plugins/using-plugins/#add-a-plugin-to-your-project)。

1. 在 `fastlane/Fastfile` 文件中添加以下内容：

   ```
   lane :release do
   # Your actions before.
   gym(
   workspace: "MyApp.xcworkspace",
   configuration: "Release",
   scheme: "MyApp",
   export_method: "app-store"        # Pass the correct export_method.
   )
   upload_symbols_to_appmetrica(post_api_key: "Post API key")
   # Your actions after.
   end
   ```

   Post API key 可以在 AppMetrica 的**设置**部分获取。它用于标识您的应用。

   {% note warning %}

   构建应用时使用带导出的 [gym](https://docs.fastlane.tools/actions/gym/#gym) action。如果您使用 Xcode 构建应用，应用在上传到 App Store Connect 后会被重新编译。那么构建时生成的 dSYM 文件将无法使用。

   {% endnote %}

1. 在 Xcode 中使用 `helper` 工具添加 dSYM 文件上传步骤。`helper` 工具从 3.8.0 版本开始包含在 AppMetrica SDK 中。它位于 SDK 归档中。[helper 工具参考](#helper)。

   1. 在 Xcode 中打开项目。
   1. 在项目导航器中选择项目文件。
   1. 在 **Targets** 块中选择您的应用。
   1. 打开 **Build Phases** 选项卡。
   1. 点击 **+** 按钮 → **New Run Script Phase**。
   1. 在 **Type a script** 文本字段中添加：

      ```
      if [ -d "${PODS_ROOT}/AppMetricaCrashes" ]; then
      HELPER_PATH=`find "${PODS_ROOT}/AppMetricaCrashes" -name "helper"`
      if [ -x  "${HELPER_PATH}" ]; then
      "${HELPER_PATH}" auto --post-api-key="Post API key"&
      else
      echo "AppMetricaСrash helper was not found"
      fi
      fi
      ```

   {% note info %}

   `auto` 模式使用 `CONFIGURATION` 环境变量。如果构建使用 `Debug` 配置，则不会上传 dSYM 文件。

   {% endnote %}

###### 上传缺失的 dSYM 文件 {#upload-missing-dsym}

如果在应用构建时未上传 dSYM 文件，崩溃报告中将显示未符号化崩溃的警告。

![警告](../../_images/dsym-warning-zh.png){style="border: solid 1px #cccccc; max-width: 800px;"}

要符号化它们，请上传缺失的 dSYM 文件。缺失文件列表可以在 AppMetrica 中您应用的[设置 → 崩溃](https://appmetrica.yandex.by/docs/zh/settings/crashes.md)页面查看。

缺失的 dSYM 文件可以通过以下方式上传：

- 使用 fastlane
- 通过网页界面
- 使用 helper

{% cut "使用 fastlane" %}

1. 安装 `appmetrica` fastlane 插件：

   ```
   fastlane add_plugin appmetrica
   ```

   有关添加插件的更多信息，请参阅 [fastlane 文档](https://docs.fastlane.tools/plugins/using-plugins/#add-a-plugin-to-your-project)。

1. 在 `fastlane/Fastfile` 文件中添加以下内容：

   ```
   lane :refresh_dsyms do
   download_dsyms
   upload_symbols_to_appmetrica(post_api_key: "Post API key")
   clean_build_artifacts
   end
   ```

   在 `download_dsyms` action 中，您可以指定所需的应用版本和构建号：

   ```
   ...
   download_dsyms(version: "1.0.0", build_number: "345")
   ...
   ```

   有关 `download_dsyms` action 的更多信息，请参阅 [fastlane](https://docs.fastlane.tools/actions/download_dsyms/) 文档。

{% endcut %}

{% cut "通过网页界面" %}

1. 找到包含 dSYM 文件的所需归档：

   {% cut "通过 Xcode Organizer" %}

   1. 在 Xcode 界面中点击 **Window** → **Organizer**。
   1. 在 **Archives** 选项卡中选择所需的应用版本。
   1. 点击 **Download dSYM** 按钮。

   ![插图](../../_images/xcode-archives_organizer.png){style="border: solid 1px #cccccc; max-width: 800px;"}

   {% endcut %}

   {% cut "通过 App Store Connect" %}

   1. 在 iTunes Connect 界面中打开 **Activity** 页面。
   1. 在 **All Builds** 选项卡中选择所需的构建号。
   1. 点击 **Download dSYM**。

   ![插图](../../_images/itunes-connect.png){style="border: solid 1px #cccccc; max-width: 800px;"}

   {% endcut %}

   您可以使用构建时生成的 dSYM 文件。

1. 在 AppMetrica 界面中，从左侧菜单进入应用设置。
1. 打开 **崩溃** → **iOS** 选项卡。
1. 点击**选择文件**按钮，上传包含 `app.dSYM` 或 `app` 目录的 ZIP 归档。

{% endcut %}

{% cut "使用 helper" %}

要使用插件上传，需要连接 3.8.0 或更高版本的 AppMetrica SDK。要将缺失的 dSYM 文件上传到 AppMetrica，请在终端中运行命令：

```
helper -k <post-api-key> <file_path>
```

`file_path` 是 dSYM 文件或包含它们的文件夹的列表。

[helper 工具参考](#helper)。

{% endcut %}

###### helper 工具参考 {#helper}

{% note info %}

`helper` 工具从 3.8.0 版本开始包含在 AppMetrica SDK 中。它位于 SDK 归档中。

{% endnote %}

Helper 是一个命令行工具，允许您将 dSYM 文件上传到 AppMetrica。

```
$ helper [auto] [-o | --package-output-path=<path>] [-v | --verbose]
         [--version] -k <post-api-key> | --post-api-key=<key> [file ...]
```

**参数**

#|
||
**参数** | **描述**
||
||
`auto`
|
自动上传模式。在此模式下，`helper` 使用以下变量：`CONFIGURATION` — 用于确定配置。如果构建使用 `Debug` 配置，则不会上传 dSYM 文件。`DWARF_DSYM_FOLDER_PATH` — 用于查找 dSYM 文件。它通常取决于 `BUILT_PRODUCTS_DIR` 变量。`AMA_POST_API_KEY` — Post API key。如果指定，在自动模式下可以使用短命令 `helper auto&`。
||
||
`-k`
|
Post API key。可以在 AppMetrica 的**设置**部分获取。它用于标识您的应用。
||
||
`-o`
|
存储临时文件的文件夹路径。默认使用系统文件夹。
||
||
`-v`
|
启用附加信息的显示。
||
||
`--version`
|
输出版本。
||
||
`file`
|
dSYM 文件或包含它们的文件夹的列表。默认使用本地工作文件夹。
||
|#

`&` 允许您并行运行 `helper`，而不会阻塞整个项目的构建。示例命令：

```
helper auto --post-api-key="Post API key"&
```

###### 了解更多 {#learn-more-ios}

- [崩溃和错误报告](https://appmetrica.yandex.by/docs/zh/mobile-reports/crashes-and-errors.md)
- [Apple 文档](https://developer.apple.com/library/archive/technotes/tn2151/_index.html)

Post API key 可以在 AppMetrica 的**设置**部分获取。它用于标识您的应用。

#### 如何检查结果 {#check-result}

1. 在测试环境中复现受控的错误或故障。
1. 打开[崩溃和错误](https://appmetrica.yandex.by/docs/zh/mobile-reports/crashes-and-errors.md)报告，找到测试版应用的数据。
1. 检查消息、设备和调用堆栈 — 与故障相关的函数序列。
1. 如果堆栈不可读，请检查是否存在专门针对此构建的调试文件。

崩溃按调用堆栈分组；错误分组取决于发送方法。详情见[崩溃和错误文档](#crash-vs-error)。

#### 在不同平台上发送错误 {#send-errors-platforms}

- [Android](https://appmetrica.yandex.by/docs/zh/sdk/android/analytics/android-operations.md#send-report-error)
- [iOS](https://appmetrica.yandex.by/docs/zh/sdk/ios/analytics/ios-operations.md#send-report-error)
- [Flutter](https://appmetrica.yandex.by/docs/zh/sdk/flutter/analytics/flutter-operations.md#send-report-error)
- [React Native](https://appmetrica.yandex.by/docs/zh/sdk/react-native/analytics/react-native-operations.md#send-report-error)
- [Unity](https://appmetrica.yandex.by/docs/zh/sdk/unity/analytics/unity-operations.md#send-report-error)

{% endcut %}

## 如何处理报告 {#work-with-report}

1. 选择时间段。打开[崩溃和错误](https://appmetrica.yandex.by/docs/zh/mobile-reports/crashes-and-errors.md)报告。例如，发布新版本后，查看自其发布以来的时间段。
1. 评估规模。比较故障数量和发生故障的设备数量。单个设备上的频繁故障和影响许多设备的问题需要不同的评估。
1. 查找发生条件。查看应用版本、操作系统和设备。打开所需的组 — 其中包含相关的故障案例。
1. 研究故障前的操作。打开具体案例的记录，点击"查看会话事件"。如果收集了相应的事件，历史记录将有助于还原用户的操作。
1. 将问题传递给开发人员。指明应用版本、问题规模和已知的用户步骤。任务链接可以添加到组评论中。

评估优先级时，还要考虑对场景的影响：例如，无法下单可能比很少使用的屏幕上的错误更重要。故障的技术原因由开发人员确定。

## 如何检查修复 {#check-fix}

发布修复后，检查问题是否在新版应用中发生。在分析中区分版本：只要用户还在使用旧版本，旧版本中的故障可能会继续到达。

可以关闭已修复的组，以将其与当前问题区分开。如果故障出现在之前未观察到的版本中，该组将重新打开。

要通过电子邮件了解问题，请设置[电子邮件通知](https://appmetrica.yandex.by/docs/zh/data-collection/crash-mails.md)。

<!-- source: zh/_includes/feedback-button.md -->
如果您没有找到所需答案，可以通过反馈表单提交您的问题。 请尽可能详细地描述问题。 如果可能，请附上截图。

<a href="../troubleshooting/feedback-new">
  <span class="button">联系支持</span>
</a>

<a href="../troubleshooting/feedback-docs">
  <span class="button">为文档提出改进建议</span>
</a>
<!-- endsource: zh/_includes/feedback-button.md -->