跳过主要内容
Capgo logo
移动 Capacitor 指南

Sentry React Native: 2026年整合指南

将 Sentry React Native 从头到尾与我们的 2026 年指南进行整合。涵盖了设置、原生崩溃、源映射、性能和 Capgo 整合

马丁·多纳迪厄

马丁·多纳迪厄

内容营销
Sentry React Native: 2026年整合指南

您已经在本地环境下拥有一个工作的 React Native 应用程序，QA 已经通过了测试，生产环境也快到了。然后，一个明显的问题出现了：当它在用户设备上崩溃时会发生什么?

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

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

目录

开始使用 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 项目，而不是您会忘记更新的临时沙盒。
  • 原生变化. 说是。仅使用 JavaScript 来捕获错误并不能满足移动应用的需求。
  • 可选功能. 只开启你知道会使用的功能，但不要在团队未对结果数据进行审查的情况下，盲目开启所有功能。

运行向导并审查结果

向导完成后，请审查修改的代码，而不是简单地信任它们。您应该在 package.json中看到一个 Sentry 包 ios ，以及 android中的本机代码修改。

，并且在您的应用入口文件中会看到一个初始化块。

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

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

典型的初始化代码如下： DSN 告诉 SDK 在哪里发送事件。将其视为配置，而不是一个必须始终不可见的机密存储项。它与授权令牌不同。然而，请确保环境设置清洁且一致，以便您的应用在每个环境中都指向正确的 Sentry 项目。

A实践模式是从环境特定的配置中加载DSN并在应用树的其余部分挂载之前初始化Sentry。如果您还在优化启动过程中，这个指南是有用的，因为启动顺序通常与团队在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 初始化。
  • 构建阶段. 查找与调试符号或源映射处理相关的任何 Sentry 上传脚本。
  • 构建设置和存档行为. 必须在存档构建期间生成和可用的符号文件。

如果您的应用程序使用 AppDelegate.mm在 React Native 桥接启动时，初始化通常会紧随其后。具体文件内容可能因 React Native 版本、模板以及是否使用新架构而有所不同，因此请勿从随机仓库复制代码片段，除非它们与您的项目形状相符。

是什么最重要：意图。iOS原生崩溃需要符号数据，而应用程序必须在崩溃被可靠观察到之前启动Sentry。

如果在 Sentry 中出现 iOS 崩溃并且 native 框架无法读取，问题通常不是“Sentry 出现问题”。通常是 symbol 上传或发布匹配的问题。

安卓上的变化

Android 通常在 Gradle 文件中添加更改，并且有时还会在清单级别进行配置。 请查看 android/build.gradle, android/app/build.gradle, 并且任何 Sentry 相关的插件或任务编排。

需要验证的内容：

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

一个常见的 Android 错误是假设成功的本地调试运行证明了发布设置是正确的。它并没有。发布路径是不同的，尤其是在最小化和 CI 签名进入场景时。 如果您的团队维护独立的调试、测试、QA 和商店构建，以下关于 移动构建类型 的分解是一个有用的参考，用于保持监控行为与每个构建变体相对应

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

不要只停留在“向导修改了文件”。直接验证行为。

使用此检查清单：

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

这里通常不起作用：

方法 什么会出错
信任未经审查的魔法师 React Native 或构建工具发生变化时，原生设置会漂移
仅在调试模式下进行测试 调试成功掩盖了发布时符号化问题
混合手动和自动上传步骤 物件在不同发布中落地，无法匹配事件

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

自动化发布和源码映射

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

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

为什么手动上传失败

失败模式是可预测的：

  • 有人忘记上传地图 在深夜修复后。
  • 上传的文件属于一个不同的提交 而用户运行的二进制或OTA包所对应的提交不同。
  • 发布名称在iOS、Android和CI步骤之间会有所不同。 上传地图后会触发重新构建
  • 从而使Sentry无法正确匹配。 因此我不建议采用“在Notion中记录步骤”的方法。它在压力下发布紧急版本时会失效。

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

一个真正可靠的发布流程

可靠的设置有几个特点：

__CAPGO_KEEP_0__

  • Release ID 将在第一次生成后重复使用 并在整个应用中重复使用。
  • 构建、打包和上传步骤发生在同一流水线中.
  • 源映射从 CI 上传而不是从开发人员的笔记本电脑上传。
  • 应用程序使用 CI 在上传期间使用的相同的发布字符串初始化 Sentry 上述这一点比人们通常期望的更为重要。您不仅需要在 Sentry 中包含源映射。您还需要将正确的源映射附加到应用程序在运行时发出emit的确切发布标识符上

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

自动构建和发布工作流程指南 适用于使用 GitHub Actions 的相同运营模型 自动构建和发布工作流程指南

A CI 脚本的实用模式

在 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 视为错误收件箱并开始.instrument 应用行为时，Sentry 就变得有用。

一名编码的软件开发人员坐在一台笔记本电脑上，背景监视器上显示数据可视化图表。

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

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

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

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

一个实用的仪表板示例：

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

这比凭直觉推断要好。

对于思考广泛的 WebView 或混合应用监控模式的团队，这篇关于在 __CAPGO_KEEP_0__ 项目中进行性能监控的文章 performance monitoring in Capacitor projects Start by enabling performance tracing in your initialization. The exact sampling strategy depends on your environment and volume tolerance, but the structure looks like this:

添加有用的上下文到错误

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

使用这些工具有意识地：

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

示例：

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' },
  });
}

面包屑路径通常是“用户说应用程序冻结了”和“应用程序在打开仪表板、启动同步和重试过时请求后失败了”的区别。

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

验证和调试您的集成

在发布之前、构建管道更改之后和SDK升级之后，您应该验证 Sentry。‘几个月前它工作过’不是一个有意义的测试。

最干净的方法是触发 JavaScript 和本机路径的控制故障，然后检查它们如何在 Sentry 中到达。

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

安全触发测试事件

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

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

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

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

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

Sentry UI 中要检查的内容

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

检查这些字段：

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

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

Sentry React Native 常见问题

症状 可能原因 解决方案
JavaScript 错误到达，但堆栈跟踪被压缩 源映射没有上传到匹配的发布 验证 CI 在打包后上传映射，并且 release 在 Sentry.init() 与
原生崩溃不出现 原生SDK 钩子缺失或初始化太晚 重新检查iOS和Android原生设置，然后在QA构建中使用受控原生崩溃路径进行测试
iOS原生帧不可读 调试符号未上传或未链接到正确的构建 确认存档构建生成符号并且上传步骤在CI或Xcode存档流程中运行
Android发布行为与调试行为不同 压缩或混淆会改变发布工件路径 查看发布Gradle任务并验证Sentry处理在发布变体中运行
事件出现在错误的环境下 构建时配置泄露到环境之间 分别为每个构建目标设置DSN、环境、发布和dist值
面包屑或用户数据丢失 上下文设置太晚或在应用状态变化时清除 立即在认证状态解析后设置用户和标签，并在关键流程周围添加面包屑

保持一个小型的“监控烟雾测试”清单在发布过程中，触发一个JS事件在测试环境，确认发布值，并验证源位置之前发布一个构建

与Live Update工作流程集成，如Capgo

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

解决方案是让 Sentry发布标识随着live包一起改变，而不是仅仅是原生的二进制文件匹配发布标识符到live包

对于live更新工作流程，视

和 release context:Capgo营销网站。角色：短UI标签或导航项。见于：page trust.astro。消息键`and`（And） 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_KEEP_0__

capgo

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

如果您的团队在应用商店审查周期外发布修复 Capgo is worth evaluating. It gives Capacitor teams a structured way to deliver live updates, target channels, control rollouts, and recover from bad releases quickly. Pair that with disciplined Sentry release naming and source map uploads, and you get a workflow where errors still point to the exact code users are running.

为 Capacitor 应用提供实时更新

When a web-layer bug is live, ship the fix through Capgo instead of waiting days for app store approval. Users get the update in the background while native changes stay in the normal review path.

当 web 层 bug 活跃时，通过 __CAPGO_KEEP_0__ 发布修复，而不是等待几天的 app 商店审批。用户在后台接收更新，而原生变化仍在正常审查路径中。

上下文: Capgo 营销网站。角色: 支持描述段落或元描述。见于组件 GetStarted.astro。保留 Capgo 产品/品牌和开发者术语的原始形式。消息键 `instant_updates_for_capacitor_apps_description` (Instant Updates For Capacitor Apps Description)。

来自 Martin 的人工支持

Capgo gives you the best insights you need to create a truly professional mobile app.

2-Way Communication in Capacitor Apps
开发 移动 +1
2025年4月26日

2-Way Communication in Capacitor Apps

避免的5种OTA更新常见错误
开发 安全 +1
context: 企业产品/价格页面。角色: UI标签。位置: 企业页面。

2025年4月13日

5 移动应用实时更新的安全最佳实践
开发 移动 +1
2025 年 1 月 14 日

5 移动应用实时更新的安全最佳实践

查看所有博客文章