# @github/failbot 中文文档

规范地址：https://npmcn.com/package/%40github/failbot/

版本：1\.1\.1
npm 元数据更新时间：2026-10-15T16:20:41.686Z
中文译文更新时间：2026-11-16T11:01:25.498Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40github/failbot
原文对照：https://npmcn.com/package/%40github/failbot/?lang=original
项目主页：https://github.com/github/failbot-js#readme
源码仓库：https://github.com/github/failbot-js

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

- 包体积（解压后）：63.1 kB，39 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>= 22\.x
- 运行依赖：1 个
- 首次发布：2021-10-20T17:02:31.369Z
- 最新版本发布：2026-08-06T10:59:09.881Z
- 近 30 天下载量：44855（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：7（近 12 个月 1 个）

## 中文简介

JavaScript 的 Faullbot 客户端

## 安装

```sh
npm install @github/failbot
```

也可以使用：`pnpm add @github/failbot`、`yarn add @github/failbot`、`bun add @github/failbot`

## README

# 失败者联署材料

A 类 [失败者](https://github.com/github/failbotg) javaScript 的客户端 .

## 安装

此软件包作为 npm 发布 `@github/failbot`。 。 。 .

```shell
❯ npm install @github/failbot
```

## 用法 :

```javascript
const {Failbot, HTTPBackend, LogBackend} = require('@github/failbot')

const failbot = new Failbot({
  app: 'my-cool-app',
  backends: [new HTTPBackend({haystackURL: process.env.HAYSTACK_URL}), new LogBackend({log: console.log.bind(console)})]
})

try {
  riskyThing()
} catch (error) {
  failbot.report(error, {
    extra: 'metadata',
    can: 'be',
    passed: 'as well'
  })
}
```

## 提交报告

`Failbot.report(error, metadata?, options?)` 返回每个已配置后端的一个承诺。 报告是默认的最佳努力,因此交付失败决心 `undefined`。配置和有效载荷准备错误,包括编辑错误,同步抛出.

设定 `rejectOnError` 用后端发送错误拒绝 :

```javascript
await Promise.all(failbot.report(error, metadata, {rejectOnError: true}))
```

`HTTPBackend` 将获取出错,超时,以及非-2xx响应视为交付失败. 默认5秒后请求超时 。 设定 `timeoutMs` 以配置超时 :

```javascript
const backend = new HTTPBackend({
  haystackURL: process.env.HAYSTACK_URL,
  timeoutMs: 1_000
})
```

## 例外有效载荷

HTTP和日志报告包括一个具体运行时间的平台(`"node"` 在节点.js和 `"javascript"` 和结构化 `exception_detail` 默认。 来自V8/Node/Chrome和Firefox/Safari的堆放框架已恢复正常,以便Failbog的调用者第一顺序。 遗产 `class`, (中文(简体) ), `message`字符串 `backtrace` 字段也用于兼容性.

消费者可以推翻默认 `platform` 财务报告和审定财务报表 `exception_detail` 通过元数据传递到 `report`。该格式继续拥有遗留错误字段、时间戳和JavaScript环境.

生成结构化例外字段编辑了Failbog全局上下文过滤器覆盖的已知证书模式,包括 URL 基本- 自动证书, cookie 值, 敏感的密钥值对等, 以及 GitHub 令牌 。 这种过滤有意保留了其他例外内容,如电子邮件地址和标识符. 提供打电话者 `exception_detail` 数值默认是逐字保存的,而遗留字段保留其已存在的值.

应用程序所有者负责将特定服务的敏感数据保留在例外情况之外。 配置 a `redact` 当应用程序处理默认证书模式无法识别的值时,函数:

```javascript
const failbot = new Failbot({
  app: 'my-cool-app',
  backends: [new HTTPBackend({haystackURL: process.env.HAYSTACK_URL})],
  redact(value) {
    return value.replace(/service-specific-sensitive-pattern/g, '[app redacted]')
  }
})
```

内建过滤运行于生成的结构化细节上. 然后,自定义功能运行在运出的有效载荷中每个JSON可序列化字符串上,包括生成和调用人提供的结构化细节、遗留字段和元数据。 它不适用于 `sensitive_context`。将其用于 GitHub 调用的额外格式 [安全例外处理指导](https://thehub.github.com/epd/engineering/dev-practicals/observability/exception-tracking/secure-exceptions/),例如授权和HMAC头,JWT,服务证书,以及特定应用程序的序列数据. 函数必须总是返回字符串,并且不能丢出。 添加应用程序编辑规则的测试,并在一个规则匹配时记录一个参数或安全日志条目,这样基础例外可以被固定.

自定义后端执行接收所配置的函数为第三个参数 `report` 在传输例外数据之前必须应用它。 捆绑的 HTTP 和日志后端自动做到这一点.

例外元数据应使用已登记 [语义公约](https://gh.io/gh-classifications)。Splunk 中必须具备但不能到达哨兵的数据可以放置在 Failbog 中 `sensitive_context` 对象 :

```javascript
failbot.report(error, {
  context: {'gh.example.repository.id': repositoryId},
  sensitive_context: {'gh.example.repository.path': repositoryPath}
})
```

仅使用 `sensitive_context` 当需要保留该值时。 认证数据和其他受限制的内容在报告之前必须删除,而不是通过上述两种方式发送.

为了将报告的例外情况归于服务目录服务 `catalog_service` 标记包括在通过此库报告的所有例外中。 由于所有的摩达部署 `OTEL_SERVICE_NAME` 环境变量, `catalog_service` 被作为 `OTEL_SERVICE_NAME`。 。 。 .

您不需要覆盖此值, 但是, 如果您需要, 您可以通过 `catalogService` 页:1 `Failbot` 构造器 : `const failbot = new Failbot({app: 'my-app', catalogService: 'my-catalog', backends: ...})`。请注意,压倒一切的这一值可能使你的团队无法收到与大量例外情况有关的警报.

## 常见问题

### @github/failbot 是什么？

JavaScript 的 Faullbot 客户端

### 如何安装 @github/failbot？

在项目目录运行 npm install @github/failbot，或使用 pnpm add / yarn add / bun add。

### @github/failbot 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @github/failbot 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @github/failbot 需要什么版本的 Node\.js？

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

### @github/failbot 可以商用吗？

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

### @github/failbot 的下载量有多少？

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

### @github/failbot 还在维护吗？

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

