# @bigbertha/sdk 中文文档

规范地址：https://npmcn.com/package/%40bigbertha/sdk/

版本：0\.13\.1
npm 元数据更新时间：2026-11-06T14:58:57.870Z
中文译文更新时间：2026-11-08T01:52:39.843Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40bigbertha/sdk
原文对照：https://npmcn.com/package/%40bigbertha/sdk/?lang=original
项目主页：https://github.com/felixowens/bertha/tree/main/sdk#readme
源码仓库：https://github.com/felixowens/bertha

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：136 kB，67 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=20
- 运行依赖：0 个
- peer 依赖：react \>=17
- 首次发布：2026-10-18T09:48:19.945Z
- 最新版本发布：2026-11-06T14:58:57.473Z
- 近 30 天下载量：5645（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：46（近 12 个月 46 个）

## 中文简介

为 Bertha 报告出错:浏览器,React,节点,边缘和Next.js,通过调试id提供源地图.

## 安装

```sh
npm install @bigbertha/sdk
```

也可以使用：`pnpm add @bigbertha/sdk`、`yarn add @bigbertha/sdk`、`bun add @bigbertha/sdk`

## README

# @bigbertha/ sdk (英语)

Bertha 报告错误 。 浏览器、 React、 节点、 边缘和 Next.js, 没有依赖性 和源地图相匹配的调试 id 而不是文件路径.

-   浏览器中大约7.8 kB gzipt ()`npm run size` 执行预算).
-   当BERTHA说起时,会退后,然后把排成一行的东西寄出去 过程消失.
-   默认情况下会擦除邮件,无记名符号和隐形查询值.
-   每一件事件都说它是怎样浮出水面的(一个未发现的错误,一个拒绝,一个边界,一个召唤), 将页面的要求与 w3C 导致的服务器错误 `traceparent`。 。 。 .
-   与 OpenTeleometry 有关的工作 : `otlp()` 在 Bertha 点出 OTel 导出者, 内部错误 将活动跨度记录在其上,浏览器将它的页面请求作为跨度发送 一旦页面出现错误。 见 [追踪](https://npmcn.com/package/%40bigbertha/sdk/#readme-traces)。 。 。 .
-   除了请求的跨度外, 发送日志行, 记录所发生的不是错误 。 见 [日志](https://npmcn.com/package/%40bigbertha/sdk/#readme-logs)。 。 。 .
-   构建插件给每个捆绑一个调试ID,上传其地图并删除 `.map` 文件,所以地图从不传送到浏览器.

每个项目在Bertha的设置页面显示其运行时间的确切片段,以及它的 键填入。 这个文件更详细地涵盖了同一个领域.

## 安装

```bash
npm install @bigbertha/sdk
```

每个版本还附在其GitHub发行中,作为 `bigbertha-sdk-<version>.tgz`。 。 。 . 自己造一个: `npm ci && npm run build && npm pack` 在此文件夹中.

## 密钥

每个项目有两个:

-   **无效密钥** (单位:千美元)`BERTHA_KEY`:发送事件. 它运送浏览器,所以它是公开的;a 被泄露的密钥只能发送事件,最多每秒50起.
-   **上传密钥** (单位:千美元)`BERTHA_UPLOAD_KEY`:上传源地图和记录部署. 留着吧 仅限CI机密.

`bertha project keys <name>` 在服务器上同时打印。 旋转摄入键入 工程设置立即停止旧的设置 .

## 下一个.js

```bash
# .env.local and your host
NEXT_PUBLIC_BERTHA_KEY="…"
NEXT_PUBLIC_BERTHA_URL="https://bertha.example.com"
BERTHA_UPLOAD_KEY="…"   # CI only
```

```ts
// instrumentation.ts: server and edge errors, including onRequestError
export { register, onRequestError } from "@bigbertha/sdk/next"

// instrumentation-client.ts: browser errors and navigation breadcrumbs
export { onRouterTransitionStart } from "@bigbertha/sdk/next/client"

// next.config.ts: stamps the release, uploads maps after `next build`
import { withBertha } from "@bigbertha/sdk/next/config"
export default withBertha({ /* your config */ })
```

`withBertha` 选项: `release`, (中文(简体) ), `keepMaps`, (中文(简体) ), `disableUpload`, (中文(简体) ), `recordDeploy`。它删除下面的地图 `.next/static` (浏览器可以获取) 并保留服务器的,没有服务 而Vercel的构建输出需要的. `keepMaps` 带 `true`, (中文(简体) ), `false` 函数 内部路径 `.next`。它也给环境留下了印记,所以 Vercel 预览报告 以中场出击 在Vercel上,它记录了上传后的部署, 与Vercel的承诺sha, 消息和作者,所以发布页面知道什么出(`recordDeploy: false` 关掉它.

为了自己的选择( :`beforeSend`, (中文(简体) ), `tags`, (中文(简体) ), `sampleRate`),电话 `init` 从 `@bigbertha/sdk/browser` 内 `instrumentation-client.ts` 而不是导入 `next/client`,以及 `init` 从 `@bigbertha/sdk/node` 内 `register()`。构建插件 无论是哪种方式都一样,它都保留了调试IDs的另一个工具(例如哨兵的) 插件)已经给出了捆绑,因此两者可以并肩运行. 把它包进去 `withSentryConfig` 并设置哨兵 `sourcemaps.deleteSourcemapsAfterUpload: false`数字 : 哨兵的插件首先运行,它所删除的地图永远无法到达Bertha. 贝莎去除 之后被送去的.

## 维特 (浏览器)

```ts
// src/main.ts
import { init } from "@bigbertha/sdk/browser"
init({ key: import.meta.env.VITE_BERTHA_KEY, url: import.meta.env.VITE_BERTHA_URL })

// vite.config.ts
import { bertha } from "@bigbertha/sdk/vite"
export default defineConfig({ plugins: [bertha()] })
```

### 浏览器事件携带什么

-   **该页:** 它的 URL 作为事件的要求, 像任何 URL 一样被擦除 .
    
-   **它是如何浮出水面的:** `onerror` 或者说 `onunhandledrejection`也没有被应用程序抓住.
    
-   **页面状态 :** 视图和像素比例,在线,可见标签,页面是如何打开的 (导航、再装入、后/前、前),开关时间长短,是否 浏览器是自动的 (`navigator.webdriver`),裁判员、语言、时区和 连接类型, 当有一个版本时则使用 Next.js 版本 .
    
-   **访客的IP**bertha从请求中读取并全数储存. `sendIp: false` 关闭; 给定的 IP `setUser` 改为使用.
    
-   **面包屑:** ,从 后向缓存、 标签隐藏和显示、 路由变化、 点击、 获取和 XHR 具有地位和期限 `console.log`, (中文(简体) ), `info`, (中文(简体) ), `warn` 财务报告和审定财务报表 `error`关闭任何 与 `breadcrumbs: { console: false }` 诸如来.
    
-   **追踪编号**,每页负载1个. 同源取来和XHR请求载有 `traceparent` 带有它的头条,所以服务器错误 旁边的错误 。 对于另一个来源的API,请输入 `tracePropagationTargets` (URL 前缀或图案)并允许 `traceparent` cORS 中的标题:
    
    ```ts
    init({ key, url, tracePropagationTargets: ["https://api.example.com"] })
    ```
    
-   **页面请求的跨度:** 页面本身、文档载荷和每个获取 和XHR及其方法,被擦除的URL和状态. 他们等待的记忆(最后200) 只要一页出错就去bertha 只要它一直停留 打开,所以一个不会出错的页面不会发出任何错误. `spans: false` 关掉.
    

浏览器扩展和脚本中的框架Safari隐藏(`webkit-masked-url://`已经 所以bertha可以说 当一个错误可能不是你的.

插件打开隐藏的源图, 如果构建没有 。 只有上传时 `BERTHA_UPLOAD_KEY` 所以本地建筑离线 保存地图. 选项 : `release`, (中文(简体) ), `url`, (中文(简体) ), `uploadKey`, (中文(简体) ), `keepMaps`。 。 。 .

## 反应

```tsx
import { ErrorBoundary } from "@bigbertha/sdk/react"

<ErrorBoundary fallback={({ reset }) => <button onClick={reset}>Try again</button>}>
  <App />
</ErrorBoundary>
```

`ErrorBoundary` 报告它用 React 组件堆栈捕获到的东西,然后制作 `fallback`: 节点,或函数 `{ error, eventId, reset }`。还需要 `onError(error, componentStack, eventId)` 财务报告和审定财务报表 `tags`输入条目时添加 React 的 每个事件的版本。 反应是可选的对等依赖; SDK 中没有其他的 需要这个.

## 节点

```ts
import { init } from "@bigbertha/sdk/node"
init() // reads BERTHA_KEY, BERTHA_URL, BERTHA_RELEASE, BERTHA_COMMIT and NODE_ENV
```

`init` 报告未发现例外和未处理的拒绝,冲出,然后作为节点退出 将(`handlers: false` 关掉它。 每隔20分钟也会发出心跳 bertha能从"不跑"中分辨出"没有出错"(bertha)`heartbeat: false`) (中文(简体) ). 心跳名称 执行过程,从 `commit`, (中文(简体) ), `BERTHA_COMMIT` 或主机本身的变量 (赫鲁库的) `HEROKU_SLUG_COMMIT` 在、 Render 、 铁路、 Vercel 、 GitHub 上没有元数据 动作),所以发布即不 `bertha deploy` 记录了它的代码.

节点运行的代码不需要源地图: SDK 读取相邻的行 从磁盘中将您自己的文件框并随事件一起发送( r)`contextLines: false` 关掉它。 这也将 V8 的默认堆栈限制从 10 帧提高到 50, 所以 a 深层框架呼叫不隐藏你的代码。 你设定的限度是孤独的.

`wrapHandler(fn)` 报告一个请求处理者丢掉并重新扔出去的东西 请求: 其 URL 、 其信头( 从不 `authorization`, (中文(简体) ), `proxy-authorization`, (中文(简体) ), `cookie`, (中文(简体) ), `set-cookie` 或者说 `x-api-key`),第一个客户端IP `x-forwarded-for` 跳还是跳 套接字, 以及从一个接入的追踪 `traceparent`下一个 `onRequestError` 发送 同样的.

带有自己的错误中间软件的应用程序将框架的请求传递为 `req` 获得 同一请求、IP和追踪:

```ts
// Koa
app.on("error", (err, ctx) =>
  captureException(err, { req: ctx, status: err.status ?? 500, mechanism: { handler: "koa", handled: false } }),
)
// Express, after the routes
app.use((err, req, res, next) => {
  captureException(err, { req, status: 500, mechanism: { handler: "express", handled: false } })
  next(err)
})
```

`req` 取节点 `IncomingMessage`快递 `req`科亚的 `ctx` 或获取 `Request` (边入也. `mechanism` 说错误逃脱了应用程序自己的代码,所以bertha 不读它作为一个应用 捕获。 服务器事件也命名为主机( Heroku ) `DYNO`,否则主机名)和 节点和下个.js版本.

对于被捆绑的节点代码,请给出输出调试ID并上传其构建后的地图:

```bash
npx bertha sourcemaps upload dist
```

## 追踪

bertha在OTLP/HTTP上取取了OpenTeleometry的痕迹,所以一个错误的页面显示的是 整个请求都是通过你的服务完成的:时间在哪里,什么先失败 呼叫一个从未回答过的服务。 它持续一个小时 并保持一个 跟踪一次错误事件,它就命名了,所以只有错误停留的痕迹.

SDK不记录服务器横跨自身. 使用 OpenTeleometry 自己的仪器和 将出口者指向伯塔 `otlp()`,它给出了 URL 和密钥头 从 `BERTHA_KEY` 财务报告和审定财务报表 `BERTHA_URL` (或 `key` 财务报告和审定财务报表 `url`:

```ts
// Next.js: instrumentation.ts (npm install @vercel/otel)
import { OTLPHttpProtoTraceExporter, registerOTel } from "@vercel/otel"
import { otlp, register as bertha } from "@bigbertha/sdk/next"
export { onRequestError } from "@bigbertha/sdk/next"

export function register() {
  registerOTel({ serviceName: "shop", traceExporter: new OTLPHttpProtoTraceExporter(otlp()) })
  return bertha()
}
```

```ts
// Node: before anything else loads
// (npm install @opentelemetry/sdk-node @opentelemetry/auto-instrumentations-node @opentelemetry/exporter-trace-otlp-proto)
import { NodeSDK } from "@opentelemetry/sdk-node"
import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node"
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto"
import { init, otlp } from "@bigbertha/sdk/node"

new NodeSDK({ traceExporter: new OTLPTraceExporter(otlp()), instrumentations: [getNodeAutoInstrumentations()] }).start()
init()
```

任何其他OTLP出口商也在工作:发送到 `<url>/ingest/v1/traces` 与 `Authorization: Bearer <key>`作为原生或JSON.

随着OpenTeleometry的运行,每个事件都命名了活动时的跨度 所以Bertha会把错误放在那个范围内 一个跨度在另一个跟踪 比 请求的 `traceparent` 由 : 哨兵运行 OpenTeleometry 并带有自己的踪迹 iDs,它的跨度会切断发送请求的页面的错误. 没有它,事件仍然伴随着 从收到的追踪 `traceparent` 并降落在请求的最外侧.

## 日志

记录线是用来记录所发生的事情的,这不是错误:一个成功的倒计时,一个缓慢的 上游,一个完成的工作。 线路去项目的日志,而不是它的问题,并携带 正在运行的跟踪(在浏览器中,页的),所以一个请求的行位于它的横跨处.

```ts
import { log } from "@bigbertha/sdk/node"   // or /browser, /edge, /next, /next/client

log.warn("TikWM failed; used the fallback", { video: "7301", status: 502 })
log.info("Synced orders", { count: 41 })
log.error(err)   // a line, not an issue: use captureException for that
```

`log.debug`, (中文(简体) ), `info`, (中文(简体) ), `warn` 财务报告和审定财务报表 `error` 接收消息(或 `Error`)和可选 字段。 字段作为文本发送,对象作为JSON. 客户 `init()` 返回有 同样的方法 `client.log`。 。 。 .

在服务器上,将请求作为 `req` 因此,一条线 降落在它的跟踪, 道路 `captureException` 已经 运行在请求以外的跟踪上 `traceparent` (哨兵's)被传递过来, 没有OpenTeleometry,请求的追踪是 都在这里了. `trace` 设置一个直接.

```ts
log.info("Used the cached price", { product: 28 }, { req: ctx })   // Koa's ctx, Express's req, a Request
```

-   下行数 `logLevel` (单位:千美元)`"info"` 未发送. `"off"` 无.
-   关于被捕获错误的错误行带有事件编号 (单位:千美元)`bertha.event_id`),所以线链接到这个问题,以哪个为先.
-   与 `captureConsole: true`, (中文(简体) ), `console.debug`, (中文(简体) ), `log`, (中文(简体) ), `info`, (中文(简体) ), `warn` 财务报告和审定财务报表 `error` 为: 也作为行号发送。 浏览器控制台面包屑保持原样.
-   线路像事件一样被洗刷, 分批发送 最多100秒第一, 并随页面或进程消失而发送。 当超过1000时 在等待(贝塔要求等待,或下降), 年龄最大的被扔下,下一个被扔下 批次以一行开头,写上多少个.
-   一个太老取出日志的Bertha答404:SDK警告一次并停止发行.

## 边缘

```ts
import { init } from "@bigbertha/sdk/edge"
init({ key: env.BERTHA_KEY, url: env.BERTHA_URL })
```

## 手牵手

每个条目输出相同的功能:

```ts
captureException(err, { level: "warning", tags: { job: "nightly" }, fingerprint: ["nightly-import"] })
// An error's own fields (code, status…) are sent with it, each as JSON.
captureMessage("Payment provider slow", { level: "warning" })
addBreadcrumb({ category: "cart", message: "Added 2 items" })
setUser({ id: "u_42" })   // hashed on the server, never shown in full
setTag("tenant", "harbour")
await flush()
```

## 选项

| 选项 | 默认 |  |
| --- | --- | --- |
| `key`, (中文(简体) ), `url` | 从嵌入( 节点, 边缘) | 在浏览器中需要 . |
| `release` | 在构建时间印出 | 插件盖出它 `BERTHA_RELEASE`,CI的 承诺莎或 `git HEAD`。 。 。 . |
| `environment` | `BERTHA_ENVIRONMENT`, (中文(简体) ), `VERCEL_ENV` 或者说 `NODE_ENV` (节点、边缘; `withBertha` 用于浏览器的邮票),其他制作 | 自由文本被绘制成生产、中产或开发图. |
| `sampleRate` | `1` | 要发送的事件份额 . |
| `beforeSend` |  | 更改事件, 或返回 `null` 放弃它. |
| `scrub` | `true` | 编辑电子邮件、无记名符号和秘密查询值,并删除错误的自有字段并请求带有证书名称的信头(`password`, (中文(简体) ), `token`, (中文(简体) ), `apiKey`(......) (中文(简体) ). |
| `tags` |  | 每个事件都有标记. |
| `versions` |  | 每个事件的更多版本,例如 `{ name: version }`。 。 。 . |
| `sendIp` | `true` | 浏览器:存储访问者的IP. |
| `tracePropagationTargets` | 仅属于同一来源 | 浏览器: 请求获得一个 `traceparent`。 。 。 . |
| `spans` | `true` | 浏览器:将页面的请求记录为跨度,并在页面出错后发送. |
| `logLevel` | `"info"` | 要发送的最低级日志行 : `"debug"`, (中文(简体) ), `"info"`, (中文(简体) ), `"warning"`, (中文(简体) ), `"error"`, (中文(简体) ), `"fatal"` 或者说 `"off"`。 。 。 . |
| `captureConsole` | `false` | 发送控制台呼叫为日志行 . |
| `breadcrumbs` | 全部开始 | 浏览器 : `fetch`, (中文(简体) ), `xhr`, (中文(简体) ), `navigation`, (中文(简体) ), `click`, (中文(简体) ), `console`。 。 。 . |
| `debug` | `false` | 记录SDK做什么. |

## 部署

出局后从中情局记录每个部署:

```bash
npx bertha deploy --env production
```

它发送释放 和最后一个承诺的sha,消息和作者。 发行页面 然后显示部署 带来了什么 是什么之后安静。 第一次活动 未知的释放也创造了释放,bertha将其标记为仅见,没有部署. 当释放是一个充分的承诺sha, 贝特哈把它作为承诺.

## 测试事件

检查密钥到达Bertha时不打破任何东西:

```bash
npx @bigbertha/sdk test --url https://bertha.example.com --key <the project's key>
```

它发出一个错误,"伯特哈测试事件",标记 `test: true`在发展中,除非 `--env` 说不然. `BERTHA_URL` 财务报告和审定财务报表 `BERTHA_KEY` 工作代替旗帜.

## 发展

```bash
npm run check   # types
npm test        # unit tests
npm run size    # browser bundle budget
npm run e2e     # the real bertha binary and the example apps, end to end
```

`npm run e2e` 用途 `../server/target/debug/bertha`,或 `BERTHA_BIN`。 。 。 . `-- --next` 添加 下个例(J)`npm install` 内 `examples/next-app` (第一编).

## 有什么新情况

每个版本的更改都在 [变动情况](https://github.com/felixowens/bertha/blob/main/CHANGELOG.md)在"JavaScript SDK"栏下 升级时要做的事 SDK分享Bertha的版本,所以 释放无法改变其中的任何内容.

## 许可证

麻省理工学院. 见 [自由主义](https://npmcn.com/package/%40bigbertha/sdk/LICENSE)。 。 。 .

## 常见问题

### @bigbertha/sdk 是什么？

为 Bertha 报告出错:浏览器,React,节点,边缘和Next\.js,通过调试id提供源地图\.

### 如何安装 @bigbertha/sdk？

在项目目录运行 npm install @bigbertha/sdk，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 bertha，可以用 npx bertha 直接运行。

### @bigbertha/sdk 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/bigbertha\_\_sdk 是否存在。

### @bigbertha/sdk 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @bigbertha/sdk 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @bigbertha/sdk 可以商用吗？

@bigbertha/sdk 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @bigbertha/sdk 的下载量有多少？

根据 npm 官方下载统计，@bigbertha/sdk 在 2026/10/08 – 2026/11/06 这 30 天内被下载 5,645 次，日均约 188 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @bigbertha/sdk 还在维护吗？

最新版本 0\.13\.1 发布于 2026/11/06（1 天前）；至今共发布 46 个版本，其中过去 12 个月发布了 46 个；首次发布于 2026/10/18。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。