# @backtrace/react 中文文档 规范地址：https://npmcn.com/package/%40backtrace/react/ 版本：0\.5\.2 npm 元数据更新时间：2026-10-29T16:57:49.208Z 中文译文更新时间：2026-11-07T16:01:42.831Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40backtrace/react 原文对照：https://npmcn.com/package/%40backtrace/react/?lang=original 项目主页：https://github.com/backtrace-labs/backtrace-javascript#readme 源码仓库：https://github.com/backtrace-labs/backtrace-javascript ## 关键信息（来自 npm 元数据） - 包体积（解压后）：3.6 MB，17 个文件 - 模块格式：ESM + CJS - TypeScript 类型：包内自带 - 运行依赖：1 个 - peer 依赖：react \>=16\.8\.0 - 首次发布：2023-10-30T13:13:18.916Z - 最新版本发布：2026-10-29T16:57:48.909Z - 近 30 天下载量：5769（2026-10-08 至 2026-11-06，npm 官方下载统计） - 已发布版本数：8（近 12 个月 2 个） ## 中文简介 回溯跟踪- Javascription 重现集成 ## 安装 ```sh npm install @backtrace/react ``` 也可以使用：`pnpm add @backtrace/react`、`yarn add @backtrace/react`、`bun add @backtrace/react` ## README # **回溯跟踪重现 SDK** [回溯跟踪](https://backtrace.io/) 在您的生产软件中抓取和处理的报告和未处理的例外 您可以通过完整的产品生命周期管理应用质量. 这个 [@ 回溯跟踪/反应](https://npmcn.com/package/%40backtrace/react/#) SDK 将您的 React 应用程序连接到 Backtrace 。 基本的整合是快速和容易的, 之后可以探索丰富的回溯追踪特征集. ## 目录 1. [基本整合 - 报告您的第一个错误](https://npmcn.com/package/%40backtrace/react/#readme-basic-integration) - [安装软件包](https://npmcn.com/package/%40backtrace/react/#readme-install-the-package) - [整合 SDK](https://npmcn.com/package/%40backtrace/react/#readme-integrate-the-sdk) - [添加回溯错误边界](https://npmcn.com/package/%40backtrace/react/#readme-add-a-backtrace-error-boundary) - [上传源代码图](https://npmcn.com/package/%40backtrace/react/#readme-upload-source-maps) 2. [报告特性出错](https://npmcn.com/package/%40backtrace/react/#readme-error-reporting-features) - [属性](https://npmcn.com/package/%40backtrace/react/#readme-attributes) - [文件附件](https://npmcn.com/package/%40backtrace/react/#readme-file-attachments) - [面包屑](https://npmcn.com/package/%40backtrace/react/#readme-breadcrumbs) - [会话重放](https://npmcn.com/package/%40backtrace/react/#readme-session-replay) - [应用稳定性计量](https://npmcn.com/package/%40backtrace/react/#readme-application-stability-metrics) - [计量配置](https://npmcn.com/package/%40backtrace/react/#readme-metrics-configuration) - [计量使用量](https://npmcn.com/package/%40backtrace/react/#readme-metrics-usage) 3. [高级 SDK 特性](https://npmcn.com/package/%40backtrace/react/#readme-advanced-sdk-features) - [回溯跟踪快捷选项](https://npmcn.com/package/%40backtrace/react/#readme-backtraceclient) - [手动发送错误](https://npmcn.com/package/%40backtrace/react/#readme-manually-send-an-error) - [修改/skip 错误报告](https://npmcn.com/package/%40backtrace/react/#readme-modifyskip-error-reports) - [SDK 方法覆盖](https://npmcn.com/package/%40backtrace/react/#readme-sdk-method-overrides) ## 基本融合 ### 安装软件包 ``` $ npm install @backtrace/react ``` ### 整合 SDK 在所有其他脚本之前在您的应用程序中添加以下代码来向 Backtrace 报告客户端错误 . ```ts // Import the BacktraceClient from @backtrace/react with your favorite package manager. import { BacktraceClient, BacktraceConfiguration } from '@backtrace/react'; // Configure client options const options: BacktraceConfiguration = { // Name of the website/application name: 'MyWebPage', // Version of the website version: '1.2.3', // Submission url // is the subdomain of your Backtrace instance (.backtrace.io) // can be found in Project Settings/Submission tokens url: 'https://submit.backtrace.io///json', }; // Initialize the client with the options const client = BacktraceClient.initialize(options); // By default, Backtrace will send an error for Uncaught Exceptions and Unhandled Promise Rejections // Manually send an error client.send(new Error('Something broke!')); ``` ### 添加回溯错误边界 这个 `@backtrace/react` SDK提供一个错误边界,在渲染过程中处理错误,发送错误并 组件堆栈到回溯跟踪,并允许您提供倒置组件. 道具 : ```ts type RenderFallback = () => ReactElement; export interface Props { children: ReactNode; fallback?: ReactElement | RenderFallback; name?: string; // to identify the ErrorBoundary when multiple are used } ``` 用法 : ```ts import { ErrorBoundary } from '@backtrace/react'; import Fallback from './components/Fallback'; ; ``` ### 上传源代码图 客户端错误报告基于已修改的代码. 上传源代码和源代码以解析已修改的代码 您的原始源标识符. [(原始内容存档于2018-10-21) (原始内容存档于2017-09-21)](https://docs.saucelabs.com/error-reporting/platform-integrations/source-map/) ## 报告特性出错 ### 属性 自定义属性是可以添加到您错误报告中的密钥值对. 它们被用于报告汇总, 对错误进行排序和过滤,可以提供更好的背景数据,而且可以提供更多的数据。 它们是许多 高级回溯跟踪特性,详见 [报告文档](https://docs.saucelabs.com/error-reporting/getting-started/)。 。 。 . 有几个地方可以添加,修改或删除属性. #### 将属性对象附加到 BacktraceClient 可以在 [回溯跟踪](https://npmcn.com/package/%40backtrace/react/#readme-backtraceclient) 初始化。 本列表 属性将包含在每个错误报告,称为全局属性. ```ts // Create an attributes object that can be modified throughout runtime const attributes: Record = { release: 'PROD', }; // BacktraceClientOptions const options: BacktraceConfiguration = { name: 'MyWebPage', version: '1.2.3', url: 'https://submit.backtrace.io///json', // Attach the attributes object userAttributes: attributes, }; // Initialize the client const client = BacktraceClient.initialize(options); ``` 您还可以包括创建报告时要解决的属性 : ```ts // BacktraceClientOptions const options: BacktraceConfiguration = { name: 'MyWebPage', version: '1.2.3', url: 'https://submit.backtrace.io///json', // Attach the attributes object userAttributes: () => ({ user: getCurrentUser(), }), }; // Initialize the client const client = BacktraceClient.initialize(options); ``` #### 应用程序运行时添加属性 一旦装入了特定数据(例如用户已经登录),就可以在运行期间设置全局属性. ```ts const client = BacktraceClient.initialize(options); ... client.addAttribute({ "clientID": "de6faf4d-d5b5-486c-9789-318f58a14476" }) ``` 您也可以添加创建报表时要解决的属性 : ```ts const client = BacktraceClient.initialize(options); ... client.addAttribute(() => ({ "clientID": resolveCurrentClientId() })) ``` #### 添加属性到错误报告 BacktraceReport 对象的属性列表可以被直接修改. ```ts const report: BacktraceReport = new BacktraceReport('My error message', { myReportKey: 'myValue' }); report.attributes['myReportKey'] = 'New value'; ``` * * * ### 文件附件 文件可以附在错误报告上. 当将回溯跟踪连接起来, 更新 回溯跟踪 或 动态的特定报告 。 当在 BacktraceClient 中包含附件时, 所有文件都将是 与每份报告一起上传. ```ts // Import attachment types from @backtrace/react import { BacktraceStringAttachment, BacktraceUint8ArrayAttachment } from "@backtrace/react"; // BacktraceStringAttachment should be used for text object like a log file, for example const attachment1 = new BacktraceStringAttachment("logfile.txt", "This is the start of my log") // BacktraceUint8ArrayAttachment should be used for binary files const attachment2 = new BacktraceUint8ArrayAttachment("connection_buffer", new Uint8Array(2)); // Setup array of files to attach const attachments = [attachment1]; // BacktraceClientOptions const options = { name: "MyWebPage", version: "1.2.3", url: "https://submit.backtrace.io///json", // Attach the files to all reports attachments, } const client = BacktraceClient.initialize(options); // Later decide to add an attachment to all reports client.addAttachment(attachment2) // After catching an exception and generating a report try { throw new Error("Caught exception!") } catch (error) { const report = const report = new BacktraceReport(error, {}, [new BacktraceStringAttachment("CaughtErrorLog", "some error logging data here")]) client.send(report); } ``` * * * ### 面包屑 Breadcrumbs是时间顺序数据追踪运行时间事件的片段. 这个SDK默认记录了一些事件, 也可以加入手动面包屑. [(面包屑特性文档)](https://docs.saucelabs.com/error-reporting/web-console/debug/#breadcrumbs) #### 面包屑配置 | 选项名称 | 类型 | 说明 | 默认 | 需要吗? | | --- | --- | --- | --- | --- | | `enable` | 布尔 | 确定面包屑支持是否启用 。 默认情况下, 值会被设定为真 . | `true` | - \- \[ | | `logLevel` | BradecrumbLog 级别 | 指定要包含的日志级别重度。 默认情况下包含所有日志 . | 所有日志 | - \- \[ | | `eventType` | 面包屑Type | 指定要包含的面包屑类型。 默认情况下,所有类型都包括在内. | 所有类型 | - \- \[ | | `maximumBreadcrumbs` | 数目 | 指定由库存储的最大面包屑数量。 默认情况下,只有100个面包屑被储存. | `100` | - \- \[ | | `intercept` | (breadcrumb: RawBreadcrumb) \* \* \* RawBreadcrumb \* \* \* 未定义; | 检查面包屑并允许修改. 如果未定义的值正在从方法被还原,则不会将面包屑添加到面包屑储存中. | 所有面包屑 | - \- \[ | ```ts import { BacktraceClient, BacktraceConfiguration } from '@backtrace/react'; // BacktraceClientOptions const options: BacktraceConfiguration = { // ignoring all but breadcrumbs config for simplicity breadcrumbs: { // breadcrumbs configuration }, }; // Initialize the client const client = BacktraceClient.initialize(options); ``` #### 默认面包屑 | 类型 | 说明 | | --- | --- | | HTTP 密码 | 添加带有url的面包crumb, 请求类型, 并重现获取或 XMLHttp 请求的状态 . | | 历史 | 添加面包屑 在pushstate和流行状态. | | 文件/窗口 | 为文档添加面包屑。单击、文档.dbl点击、文档.drag、文档.trot、窗口.load、窗口.unload、窗口.pagehide、窗口.pageshow、窗口.online和窗口.offline. | | 控制台 | 每次开发者使用控制台日志时都会添加面包屑. | #### 拦截面包屑 如果PII或其他信息需要从面包屑中过滤,您可以使用截取功能来跳过或过滤 清除敏感信息。 任何RawBreadcrumb返回的会用于面包crumb. 如果返回未定义,则无 将添加面包屑. #### 手动面包屑 除了所有自动收集的默认面包屑外,您还可以手动添加面包屑: 属于你自己的. ```ts client.breadcrumbs?.info('This is a manual breadcrumb.', { customAttr: 'wow!', }); ``` * * * ### 会话重放 可选 `@backtrace/session-replay` 模块允许您捕捉并重放导致出错的用户交互。 这为您的错误报告提供了类似视频的上下文,从而更容易复制和调试问题. 会话重放模块的设计以隐私为最高优先. 默认情况下,它会自动遮盖所有文本和输入字段来避免捕获敏感的用户数据. 关于会话重放配置、取样和高级隐私控制的全部细节,请参见 **[会话重放模块文档](https://npmcn.com/package/%40backtrace/session-replay/README.md)**。 。 。 . #### 1\. 安装额外软件包 何况 `@backtrace/react`,您还需要安装会话重放软件包. ```bash $ npm install @backtrace/session-replay ``` #### 2\. 向客户端添加模块 要启用会话重放, 您必须使用 BacktraceClient. builder () 并添加 BacktraceClientReplay Module 。 这将取代标准的 BacktraceClient. 初始化 () . ```ts // Import the necessary modules import { BacktraceClient, BacktraceConfiguration } from '@backtrace/react'; import { BacktraceSessionReplayModule } from '@backtrace/session-replay'; // Configure client options const options: BacktraceConfiguration = { name: 'MyWebPage', version: '1.2.3', url: 'https://submit.backtrace.io///json', }; // Initialize the client using the builder to add the session replay module const client = BacktraceClient.builder(options) .useModule( new BacktraceSessionReplayModule({ // Configuration for session replay goes here. maxEventCount: 100, privacy: { blockClass: 'do-not-send', }, sampling: { input: 'last', } }), ) .build(); // The client is now initialized with Session Replay enabled. // Any errors captured by the client or the ErrorBoundary will now include a session replay. ``` 当捕获出错时,将在调试器页面上为回溯跟踪UI中的特定出错提供会话重放的链接. * * * ### 应用稳定性计量 Backtrace React SDK具有发送使用量表的能力,可以在Backtrace UI中取景. [(标准计量特征文件)](https://docs.saucelabs.com/error-reporting/project-setup/stability-metrics/) #### 计量配置 | 选项名称 | 类型 | 说明 | 默认 | 需要吗? | | --- | --- | --- | --- | --- | | `metricsSubmissionUrl` | 字符串 | Metrics服务器主机名. 默认值设定为 [https://events.backtrace.io (英语)](https://events.backtrace.io/)。 。 。 . | `https://events.backtrace.io` | - \- \[ | | `enable` | 布尔 | 确定是否启用了参数支持。 默认情况下, 值会被设定为真 . | `true` | - \- \[ | | `autoSendInterval` | 数目 | 指示崩溃自由度量度被发送到 Backtrace 的频率 。 间隔是一个以ms为单位的值. 默认情况下,会话事件会在应用程序启动/完成时发送,在应用程序运行期间每30分钟发送一次. 如果值设定为 0 。 自动发送模式已禁用 。 在这种情况下,应用程序需要手动维护发送模式. | 应用程序启动/完成时 | - \- \[ | | `size` | 数目 | 表示在自动提交前, 计量存储可以存储多少个事件 . | `50` | - \- \[ | #### 计量使用量 ```ts // metrics will be undefined if not enabled client.metrics?.send(); ``` * * * ## 高级 SDK 特性 ### 回溯跟踪 后追Client是SDK的主要类. 当这个单通对象被即时化时, 开始监测错误, 它会 撰写和发送报告,说明未处理的错误和未处理的承诺拒绝。 也可以用来手动发送 例外和拒绝处理者的报告。 不创建此对象的一个以上实例 . #### 回溯跟踪选择 BacktraceClient 初始化后通过的选项如下 . | 选项名称 | 类型 | 说明 | 默认 | 需要吗? | | --- | --- | --- | --- | --- | | `url` | 字符串 | 将错误发送到的提交 URL | | - \- \[x\] | | `name` | 字符串 | 您的申请名称 | | - \- \[x\] | | `version` | 字符串 | 您的应用程序版本 | | - \- \[x\] | | `token` | 字符串 | 错误的提交符 。 只有在直接提交回溯跟踪 URL 时才需要这样做 。 (不常见) | | - \- \[ | | `userAttributes` | 词典 | 在 Backtrace UI 中可以被过滤并相加的附加属性. | | - \- \[ | | `attachments` | 回溯跟踪连接 \[\] | 附加文件将随错误报告一起发送 。 见 [文件附件](https://npmcn.com/package/%40backtrace/react/#readme-file-attachments) | | - \- \[ | | `beforeSend` | (数据:回溯追踪数据) 后跟踪 Data QQ 未定义 | 每次在管理环境中发生例外时触发一个事件,这使得您可以跳过报告(通过返回一个无效值)或者修改库在发送报告前收集的数据. 您可以使用"先发送"事件来扩展属性或基于应用程序在例外时拥有的数据的JSON对象数据. 见 [修改/skip 错误报告](https://npmcn.com/package/%40backtrace/react/#readme-modifyskip-error-reports)(中文(简体) ) | | - \- \[ | | `skipReport` | (报告:回溯追踪报告) | 如果您想要忽略特定类型的错误报告, 我们建议您使用跳过报告调用 。 通过使用它,根据报告生成的数据,可以决定过滤报告,或者发送到回溯追踪. | | - \- \[ | | `captureUnhandledErrors` | 布尔 | 启用未处理错误 | `true` | - \- \[ | | `captureUnhandledPromiseRejections` | 布尔 | 启用未处理的承诺拒绝 | `true` | - \- \[ | | `timeout` | 整数 | 要等多久才能确定连接时间 | `15000` | - \- \[ | | `ignoreSslCertificate` | 布尔 | 忽略 SSL 证书出错 | `false` | - \- \[ | | `rateLimit` | 整数 | 限制客户端每分钟发送的报告数量 。 如果设定为"0",则没有限制. 如果设定为大于"0"的值并达到值,客户端直到下一分钟才会发送任何报告. | `0` | - \- \[ | | `metrics` | 回溯跟踪量表选项 | 见 [回溯跟踪稳定度量](https://npmcn.com/package/%40backtrace/react/#readme-application-stability-metrics) | | - \- \[ | | `breadcrumbs` | 后跟踪 Breadcrumbs 设置 | 见 [后跟踪面包屑](https://npmcn.com/package/%40backtrace/react/#readme-breadcrumbs) | | - \- \[ | ### 手动发送错误 将错误发送到 Backtrace 有几种方法 。 关于定义的更详细情况 `client.send()` 见 [方法](https://npmcn.com/package/%40backtrace/react/#readme-methods) 见下文. ```ts // send as a string await client.send('This is a string!'); // send as an Error await client.send(new Error('This is an Error!')); // as a BacktraceReport (string) await client.send(new BacktraceReport('This is a report with a string!')); // as a BacktraceReport (Error) await client.send(new BacktraceReport(new Error('This is a report with a string!'))); ``` ### 修改/skip 错误报告 当管理环境中出现例外,您可以附加一个处理器时,会触发发送前的事件. 您可以使用“ 发送前” 事件来擦除 PII, 或者根据您的应用程序的数据扩展属性或 JSON 对象数据 在例外时有。 报告可以通过返回一个无效值被完全跳过 . ```ts const client = BacktraceClient.initialize({ url: SUBMISSION_URL, name: '@backtrace/react-example', version: '0.0.1', beforeSend: (data: BacktraceData) => { // skip the report by returning a null from the callback if (!shouldSendReportToBacktrace(data)) { return undefined; } // apply custom attribute data.attributes['new-attribute"] = 'apply-data-in-callback'; return data; }, }); ``` ### SDK 方法覆盖 BacktraceClient. buildinger 用于推翻默认的 BacktraceClient 方法. 文件与 http 操作覆盖 例如,可用于在休息或运动中执行数据自定义加密. > 不使用这些操作来修改数据对象。 见 [修改/skip 错误报告](https://npmcn.com/package/%40backtrace/react/#readme-modifyskip-error-reports) 页:1 用于修改报告然后将其发送到 Backtrace 的正确方法. ```ts const client = BacktraceClient.builder(options) .useRequestHandler(requestHandler) .useBreadcrumbSubscriber(breadcrumbSubscriber) .addAttributeProvider(attributeProvider) .build(); ``` ## 常见问题 ### @backtrace/react 是什么？ 回溯跟踪- Javascription 重现集成 ### 如何安装 @backtrace/react？ 在项目目录运行 npm install @backtrace/react，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=16\.8\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。 ### @backtrace/react 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @backtrace/react 支持 ESM 还是 CommonJS？ 同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。 ### @backtrace/react 可以商用吗？ @backtrace/react 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @backtrace/react 的下载量有多少？ 根据 npm 官方下载统计，@backtrace/react 在 2026/10/08 – 2026/11/06 这 30 天内被下载 5,769 次，日均约 192 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @backtrace/react 还在维护吗？ 最新版本 0\.5\.2 发布于 2026/10/30（9 天前）；至今共发布 8 个版本，其中过去 12 个月发布了 2 个；首次发布于 2023/10/30。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。