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企业指南

Install the SDK with the wizard from the project root:

npx @sentry/wizard@latest -i reactNative

从项目根目录使用向导安装 __CAPGO_KEEP_0__

• 向导会问一些开发人员经常快速点击的问题：项目选择
• 选择您打算在生产中使用的实际Sentry项目，而不是您会忘记更新的临时沙盒。. 说是肯定的。仅仅使用 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.

A practical pattern is to load the DSN from environment-specific config and initialize Sentry before the rest of your app tree mounts. If you’re also working through startup polish, this guide to React Native splash screen setup is useful because startup code order often intersects with where teams place Sentry initialization.

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

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

配置 Native iOS 和 Android 项目

在这个阶段，许多 React Native 团队会产生错误的完成感。 JavaScript SDK 已经安装，事件显示出来，大家都以为崩溃报告已经完成了。然而，它并没有。 如果 native 集成关闭，许多您关心的崩溃事件将永远无法以可用的形式到达 Sentry。

iOS 中发生了什么变化

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

在 Xcode 中检查这些地方：

• 应用启动 code. iOS 应用需要在启动早期进行本机 Sentry 初始化。
• 构建阶段. 查找与调试符号或源映射处理相关的 Sentry 上传脚本。
• 构建设置和存档行为. symbol 文件必须在存档构建期间生成并可用。

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

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

如果 iOS 崩溃在 Sentry 中以不可读的本机帧出现，问题通常不是“Sentry 失效了”。通常是符号上传或发布匹配的问题。

Android 中发生了什么变化

Android 通常在 Gradle 文件和有时在清单级别配置中添加更改。请检查 android/build.gradle, android/app/build.gradle,以及任何与 Sentry 相关的插件或任务编排。

Things to verify:

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

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

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

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

使用此检查清单：

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

以下通常不太有效：

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

自动化发布和源码映射

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

手动源码映射上传听起来在你频繁发布时是可以接受的。在实际情况下，它们失败了，因为人类在重复的发布记账中很差。

为什么手动上传失败

失败模式是可预测的：

• 有人忘记上传地图 在深夜的修复后。
• 上传的文件属于一个不同的提交 而用户运行的二进制或 OTA 包所对应的提交。
• 发布名称在 iOS、Android 和 CI 步骤之间会有所不同。 上传地图后会发生重建
• 并使 Sentry 匹配的内容失效。 因此，我不建议采用“在 Notion 中记录步骤”的方法。它在紧急发布出问题时会失效。

一张七步流程图，展示了 React Native 的 Sentry 发布和源码地图的自动化管理过程。

可靠的设置有几个特点：

__CAPGO_KEEP_0__

• Release IDs会在第一次生成后 被重复使用。
• 构建、打包和上传步骤都在同一条流水线中发生.
• 源映射从CI上传而不是开发人员的笔记本电脑。
• 应用程序使用CI上传时使用的相同的发布字符串 初始化 Sentry。

最后一点比人们通常期望的更重要。您不仅需要在 Sentry 中有源映射。您还需要 将正确的源映射附加到应用程序在运行时发出准确的发布标识符.

如果您的团队已经标准化了移动自动化，这份关于 使用GitHub Actions自动构建和发布工作流的指南 与相同的运营模型相符。

A practical CI script pattern

在 CI 中使用类似这样的脚本，并从管道环境中获取值：

#!/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 在这里变得有用，当您停止将其视为错误收件箱时，开始对应用程序行为进行仪表化。

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

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

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 methods 可能会根据__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 异常和本机崩溃。
• 发布和 dist. 如果它们是空的或错误的，源映射和符号化将会漂移。
• 堆栈帧. 应该上传的 JavaScript 映射的可读源位置应出现。
• 面包屑和标签. 确认您的自定义上下文已到达。
• 环境. 确保开发和生产事件不会混入一个流中。

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

Sentry React Native 常见问题

保持一个小型“监控烟雾测试”清单在发布过程中，一个有用的习惯是这样的：在测试环境触发一个JS事件，确认发布值，验证源位置，然后才推动一个构建

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

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

解决方案是让 Sentry 的发布标识跟随 live 包，而不是仅仅跟随原生的二进制文件 将发布标识匹配到live包对于Live Update工作流程，应将__CAPGO_KEEP_0__和__CAPGO_KEEP_1__视为与交付的JavaScript包相关的运行时标识。原生的应用版本仍然很重要，但一旦包可以独立改变，它就不够了

一个实用的模式如下：

一个实用的模式如下： release 一个实用的模式如下： dist 一个实用的模式如下：

一个实用的模式如下：

• 使用原生应用版本作为基本发布名称的一部分。
• 在发布名称中追加实时更新版本或包标识符。
• 使用 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 的截图。

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

避免的主要错误是重复使用一个静态发布字符串来处理每个后端更新。如果多个捆绑包共享相同的Sentry发布，调试就变成了猜测游戏。

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