使用 Sentry

编辑页面

安装和配置 Sentry 以进行崩溃报告的指南。

Android

iOS

Web

Sentry 是一个崩溃报告平台，为你提供对生产环境部署的实时洞察，以及用于复现和修复崩溃的信息。

它会在用户使用你的应用时通知你出现的异常或错误，并在网页仪表板中为你整理这些信息。报告的异常会自动包含堆栈跟踪、设备信息、版本以及其他相关上下文。你还可以提供特定于你应用的额外上下文，例如当前路由和用户 ID。

你将学到什么

本指南涵盖将 Sentry 集成到 Expo 项目的三个主要方面：

在你的 React Native 应用中安装并配置 Sentry
在 EAS 中使用 Sentry：
- 用于构建应用的EAS Build
- 用于空中更新的EAS Update
设置 Sentry-Expo 集成，以便直接在你的 EAS 仪表板中查看崩溃报告和会话回放

安装并配置 Sentry

注册 Sentry 账号并创建项目

在继续安装 Sentry 之前，你需要确保已经创建了 Sentry 账号和项目：

1.1

organization slug 可在你的 Organization settings 选项卡中找到
项目名称可在你的项目的 Settings > Projects 选项卡中找到（在列表中查找）
DSN 可在你的项目的 Settings > Projects > Project name > SDK Setup 部分下的 Client Keys (DSN) 选项卡中找到

1.2

前往 Developer Settings > Auth Tokens 页面，创建一个新的 Organization Auth Token。该 token 会自动配置为 Source Map Upload 和 Release Creation 的权限。请保存它。

当你拥有以下各项后：organization slug、项目名称、DSN 和 auth token，就可以继续下一步了。

使用 Sentry 向导设置你的项目

在 Expo 项目中设置 Sentry 最简单的方法是使用 Sentry 向导。该工具会自动为你的项目配置正确的设置。

在你的项目目录中运行以下命令：

Terminal

- npx @sentry/wizard@latest -i reactNative

该向导将会：

安装所需依赖
配置你的项目以使用 Sentry
自动设置 Metro 配置
将必要的初始化代码添加到你的应用中

按照向导中的提示完成设置流程。向导会引导你登录 Sentry 账号，并获取与你的项目相关的所有正确信息。

验证配置

为你的应用创建一个新的发布构建，并验证它是否正确上传了 sourcemaps。你可以考虑在应用中添加一个按钮来测试它是否正常工作并且 sourcemaps 是否按预期接入，例如：

import { Button } from 'react-native';

// 在某个组件内部
<Button title="点我" onPress={() => { throw new Error('Hello, again, Sentry!'); }}/>

与 EAS Build 一起使用

请确保在你的构建环境中设置了 SENTRY_AUTH_TOKEN，Sentry 就会自动为你上传 source maps。如果你使用的是环境变量而不是应用配置中的属性，也请确保这些变量同样已设置。

按照上述说明，在使用 EAS Build 时，无需额外工作即可将 Sentry 集成到你的项目中。

与 EAS Update 一起使用

运行 eas update 后，将 source maps 上传到 Sentry：

Terminal

# 将 `eas update` 生成的 "dist" 目录传递给上传脚本

- npx sentry-expo-upload-sourcemaps dist

就是这样！你更新中的错误现在将在 Sentry 中被正确符号化。

你想在一个命令中同时发布更新和 sourcemaps 吗？

你可以使用 && 将命令串联起来，一步完成发布更新并上传 sourcemaps：

Terminal

- eas update --branch <branch> && npx sentry-expo-upload-sourcemaps dist

你想为错误报告附加额外的更新相关元数据吗？

将 Sentry 配置为使用与你的更新相关的信息标记你的 scope，可以让你在 Sentry 仪表板中看到发生在某些更新中的错误。

请尽早在应用生命周期中的全局 scope 里添加以下代码片段。

import * as Sentry from '@sentry/react-native';
import * as Updates from 'expo-updates';

const manifest = Updates.manifest;
const metadata = 'metadata' in manifest ? manifest.metadata : undefined;
const extra = 'extra' in manifest ? manifest.extra : undefined;
const updateGroup = metadata && 'updateGroup' in metadata ? metadata.updateGroup : undefined;

Sentry.init({
  // dsn、release、dist 等...
});

const scope = Sentry.getGlobalScope();

scope.setTag('expo-update-id', Updates.updateId);
scope.setTag('expo-is-embedded-update', Updates.isEmbeddedLaunch);

if (typeof updateGroup === 'string') {
  scope.setTag('expo-update-group-id', updateGroup);

  const owner = extra?.expoClient?.owner ?? '[account]';
  const slug = extra?.expoClient?.slug ?? '[project]';
  scope.setTag(
    'expo-update-debug-url',
    `https://expo.dev/accounts/${owner}/projects/${slug}/updates/${updateGroup}`
  );
} else if (Updates.isEmbeddedLaunch) {
  // 如果该更新是构建中内嵌的那个更新，而不是从 updates 服务器下载的更新，则这里会是 `true`。
  scope.setTag('expo-update-debug-url', 'embedded updates 不适用');
}

配置完成后，与该更新相关的信息将显示在错误的标签部分中：

Sentry 与 EAS 仪表板集成

Sentry 与 Expo 的集成让你可以直接在 EAS 仪表板中查看 Expo 应用部署的崩溃报告和 Session Replays。此集成提供了到 Sentry 堆栈跟踪的直接链接，并包含完整上下文、会话回放和调试能力。

安装

安装此集成需要 Sentry 的 owner、manager 或 admin 权限。

登录你的 Expo 账号，并打开 Account settings > Overview。
在 Connections 下，点击 Sentry 旁边的 Connect。
登录你的 Sentry 账号，并接受将该集成加入你的组织。之后你会被重定向回 Account settings。

关联你的项目

连接账号后，你需要将你的 EAS Project 关联到你的 Sentry Project：

在 EAS 中打开 Projects > [Your Project] > Configuration > Project settings。
点击 Link，并从下拉菜单中选择你的 Sentry Project。

使用

要在 EAS 仪表板中查看你的 Sentry 数据，请打开 Projects > [Your Project] > Updates > Deployments > [Deployment]，以查看来自某个 Release 的 Sentry 数据。

通过此集成，你可以：

直接在 EAS 仪表板中查看崩溃报告
访问 Session Replays，准确查看错误发生前发生了什么
获取包含完整上下文的详细堆栈跟踪
在 EAS 和 Sentry 之间无缝切换以进行调试

了解更多关于 Sentry 的信息

Sentry 不仅仅能捕获致命错误，还可以通过他们的 JavaScript usage 文档了解更多关于如何使用 Sentry 的信息。