# @backtrace/node 中文文档 规范地址：https://npmcn.com/package/%40backtrace/node/ 版本：0\.8\.4 npm 元数据更新时间：2026-10-29T16:56:25.607Z 中文译文更新时间：2026-11-07T15:52:36.019Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40backtrace/node 原文对照：https://npmcn.com/package/%40backtrace/node/?lang=original 项目主页：https://github.com/backtrace-labs/backtrace-javascript#readme 源码仓库：https://github.com/backtrace-labs/backtrace-javascript ## 关键信息（来自 npm 元数据） - 包体积（解压后）：264 kB，42 个文件 - 模块格式：ESM + CJS - TypeScript 类型：包内自带 - Node.js 要求：\>=14 - 运行依赖：2 个 - 首次发布：2023-10-30T13:12:41.457Z - 最新版本发布：2026-10-29T16:56:24.937Z - 近 30 天下载量：6099（2026-10-08 至 2026-11-06，npm 官方下载统计） - 已发布版本数：19（近 12 个月 4 个） ## 中文简介 后追踪- JavaScript 节点. JS 集成 ## 安装 ```sh npm install @backtrace/node ``` 也可以使用：`pnpm add @backtrace/node`、`yarn add @backtrace/node`、`bun add @backtrace/node` ## README # **后追踪节点 SDK** [回溯跟踪](https://backtrace.io/) 在您的生产软件中抓取和处理的报告和未处理的例外 您可以通过完整的产品生命周期管理应用质量. 这个 [@ 回溯跟踪/节点](https://npmcn.com/package/%40backtrace/node/#) SDK将您的JavaScript应用程序连接到 Backtrace. 基本的整合是快速和容易的, 之后可以探索丰富的回溯追踪特征集. ## 目录 1. [基本整合 - 报告您的第一个错误](https://npmcn.com/package/%40backtrace/node/#readme-basic-integration) - [安装软件包](https://npmcn.com/package/%40backtrace/node/#readme-install-the-package) - [整合 SDK](https://npmcn.com/package/%40backtrace/node/#readme-integrate-the-sdk) - [上传源代码图](https://npmcn.com/package/%40backtrace/node/#readme-upload-source-maps) 2. [报告特性出错](https://npmcn.com/package/%40backtrace/node/#readme-error-reporting-features) - [属性](https://npmcn.com/package/%40backtrace/node/#readme-attributes) - [文件附件](https://npmcn.com/package/%40backtrace/node/#readme-file-attachments) - [面包屑](https://npmcn.com/package/%40backtrace/node/#readme-breadcrumbs) - [应用稳定性计量](https://npmcn.com/package/%40backtrace/node/#readme-application-stability-metrics) - [计量配置](https://npmcn.com/package/%40backtrace/node/#readme-metrics-configuration) - [计量使用量](https://npmcn.com/package/%40backtrace/node/#readme-metrics-usage) - [离线数据库支持](https://npmcn.com/package/%40backtrace/node/#readme-offline-database-support) - [数据库配置](https://npmcn.com/package/%40backtrace/node/#readme-database-configuration) - [本地崩溃支持](https://npmcn.com/package/%40backtrace/node/#readme-native-crash-support) - [手工数据库操作](https://npmcn.com/package/%40backtrace/node/#readme-manual-database-operations) 3. [高级 SDK 特性](https://npmcn.com/package/%40backtrace/node/#readme-advanced-sdk-features) - [回溯跟踪快捷选项](https://npmcn.com/package/%40backtrace/node/#readme-backtraceclient) - [手动发送错误](https://npmcn.com/package/%40backtrace/node/#readme-manually-send-an-error) - [修改/skip 错误报告](https://npmcn.com/package/%40backtrace/node/#readme-modifyskip-error-reports) - [SDK 方法覆盖](https://npmcn.com/package/%40backtrace/node/#readme-sdk-method-overrides) ## 基本融合 ### 安装软件包 ``` $ npm install @backtrace/node ``` ### 整合 SDK 在所有其他脚本之前将以下代码添加到您的应用程序中,向 Backtrace 报告节点错误 . ```ts // Import the BacktraceClient from @backtrace/node with your favorite package manager. import { BacktraceClient, BacktraceConfiguration } from '@backtrace/node'; // Configure client options const options: BacktraceConfiguration = { // 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!')); ``` ### 上传源代码图 客户端错误报告基于已修改的代码. 上传源代码和源代码以解析已修改的代码 您的原始源标识符. [(原始内容存档于2018-10-21) (原始内容存档于2017-09-21)](https://docs.saucelabs.com/error-reporting/platform-integrations/source-map/) ## 报告特性出错 ### 属性 自定义属性是可以添加到您错误报告中的密钥值对. 它们被用于报告汇总, 对错误进行排序和过滤,可以提供更好的背景数据,而且可以提供更多的数据。 它们是许多 高级回溯跟踪特性,详见 [报告文档](https://docs.saucelabs.com/error-reporting/getting-started/)。默认属性 作为应用程序名称和版本,自动基于您的软件包.json信息。 如果回溯跟踪不能 找到它们,您需要通过用户属性手动提供它们 . 有几个地方可以添加,修改或删除属性. #### 将属性对象附加到 BacktraceClient 可以在 [回溯跟踪](https://npmcn.com/package/%40backtrace/node/#readme-backtraceclient) 初始化。 本列表 属性将包含在每个错误报告,称为全局属性. ```ts // Create an attributes object that can be modified throughout runtime const attributes: Record = { release: 'PROD', }; // BacktraceClientOptions const options: BacktraceConfiguration = { 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 = { url: 'https://submit.backtrace.io///json', // Attach the attributes object userAttributes: () => ({ attribute: getAttributeValue(), }), }; // 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/node import { BacktraceStringAttachment, BacktraceUint8ArrayAttachment, BacktraceFileAttachment } from "@backtrace/node"; // BacktraceStringAttachment should be used for text object like a log file, for example const stringAttachment = new BacktraceStringAttachment("logfile.txt", "This is the start of my log") // Buffer attachment is an attachment type dedicated to store buffer data const bufferAttachment = new BacktraceBufferAttachment('buffer-attachment.txt', Buffer.from('sample')); // File attachment is an attachment type dedicated for streaming files const fileAttachment = new BacktraceFileAttachment('/path/to/sample/file'); // BacktraceClientOptions const options = { url: "https://submit.backtrace.io///json", // Attach the files to all reports attachments: [path.join('/path/to/attachment'), stringAttachment], } const client = BacktraceClient.initialize(options); // Later decide to add an attachment to all reports client.addAttachment(bufferAttachment) // After catching an exception and generating a report try { throw new Error("Caught exception!") } catch (error) { const report = const report = new BacktraceReport(error, {}, [fileAttachment]) 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/node'; // BacktraceClientOptions const options: BacktraceConfiguration = { // ignoring all but breadcrumbs config for simplicity breadcrumbs: { // breadcrumbs configuration }, }; // Initialize the client const client = BacktraceClient.initialize(options); ``` #### 默认面包屑 | 类型 | 说明 | | --- | --- | | 控制台 | 每次开发者使用控制台日志时都会添加面包屑. | #### 拦截面包屑 如果PII或其他信息需要从面包屑中过滤,您可以使用截取功能来跳过或过滤 清除敏感信息。 任何RawBreadcrumb返回的会用于面包crumb. 如果返回未定义,则无 将添加面包屑. #### 手动面包屑 除了所有自动收集的默认面包屑外,您还可以手动添加面包屑: 属于你自己的. ```ts client.breadcrumbs?.info('This is a manual breadcrumb.', { customAttr: 'wow!', }); ``` * * * ### 应用稳定性计量 Backtrace节点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(); ``` * * * ### 离线数据库支持 Backtrace节点SDK可以在发送到Backtrace之前缓存生成的报告并崩溃到本地磁盘. 这是 建议;在某些配置中,节点应用程序可在SDK完成提交数据之前崩溃,并在 网络条件缓慢 您的应用程序可能会在关闭窗口中等待 HTTP 提交完成 。 在这样的情况下 下一次应用程序启动时会发送事件缓存报告. 通过离线数据库支持,您可以: - 在用户没有互联网连接或服务无法提供时缓存您的报告, - 捕捉坠机, - 手动决定是否发送报告,以及何时发送. 离线数据库支持默认已禁用 。 要启用它, 请添加“ enable: true ” 和目录的路径 回溯跟踪可以存储崩溃数据. ```ts const client = BacktraceClient.initialize({ // ignoring all but database config for simplicity database: { enable: true, path: '/path/to/the/database/directory', captureNativeCrashes: true, }, }); // manually send and keep the data on connection issue client.database.send(); // manually send and remove all data no matter if received success or not. client.database.flush(); ``` #### 数据库配置 | 选项名称 | 类型 | 说明 | 默认 | 需要吗? | | --- | --- | --- | --- | --- | | `enabled` | 布尔 | 启用/ 禁用离线数据库支持 . | 虚假 | - \- \[x\] | | `path` | 字符串 | 崩溃数据本地存储路径 . | \- 说吧 | - \- \[x\] | | `createDatabaseDirectory` | 布尔 | 允许 SDK 创建离线数据库目录 . | 真实 | | | `autoSend` | 布尔 | 根据重试设置向服务器发送报告 。 如果该值被设定为"假",您可以使用Flush或Send 方法作为替代. | 真实 | | | `maximumNumberOfRecords` | 数目 | 离线数据库中存储报告的最大数量 。 达到限制后,删除最老的报告. 如果值等于"0",则不设定限制. | 第8条 | | | `retryInterval` | 数目 | 如果数据库无法发送报告, 需要等待的时间( ms) . | 60 000人 | | | `maximumRetries` | 数目 | 如果数据库无法发送报告, 请尝试的重试次数 . | 3个 | | | `captureNativeCrashes` | 布尔 | 如果运行时间支持的话, 抓取并标记本地崩溃的堆栈痕迹 。 生成崩溃报告, 在本地存储, 并在下次启动时上传 . | 虚假 | | #### 本地崩溃支持 Backtrace节点SDK可以捕捉由Assert/OOM相撞等节点应用程序所生成的本土相撞. 顺序 为了收集它们,SDK使用节点 `process.report` API (英语). 设置本地崩溃支持后, 您 `process.report` 设置可能被覆盖, 您的崩溃数据可能在数据库目录中创建 . 下次会议发送的数据库记录可能没有关于崩溃会话的一些信息,例如属性或 面包屑. 为了缩小数据库记录的大小,附件支持仅限于文件附件. #### 手工数据库操作 BacktraceDatabase对象的客户端选项中可提供数据库支持. 你可以用手动的 操作数据库记录. ## 高级 SDK 特性 ### 回溯跟踪 后追Client是SDK的主要类. 当这个单通对象被即时化时, 开始监测错误, 它会 撰写和发送报告,说明未处理的错误和未处理的承诺拒绝。 也可以用来手动发送 例外和拒绝处理者的报告。 不创建此对象的一个以上实例 . #### 回溯跟踪选择 BacktraceClient 初始化后通过的选项如下 . | 选项名称 | 类型 | 说明 | 默认 | 需要吗? | | --- | --- | --- | --- | --- | | `url` | 字符串 | 将错误发送到的提交 URL | | - \- \[x\] | | `token` | 字符串 | 错误的提交符 。 只有在直接提交回溯跟踪 URL 时才需要这样做 。 (不常见) | | - \- \[ | | `userAttributes` | 词典 | 在 Backtrace UI 中可以被过滤并相加的附加属性. | | - \- \[ | | `attachments` | 回溯跟踪连接 \[\] | 附加文件将随错误报告一起发送 。 见 [文件附件](https://npmcn.com/package/%40backtrace/node/#readme-file-attachments) | | - \- \[ | | `beforeSend` | (数据:回溯追踪数据) 后跟踪 Data QQ 未定义 | 每次在管理环境中发生例外时触发一个事件,这使得您可以跳过报告(通过返回一个无效值)或者修改库在发送报告前收集的数据. 您可以使用"先发送"事件来扩展属性或基于应用程序在例外时拥有的数据的JSON对象数据. 见 [修改/skip 错误报告](https://npmcn.com/package/%40backtrace/node/#readme-modifyskip-error-reports)(中文(简体) ) | | - \- \[ | | `skipReport` | (报告:回溯追踪报告) | 如果您想要忽略特定类型的错误报告, 我们建议您使用跳过报告调用 。 通过使用它,根据报告生成的数据,可以决定过滤报告,或者发送到回溯追踪. | | - \- \[ | | `captureUnhandledErrors` | 布尔 | 启用未处理错误 | `true` | - \- \[ | | `captureUnhandledPromiseRejections` | 布尔 | 启用未处理的承诺拒绝 | `true` | - \- \[ | | `timeout` | 整数 | 要等多久才能确定连接时间 | `15000` | - \- \[ | | `ignoreSslCertificate` | 布尔 | 忽略 SSL 证书出错 | `false` | - \- \[ | | `rateLimit` | 整数 | 限制客户端每分钟发送的报告数量 。 如果设定为"0",则没有限制. 如果设定为大于"0"的值并达到值,客户端直到下一分钟才会发送任何报告. | `0` | - \- \[ | | `metrics` | 回溯跟踪量表选项 | 见 [回溯跟踪稳定度量](https://npmcn.com/package/%40backtrace/node/#readme-application-stability-metrics) | | - \- \[ | | `breadcrumbs` | 后跟踪 Breadcrumbs 设置 | 见 [后跟踪面包屑](https://npmcn.com/package/%40backtrace/node/#readme-breadcrumbs) | | - \- \[ | | `database` | 回溯跟踪数据库设置 | 见 [回溯跟踪数据库](https://npmcn.com/package/%40backtrace/node/#readme-offline-database-support) | | - \- \[ | ### 手动发送错误 将错误发送到 Backtrace 有几种方法 。 关于定义的更详细情况 `client.send()` 见 [方法](https://npmcn.com/package/%40backtrace/node/#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, 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/node/#readme-modifyskip-error-reports) 页:1 用于修改报告然后将其发送到 Backtrace 的正确方法. ```ts const client = BacktraceClient.builder(options) .useRequestHandler(requestHandler) .useBreadcrumbSubscriber(breadcrumbSubscriber) .addAttributeProvider(attributeProvider) .build(); ``` ## 常见问题 ### @backtrace/node 是什么？ 后追踪- JavaScript 节点\. JS 集成 ### 如何安装 @backtrace/node？ 在项目目录运行 npm install @backtrace/node，或使用 pnpm add / yarn add / bun add。 ### @backtrace/node 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @backtrace/node 支持 ESM 还是 CommonJS？ 同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。 ### @backtrace/node 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=14。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @backtrace/node 可以商用吗？ @backtrace/node 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @backtrace/node 的下载量有多少？ 根据 npm 官方下载统计，@backtrace/node 在 2026/10/08 – 2026/11/06 这 30 天内被下载 6,099 次，日均约 203 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @backtrace/node 还在维护吗？ 最新版本 0\.8\.4 发布于 2026/10/30（9 天前）；至今共发布 19 个版本，其中过去 12 个月发布了 4 个；首次发布于 2023/10/30。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。