Sentry React Native: 2026年整合指南

您已经拥有一个正在本地运行的 React Native 应用程序，QA 已经批准了它，生产也快到了。然后，一个明显的问题出现了：当它在用户设备上崩溃时会发生什么？

没有 Sentry，答案通常很糟糕。您会得到一个支持票，一个模糊的截图，可能是一个开发构建的控制台日志，它与生产构建不符。使用 Sentry React Native 进行正确的设置，您会得到错误、堆栈、发布它的版本以及足够的上下文来修复它而不必猜测。问题在于 基本安装是容易的部分. 实际上，痛苦的部分是后来发生的：原生集成、符号化、源映射、发布命名以及在您的交付模型中包含实时更新时保持所有这些内容的对齐。

大多数指南都太早停止了。一个真正的设置必须能够承受CI、App Store构建、Android发布和JavaScript捆绑包，这些捆绑包并不总是来自原始二进制文件。

目录

• Getting Started with the Sentry SDK
  • 您需要在安装之前准备什么
  • 运行向导并查看结果
• 配置原生 iOS 和 Android 项目
  • iOS 上发生了什么变化
  • Android 上发生了什么变化
  • 原生设置可以节省后来花在此处的时间
• 自动化发布和源映射
  • 为什么手动上传会失败
  • 一个能真正发挥作用的发布流程
  • 实用的CI脚本模式
• 捕获性能数据和自定义事件
  • 通过追踪慢屏幕而不是猜测
  • 为错误添加有用的上下文
• 验证和调试您的集成
  • 安全地触发测试事件
  • 在Sentry UI中检查什么
  • Sentry React Native常见问题
• 与Capgo类似的实时更新工作流程集成
  • 匹配发布标识符到实时包

Sentry SDK

快速入门Sentry React Native的方法是使用安装向导。它处理了大部分重复的设置，并快速让您达到一个工作基线。这很重要，因为手动安装通常会导致您无法察觉的细微差异，直到第一个生产故障发生。

安装之前需要什么

您需要先安装一个正常的React Native开发环境。包括Node、包管理器、iOS和Android的平台工具以及macOS上的Watchman。如果您的工作流程中已经包含了这些工具，那么您也需要一个Sentry账户和一个为React Native创建的项目。

如果您仍在评估是否React Native是您的团队的正确运维选择，这个 关于React Native的企业指南 提供了有关平台权衡、人员配置和维护预期的有用的非营销背景。阅读它之前，您应该在共享代码库中提交监控和发布过程。

从项目根目录使用向导安装SDK：

npx @sentry/wizard@latest -i reactNative

向导会问一些开发人员经常快速点击的问题：

• 项目选择选择您打算在生产中使用的实际Sentry项目，而不是您会忘记更新的临时沙盒。
• 原生变更. 说 yes。仅使用 JavaScript 的错误捕获对于移动应用程序来说是不够的。
• 可选功能. 开启你知道你会使用的功能，但不要在第一天就盲目开启所有功能，如果你的团队不会审查结果数据。

运行向导并审查结果

向导完成后，检查修改项而不是信任它们而不进行审查。你应该在 package.json中看到一个 Sentry 包 ios ，native 修改项在 android，和一个初始化块在你的应用程序入口文件中。

一个典型的初始化看起来像这样：

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

Sentry.init({
  dsn: 'YOUR_DSN',
});

DSN 告诉 __CAPGO_KEEP_0__ 发送事件的位置。将其视为配置，而不是一个必须永远不可见的机密存储项。它与认证令牌不同。然而，请保持你的环境设置干净和一致，以便你的应用程序在每个环境中都指向正确的 Sentry 项目。 tells the SDK where to send events. Treat it as configuration, not as a secret vault item that must never be visible. It isn’t the same as an auth token. Still, keep your environment setup clean and consistent so your app points to the right Sentry project in each environment.

在环境特定的配置中加载DSN并在应用树挂载之前初始化Sentry是一个实用的模式。如果您还在优化启动时间， React Native启动屏幕设置 is useful because startup code order often intersects with where teams place Sentry initialization.

实用规则： 尽早在应用启动时初始化Sentry。如果您等到导航、身份验证、远程配置之后，会错过启动失败的事件。

在这个阶段，不要追求完美。立即目标是简单的：启动应用，稍后在文章中触发JavaScript异常，并确认事件已成功发送到Sentry。一旦这项工作正常，native和发布层就更容易理解了。

配置Native iOS和Android项目

在这个阶段，许多React Native团队会产生错误的完成感。JavaScriptSDK已安装，事件已显示，人们认为崩溃报告已完成。然而，它并没有。

如果native集成未启用，某些您关心最多的崩溃将永远无法以可用的形式发送到Sentry。

iOS中的变化

打开iOS项目并检查向导所做的更改。在一个裸露的React Native应用中，这通常意味着应用启动和构建阶段的更新。您正在寻找Sentry初始化钩子和与构建过程相关的上传步骤。

• App delegate startup code. 应用程序需要在启动时尽早初始化本机 Sentry。
• Build Phases. 查找与调试符号或源映射处理相关的 Sentry 上传脚本。
• Build settings and archive behavior. symbol 文件必须在存档构建期间可用。

如果您的应用程序使用 AppDelegate.mm，则初始化通常位于 React Native 桥启动引导程序附近。具体文件内容可能因 React Native 版本、模板以及是否使用新架构而有所不同，因此请勿从随机仓库复制snippets，除非它们与您的项目形状相匹配。

关键是意图：iOS 本机崩溃需要符号数据，应用程序必须在崩溃可靠观察之前启动 Sentry。

如果在 Sentry 中出现无法读取的 iOS 本机帧，问题通常不是“Sentry 失败了”。通常是符号上传或发布匹配问题。

Android 中发生了什么变化

Android 通常在 Gradle 文件和 manifest-level 配置中添加更改。请检查 android/build.gradle, android/app/build.gradle，以及任何 Sentry 相关的插件或任务编排。

Things to verify:

1. Sentry Gradle 插件已应用 因此，可以在构建时间处理发布 artifact。
2. 变体处理是正常的 如果您使用产品风味或多个构建类型。
3. ProGuard 或 R8 输出已考虑 如果您的发布构建缩小或混淆 code。

Android 的常见错误是假设成功的本地调试运行证明了发布设置是正确的。它并没有。发布路径是不同的，尤其是在 minification 和 CI 签名进入场景时。 如果您的团队维护独立的调试、测试、QA 和商店构建， 移动构建类型

的分解是一个有用的参考，用于保持监控行为与每个构建变体相对应。

原生设置检查可以节省时间后期的检查项。

使用此检查清单：

• 将 iOS 构建存档到本地 并确认构建过程中符号处理没有失败。
• 创建一个发布 Android 构建 并检查 CI 日志以查找 Sentry 相关任务。
• 检查 Sentry 中的包名和捆绑标识符映射 如果您在一个组织下管理多个应用，请在 Sentry 中检查包名和捆绑标识符映射。
• 确认发布命名约定在 CI 开始上传不一致名称的艺术品之前确认发布命名约定。

通常不太有效的方法是：

最好的设置是无聊的。原生启动钩子已经在位，构建脚本每次都运行，发布命名在 iOS、Android 和 JavaScript 包装之间是确定的。

自动化发布和源码映射

如果有一个地方可以让 Sentry React Native 设置崩溃，那就是这里。团队安装了 SDK，看到事件，推迟了发布自动化。然后第一个严重的生产问题出现了，堆栈跟踪被压缩，发布缺失，或者源码映射上传属于不同的包装。

为什么手动上传失败

失败模式是可预测的：

手动上传听起来在实际运作中是可接受的，当你频繁发布时。然而，在实践中，它们失败了，因为人类在重复的发布记录中很差。

• 有人忘记上传地图 在深夜发布修复后
• 上传的文件属于一个不同的提交 而用户运行的二进制或 OTA 包的提交不同
• 发布名称在 iOS、Android 和 CI 步骤之间略有不同 上传地图后会发生重建
• 这使 Sentry 匹配的内容失效 所以我不推荐在 Notion 中记录步骤的方法

它在紧急发布压力下发布时会有效

一个能真正坚持的发布流程

可靠的设置有几个特性

• Release IDs会在第一次生成后 被重复使用。
• 构建、打包和上传步骤都在同一条流水线中发生.
• 源映射从CI上传而不是开发人员的笔记本电脑。
• 应用程序使用CI上传时使用的相同发布字符串初始化Sentry。 上述最后一点比人们通常期望的更重要。您不仅需要在Sentry中提供源映射。您还需要

将正确的源映射附加到应用程序在运行时发出且准确的发布标识符上 如果您的团队已经标准化了移动自动化，这份关于.

使用__CAPGO_KEEP_0__ Actions的自动构建和发布工作流程指南 automatic build and release workflows with GitHub Actions 自动构建和发布工作流程指南

A practical CI script pattern

在 CI 中使用类似这样的脚本，通过 pipeline 环境提供值：

#!/usr/bin/env bash
set -euo pipefail

export SENTRY_AUTH_TOKEN="$SENTRY_AUTH_TOKEN"
export SENTRY_ORG="your-org"
export SENTRY_PROJECT="your-project"

RELEASE_NAME="${APP_VERSION}+${GIT_SHA}"

npx sentry-cli releases new "$RELEASE_NAME"

npx react-native bundle \
  --platform ios \
  --dev false \
  --entry-file index.js \
  --bundle-output ./dist/main.jsbundle \
  --sourcemap-output ./dist/main.jsbundle.map

npx sentry-cli releases files "$RELEASE_NAME" upload-sourcemaps ./dist \
  --rewrite \
  --strip-prefix "$(pwd)"

npx sentry-cli releases finalize "$RELEASE_NAME"

需要适配 Android 的打包命令，并且许多团队将平台相关的任务分开，而不是强制一个脚本同时处理两者。这也没问题。关键是保持一致性。

严格的发布规则比聪明的脚本更重要。 选择一个命名约定，在构建时将其注入应用程序，并且永远不要让本地的临时上传与 CI 相竞争。

对于 React Native，我更喜欢将发布字符串存储在一个构建生成的配置位置，并在 Sentry.init():

Sentry.init({
  dsn: Config.SENTRY_DSN,
  release: Config.SENTRY_RELEASE,
  dist: Config.SENTRY_DIST,
});

结果很简单。当事件到达时，Sentry 可以将最小化的帧映射回您实际发布的 code，而不是您认为您发布的 code。

捕获性能数据和自定义事件

崩溃告诉你什么出了问题。性能跟踪告诉你用户在什么时候放弃了。

一个常见的报告听起来像这样：“仪表板很慢。”这不是足够的调试信息。慢到哪里？在导航？在数据获取？在渲染一个重型图表？Sentry 在这里变得有用，当你停止将其视为错误收件箱，而是开始对应用程序行为进行 instrumenting 时。

跟踪一个慢的屏幕而不是猜测

首先在初始化中启用性能跟踪。具体采样策略取决于您的环境和容量容忍度，但结构如下：

Sentry.init({
  dsn: Config.SENTRY_DSN,
  tracesSampleRate: 1.0,
});

如果您使用 React Navigation，需要将集成与屏幕转换关联起来，以便屏幕转换产生跟踪数据。然后在物理设备上重现抱怨，而不是仅在模拟器上重现。模拟器会隐藏用户注意到的那种缓慢感受。

实用dashboard示例：

1. 用户登录后打开主dashboard。
2. 导航完成，但内容出现迟缓。
3. 跟踪显示屏幕交易时间过长。
4. 子span显示一个API请求和一个昂贵的渲染路径。
5. 您优化渲染路径，重新发布，并比较新的跟踪形状。

比起凭直觉推测，这更好。

对于思考广泛的webview或混合应用监控模式的团队，这篇关于 在Capacitor项目中的性能监控 的文章值得浏览，因为即使堆栈不同，操作思维也是类似的。

添加有用的上下文到错误

性能数据变得更有用时，事件携带商业上下文。 不是虚荣的元数据。 只有足够的信息来回答受影响的用户是谁，用户当前在哪个屏幕上，以及在失败之前发生了什么。

使用这些工具有目的：

• 用户上下文 与 Sentry.setUser() 这样支持人员可以将报告与受影响的帐户相关联，而不必在猜测中挖掘。
• 面包屑 用于像点击提交、打开模态或启动同步这样的操作。
• 自定义标签 用于维度如计划类型、特征标志状态或API区域。
• 捕获的异常信息 当您捕获并重新抛出或表面受控失败时。

A breadcrumb trail is often the difference between “user says the app froze” and “the app failed after opening dashboard, starting sync, and retrying a stale request.”

Sentry.setUser({
  id: user.id,
  email: user.email,
});

Sentry.addBreadcrumb({
  category: 'navigation',
  message: 'Opened dashboard screen',
  level: 'info',
});

try {
  await loadDashboard();
} catch (error) {
  Sentry.captureException(error, {
    tags: { screen: 'dashboard' },
    extra: { widget: 'balance-summary' },
  });
}

当自定义仪表板出现问题时，它通常会因为过于吵闹而出现问题。不要捕获应用程序中的每个按钮点击。捕获边界、状态转换和调试时重要的操作。足够的上下文来解释事件。不要让它淹没。

验证和调试您的集成

您应该在交付之前、构建管道更改之后以及__CAPGO_KEEP_0__升级之后验证 Sentry。 “几个月前它工作正常”并不是一个有意义的测试。

You should verify Sentry before shipping, after build pipeline changes, and after SDK upgrades. “It worked months ago” isn’t a meaningful test.

一名男性软件开发人员坐在电脑监视器上，桌子上有一个测试集成清单，正在编写__CAPGO_KEEP_0__。

对于 JavaScript 错误，请在非生产屏幕上添加一个临时按钮：

对于捕获的异常而不会崩溃的应用程序：

<Button
  title="Trigger JS Error"
  onPress={() => {
    throw new Error('Test JavaScript Sentry error');
  }}
/>

本机崩溃测试应在开发或受控 QA 构建中进行，并且应谨慎进行。exact helper 方法可用性可能会根据__CAPGO_KEEP_0__版本和平台编程而有所不同，所以我更喜欢使用__CAPGO_KEEP_1__的文档化本机崩溃测试工具，而不是自己编写崩溃路径。

<Button
  title="Capture Exception"
  onPress={() => {
    Sentry.captureException(new Error('Handled Sentry test error'));
  }}
/>

Native crash testing should be done carefully and only in development or controlled QA builds. The exact helper methods available can vary by SDK version and platform wiring, so I prefer using the SDK’s documented native crash test utility when present rather than inventing your own crash path.

Sentry UI 中要检查的内容

当事件出现时，检查标题以外的更多内容。

检查这些字段：

• 平台和机制. 这有助于区分 JS 异常和本机崩溃。
• Release 和 dist. 如果它们是空的或错误的，源映射和符号化将会漂移。
• 堆栈帧. 应该上传的 JavaScript 映射的可读源位置应出现。
• 面包屑和标签. 确认您的自定义上下文已到达。
• 环境. 确保开发和生产事件不会混入一个流中。

如果原生事件到达但符号化很差，别再修改 app code. 通常这是一个构建物品问题。

Sentry React Native 常见问题

养成的一个最后习惯是，在发布流程中保留一个微小的“监控烟雾测试”清单。 在测试环境触发一个JS事件，确认发布值，并在发布之前验证源位置

与Capgo类似的Live Update工作流程集成

Live更新改变了发布模型。 商店中的二进制文件可能保持不变，而JavaScript包在下面改变。如果 Sentry仍然只以原来的应用程序版本为依据，堆栈跟踪会变得混乱

解决方案是让 Sentry发布标识符随着live bundle变化而变化，而不是仅仅依赖于原生的二进制文件

将发布标识符与live bundle匹配

对于live更新工作流程， release 和 dist 作为与传递的JavaScript包相关的运行时标识符。 原生的应用程序版本仍然很重要，但一旦包可以独立改变，它就不够了

一个实用的模式看起来像这样：

• 使用原生应用版本作为基本发布名称的一部分。
• 在发布名称中追加实时更新版本或包标识符。
• 使用 dist 用于频道或构建特定差异化时，适合您的模型。
• 在该exact发布标识符下上传每个实时捆绑的源映射。

例如，如果您的应用程序在启动时加载更新元数据，则使用当前活动捆绑的值而不是静态构建配置初始化 Sentry。

Sentry.init({
  dsn: Config.SENTRY_DSN,
  release: activeBundle.releaseName,
  dist: activeBundle.channel,
});

这样，当用户在热修复捆绑中遇到错误时，Sentry 就会将帧解析为热修复的源映射，而不是旧的商店捆绑。

这与任何 OTA 风格的工作流有关。如果您想了解实时更新在 __CAPGO_KEEP_0__ 应用程序中的工作原理的详细信息，这个解释是一个很好的参考。 how live updates work in Capacitor apps 截图来自 https://__CAPGO_KEEP_0__.app

使用原生应用版本作为基本发布名称的一部分。

避免的主要错误是重复使用一个静态发布字符串来更新所有后端。

如果您的团队在应用商店审查周期外修复问题, Capgo 值得评估。它为Capacitor团队提供了一种结构化的方式来交付实时更新、目标频道、控制发布和快速恢复坏的发布。将其与严格的Sentry发布命名和源映射上传相结合，您可以得到一个工作流程，错误仍然指向正在运行的code用户的确切位置。