# @hawk\.so/nodejs 中文文档

规范地址：https://npmcn.com/package/%40hawk.so/nodejs/

版本：3\.3\.2
npm 元数据更新时间：2026-02-11T17:36:16.865Z
中文译文更新时间：2026-11-17T13:56:18.852Z
软件包许可：AGPL-3\.0-only

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

原始 npm 页面：https://www.npmjs.com/package/%40hawk.so/nodejs
原文对照：https://npmcn.com/package/%40hawk.so/nodejs/?lang=original
源码仓库：https://github.com/codex-team/hawk.nodejs

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

- 包体积（解压后）：154 kB，78 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：24\.x
- 运行依赖：3 个
- 首次发布：2020-06-09T09:29:28.760Z
- 最新版本发布：2026-02-11T17:36:16.686Z
- 近 30 天下载量：5829（2026-10-18 至 2026-11-16，npm 官方下载统计）
- 已发布版本数：32（近 12 个月 4 个）

## 中文简介

霍克的节点捕手

## 安装

```sh
npm install @hawk.so/nodejs
```

也可以使用：`pnpm add @hawk.so/nodejs`、`yarn add @hawk.so/nodejs`、`bun add @hawk.so/nodejs`

## README

# @hawk.so/nodejs (韩语)

节点.js 出错 [鹰](https://hawk.so/)

## 初始参数

初始化参数 :

| 名称 | 类型 | 所需经费 | 说明 |
| --- | --- | --- | --- |
| `token` | 字符串 | **所需经费** | 您的项目的整合 Token |
| `release` | 字符串 | 选项 | 发行时唯一的标识符. |
| `context` | 对象 | 选项 | 您想要随每个消息传递的任何数据 . |
| `disableGlobalErrorsHandling` | 布尔 | 选项 | 不初始化全局错误处理 |
| `beforeSend` | 函数( 事件) qq事件 qq 虚空 | 选项 | 发送前过滤数据 。 返回已修改的事件, `false` 放弃活动. |
| `breadcrumbs` | `false` 或对象 | 选项 | 过 `false` 以禁用。 要配置的通过选项对象(参见 [面包屑](https://npmcn.com/package/%40hawk.so/nodejs/#readme-breadcrumbs)。默认:已启用. |

## 使用量

1.  [创建](https://hawk.so/) 一个账户,并获得一个整合托肯.
2.  添加 [@hawk.so/nodejs (韩语)](https://www.npmjs.com/package/@hawk.so/nodejs) 软件包.
3.  `Require` 并初始化模块.

### 安装

使用国家防范机制或 Yarn 安装 Catcher `@hawk.so/nodejs`。 。 。 .

```bash
$ npm install @hawk.so/nodejs --save
```

```bash
$ yarn add @hawk.so/nodejs
```

### 需要 HawkCatcher 模块

#### 通用JS项目

```js
const HawkCatcher = require('@hawk.so/nodejs').default;
```

#### 无害环境管理项目

```js
import HawkCatcher from '@hawk.so/nodejs';
```

### 鹰卡捷

在您的工程条目文件中初始化 HawkCatcher, 方法是通过一个工程符号 .

```js
const HAWK_TOKEN = 'eyJhb...VPsc=';

HawkCatcher.init(HAWK_TOKEN);
```

HawkCatcher 添加听众 `uncaughtException` 财务报告和审定财务报表 `unhandledRejection` 自己来.

#### 禁用全局错误处理

如果您不想初始化全局例外处理器, 请使用 `disableGlobalErrorsHandling` 一、导 言.

```js
HawkCatcher.init({
  token: HAWK_TOKEN,
  disableGlobalErrorsHandling: true,
});
```

然后,你可以手动抓住事件.

### 全球背景

您可以定义要抓取的所有事件的全局背景 .

```js
HawkCatcher.init({
  token: HAWK_TOKEN,
  context: {
    myOwnDebugInfo: '1234'
  }
});
```

### 释放

要标记事件到特定释放 通过 `release` 标识符字符串为 intial 配置.

```js
HawkCatcher.init({
  token: 'INTEGRATION TOKEN',
  release: process.env.releaseId
})
```

### 人工捕获例外

之后 [初始化](https://npmcn.com/package/%40hawk.so/nodejs/init-hawkcatcher) 您可以在任何工程的试捕构造中手动捕获例外.

刚刚 [需要 HawkCatcher 软件](https://npmcn.com/package/%40hawk.so/nodejs/#readme-require-hawkcatcher-module) 打电话 `.send()` 方法.

```js
try {
  throw new Error('My lovely error');
} catch (e) {
  HawkCatcher.send(e);
}
```

如果HawkCatcher没有初始化的话 `.send()` 方法不会做什么.

#### 事件背景

您可以通过任何信息作为单个活动的上下文参数.

```js
try {
  throw new Error('User not found');
} catch (e) {
  HawkCatcher.send(e, {
    myOwnDebugInfo: '1234'
  });
}
```

如果存在此上下文对象, 则会与全局上下文合并 .

#### 用户

您可以将用户数据作为第三段发送.

可用字段 :

| 参数 | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| 编号 | `string|number` | 所需经费 | 用户标识符 |
| 名称 | `string` | \- 说吧 | 用户名 |
| url 密码 | `string` | \- 说吧 | 用户配置文件 URL |
| 图像 | `string` | \- 说吧 | 用户配置文件 pic URL |

```js
try {
  throw new Error('Cannot create a new post');
} catch (e) {
  HawkCatcher.send(e, {}, {
    id: 1234,
    name: 'Taly'
});
}
```

### 面包屑

Breadcrumbs 跟踪事件导致出错,为调试提供上下文. 与 API 相同 [@hawk.so/javascript](https://www.npmjs.com/package/@hawk.so/javascript) (添加, get, clear); 在节点中没有自动跟踪取取/导航/点击,只有手动面包屑.

#### 默认配置

默认情况下,面包屑是启用的(只有定制面包屑):

```js
HawkCatcher.init({
  token: 'INTEGRATION_TOKEN'
  // breadcrumbs enabled by default
});
```

#### 残废面包屑

完全禁用面包屑:

```js
HawkCatcher.init({
  token: 'INTEGRATION_TOKEN',
  breadcrumbs: false
});
```

#### 自定义配置

配置面包屑(酌情与联署材料相同):

```js
HawkCatcher.init({
  token: 'INTEGRATION_TOKEN',
  breadcrumbs: {
    maxBreadcrumbs: 20,
    beforeBreadcrumb: (breadcrumb, hint) => {
      if (breadcrumb.category === 'auth' && breadcrumb.data?.userId) {
        return false; // Discard
      }
      return breadcrumb;
    }
  }
});
```

#### 面包屑选项

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `maxBreadcrumbs` | `number` | `15` | 要储存的面包屑最多。 达到限值后取出最古老的面包屑(FIFO). |
| `beforeBreadcrumb` | `function` | `undefined` | 胡克在每块面包屑被储存之前就打电话了 接收 `(breadcrumb, hint)`返回经过修改的面包屑来保存它, `false` 丢弃. |

#### 手工面包屑

手动添加自定义面包屑. Breadcrumbs 累积在缓冲器中,并附着在每起事件上,直到通过 `HawkCatcher.breadcrumbs.clear()`数字 :

```js
HawkCatcher.breadcrumbs.add({
  type: 'logic',
  category: 'auth',
  message: 'User logged in',
  level: 'info',
  data: { userId: '123' }
});
```

#### 面包屑方法

与联署材料的捕捉者相同:

```js
// Add a breadcrumb
HawkCatcher.breadcrumbs.add(breadcrumb, hint);

// Get current breadcrumbs
const breadcrumbs = HawkCatcher.breadcrumbs.get();

// Clear all breadcrumbs
HawkCatcher.breadcrumbs.clear();
```

### 敏感数据过滤

使用 `beforeSend()` 在发送到 Hawk 之前, 勾通过滤数据 .

-   **返回已修改的事件** ——将发送修改后的事件
-   **返回时 `false`** ——事件将完全放弃
-   **任何其它值无效** ——原事件按正时发送(已登录警告)

```js
HawkCatcher.init({
  token: 'INTEGRATION TOKEN',
  beforeSend(event) {
    // Strip sensitive user data
    if (event.user && event.user.name) {
      delete event.user.name;
    }

    return event;
  }
});
```

完全丢弃一个事件 :

```js
HawkCatcher.init({
  token: 'INTEGRATION TOKEN',
  beforeSend(event) {
    if (event.title.includes('ignore-me')) {
      return false;
    }

    return event;
  }
});
```

## 许可证

本项目根据以下规定获得许可证: **GNU 阿费罗通用公共许可证 v3.0 (AGPL-3**。 。 。 . 见 [自由主义](https://npmcn.com/package/%40hawk.so/nodejs/LICENSE) 完整文本的文档.

## 常见问题

### @hawk\.so/nodejs 是什么？

霍克的节点捕手

### 如何安装 @hawk\.so/nodejs？

在项目目录运行 npm install @hawk\.so/nodejs，或使用 pnpm add / yarn add / bun add。

### @hawk\.so/nodejs 支持 TypeScript 吗？

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

### @hawk\.so/nodejs 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @hawk\.so/nodejs 需要什么版本的 Node\.js？

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

### @hawk\.so/nodejs 可以商用吗？

@hawk\.so/nodejs 使用 AGPL-3\.0-only 许可。最严格的 Copyleft：除分发外，通过网络向用户提供基于它的服务也需要开源对应源码。闭源 SaaS 使用前务必评估。以上为概括，不构成法律意见，请以许可原文为准。

### @hawk\.so/nodejs 的下载量有多少？

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

### @hawk\.so/nodejs 还在维护吗？

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

