# @bugfender/sdk 中文文档

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

版本：4\.0\.1
npm 元数据更新时间：2026-07-23T14:45:45.381Z
中文译文更新时间：2026-11-08T18:35:36.830Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：4 MB，162 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：8 个
- 首次发布：2020-03-31T11:17:19.288Z
- 最新版本发布：2026-07-23T14:45:45.133Z
- 近 30 天下载量：23232（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：41（近 12 个月 4 个）

## 中文简介

用于网络的 Bugfender SDK, 为应用程序定制的远程日志

## 安装

```sh
npm install @bugfender/sdk
```

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

## README

# 臭虫网络 SDK

Bugfender是一个改变游戏的平台,它记录了用户经历的每一个细节,并将数据直接输入一个易于使用的网页控制台. Bugfender SDK是多平台的并可供移动和网络应用,因此可以对所有的应用程序使用同一种工具.

此 Bugfender SDK 是用于前端工程的, 以 **Java 脚本** 或者说 **类型脚本**。 。 。 .

## 目录

1.  [应用程序样本](https://npmcn.com/package/%40bugfender/sdk/#readme-sample-apps)
2.  [安装](https://npmcn.com/package/%40bugfender/sdk/#readme-installation)
    -   [国家预防机制](https://npmcn.com/package/%40bugfender/sdk/#readme-npm)
    -   [浏览器](https://npmcn.com/package/%40bugfender/sdk/#readme-browser)
3.  [使用量](https://npmcn.com/package/%40bugfender/sdk/#readme-usage)
4.  [高级使用](https://npmcn.com/package/%40bugfender/sdk/#readme-advanced-usage)
5.  [内容安全政策](https://npmcn.com/package/%40bugfender/sdk/#readme-content-security-policy)
6.  [更改日志](https://npmcn.com/package/%40bugfender/sdk/#readme-changelog)
    -   [2.x 中断更改](https://npmcn.com/package/%40bugfender/sdk/#readme-2x-breaking-changes)
7.  [其他 SDKs 软件](https://npmcn.com/package/%40bugfender/sdk/#readme-other-sdks)

## 应用程序样本

我们创建了两个可以用作参考的样本应用程序:

-   如果你计划使用 Bugfender SDK 在一个 **香草JavaScript应用程序**访问 [https://github.com/bugfender/ BugfenderSDK-JS-样板](https://github.com/bugfender/BugfenderSDK-JS-Sample)
-   如果你计划使用 Bugfender SDK 在一个 **角应用**访问 [https://github.com/bugfender/ BugfenderSDK-Angular-Sample 互联网档案馆的存檔,存档日期2013-12-22](https://github.com/bugfender/BugfenderSDK-Angular-Sample)
-   如果你计划使用 Bugfender SDK 在一个 **反应应用程序**访问 [https://github.com/bugfender/BugfenderSDK-React-Sample 互联网档案馆的存檔,存档日期2013-12-22](https://github.com/bugfender/BugfenderSDK-React-Sample)
-   如果你计划使用 Bugfender SDK 在一个 **Vue.js 应用程序**访问 [https://github.com/bugfender/ BugfenderSDK-Vue-Sample 互联网档案馆的存檔,存档日期2013-12-22](https://github.com/bugfender/BugfenderSDK-Vue-Sample)

## 安装

Bugfender被设计为在浏览器和Node.js开发环境中同时工作(仅用于前端).

### 国家预防机制

以下是让Bugfender在您的应用程序上工作的要点:

-   获取应用程序密钥 [bugfender.com (英语)](https://bugfender.com/)
-   安装 SDK 国家预防机制软件包 :

```bash
npm install @bugfender/sdk
```

然后,你可以进入和使用SDK:

```typescript
// Import Bugfender
import { Bugfender } from '@bugfender/sdk';

// Initialize. `appKey` is the only required option.
Bugfender.init({
    appKey: '<YOUR_APP_KEY_HERE>',
    // apiURL: 'https://api.bugfender.com',
    // baseURL: 'https://dashboard.bugfender.com',
    // overrideConsoleMethods: true,
    // printToConsole: true,
    // registerErrorHandler: true,
    // logBrowserEvents: true,
    // logUIEvents: true,
    // version: '',
    // build: '',
});

// Bugfender now can be used
Bugfender.log('Hello world!');
```

记住要改变 `<YOUR_APP_KEY_HERE>` 与您的应用程序的应用密钥。 对于所有可用的选项 [见我们的参考文献](https://js.bugfender.com/interfaces/isdkoptions.html)。 。 。 .

#### 类型脚本

如果您正在使用 TypeScript 拼写一个应用程序, Bugfender 包括 TypeScript 定义文件 .

### 浏览器

如果您计划在您的 HTML/JS 网页上直接使用 SDK, 您可以按照这些步骤导入 SDK :

-   获取应用程序密钥 [bugfender.com (英语)](https://bugfender.com/)
-   导入 Bugfender SDK JavaScript 文件
-   输入和使用您的脚本

```html
<script defer src="https://js.bugfender.com/bugfender-v2.js"></script>
<script defer src="your-script.js"></script>
```

> 请注意,为了遵守装载命令 `script` 标记必须有 `defer` 属性而非 `async`如果 `async` 使用时, 命令不能被保证, 因此您的应用程序中可能存在 Bugfender 无法捕获的日志错误( M) .

```javascript
// your-script.js
// Bugfender will be registered in `window`
// Initialize. `appKey` is the only required option.
Bugfender.init({
    appKey: '<YOUR_APP_KEY_HERE>',
});

// Bugfender now can be used
Bugfender.log('Hello world!');
```

记住要改变 `<YOUR_APP_KEY_HERE>` 与您的应用程序的应用密钥。 对于所有可用的选项 [见我们的参考文献](https://js.bugfender.com/interfaces/isdkoptions.html)。 。 。 .

## 使用量

在您初始化了 SDK 之后, 您才能开始使用它 。 完整的API 参考访问 URL : [https://js.bugfender.com (中文(简体) )](https://js.bugfender.com/)。 。 。 .

### 发送日志

SDK提供了向服务器发送日志的下列方法:

-   `Bugfender.trace()`
-   `Bugfender.info()`
-   `Bugfender.log()`
-   `Bugfender.warn()`
-   `Bugfender.error()`
-   `Bugfender.fatal()`

这些方法的签名与 `window.console` 等价单位.

### 隐藏 `console` 日志

可能你可能想得到所有你的应用日志 在你的日志查看器, 做到这一点,当你 `init` 您可以启用控制台控制器 。 对于这个,有 `overrideConsoleMethods` 选项可以启用/启用。 默认 SDK 会抓取 `window.console` 打电话.

### 禁用 UI 事件记录

Bugfender 默认记录一些 UI 事件 。 这包括:点击、字段聚焦/blur、有结果值的字段按键(不包括 `password` 并提交材料。 要禁用此行为集 `logUIEvents` 选项到 `false` 关于 Bugfender 初始化.

#### 忽略敏感字段的密钥压值

已经响起 **忽略密码字段** 从按键压记录, 但如果您需要忽略敏感字段, 您可以使用 `data-bf-ignore-keypress` 属性。 请注意,这可以适用于单个字段或一组字段. 如果您要禁用整个页面的此行为, 请将属性添加到 `html` 或者说 `body` 键.

```html
<!-- Ignore a single field -->
<input placeholder="Sensitive field…" data-bf-ignore-keypress>

<!-- Ignore a group of fields. Note that all children of `form` are ignored. -->
<form data-bf-ignore-keypress>
    <input placeholder="Superhero name">
    <input placeholder="Superhero HQ address">
</form>

<!-- Ignore on all the fields -->
<body data-bf-ignore-keypress>
    ...
</body>
```

> 注意被忽略的是字段的价值. 密钥发布事件仍将注册 .

### 网络记录 (Web SDK)

网络请求抓取默认被禁用 。 初始化后,您可以启用它并配置细节级别 :

```typescript
Bugfender.setNetworkLoggingEnabled(true);

// Optional: full mode (captures request/response bodies)
Bugfender.setNetworkLoggingCaptureBodies(true);

// Optional: URL filters (substring or wildcard, e.g. https://*.example.com/*)
Bugfender.setNetworkLoggingURLFilter(
    ['api.example.com'], // allowlist
    ['api.example.com/private'] // denylist
);

// Optional: request cap per calendar minute (null = no limit; values <= 0 treated as null)
Bugfender.setNetworkLoggingMaxRequestsPerMinute(60);
```

启用时, 网络事件将作为日志发送 `bf_network`。 。 。 .

## 高级使用

### 发送问题

Bugfender 允许您向服务器发送问题 。 一个问题与一个会话类似,但这些问题部分会显示,即使设备在系统中没有被启用,您也可以随时从应用程序发送问题. 问题对于跟踪您可以在代码中发现的重要错误很有用.

发送问题时,您可以使用以下函数:

```typescript
Bugfender.sendIssue('Issue title', 'Description of the issue');
```

### 发送带有标签的日志

Bugfender有一个更先进的记录系统 `console.log()` ,并允许您在日志中添加标记,添加标记将允许您在 Bugfender 日志查看器中轻松查找并过滤日志.

```typescript
Bugfender.sendLog({ tag: 'tag1', text: 'this is my log' });
```

### 使用 `LogLevel` 语句

你访问的方式 `LogLevel` enum取决于你如何消耗 Bugfender SDK.

国家防范机制一揽子计划,ES6 `import`数字 :

```typescript
import { LogLevel } from '@bugfender/sdk';
```

国家防范机制一揽子计划,共同JS `require`数字 :

```js
const LogLevel = require('@bugfender/sdk').LogLevel;
```

浏览器 `<script>` 标签 :

```js
Bugfender.LogLevel
```

### 设备相关数据

您可以将信息连接到设备上, 就象一个字典:

```typescript
Bugfender.setDeviceKey('key', 'value');
Bugfender.removeDeviceKey('key');
```

您可以在博客上找到更多信息 [相关设备信息](https://bugfender.com/blog/associated-device-information/)。 。 。 .

### 收集用户反馈

Bugfender可以收集用户反馈. 用户反馈类似于会话,但会在"用户反馈"部分显示. 您可以随时从应用程序中发送它们, 即使设备没有启用 .

```typescript
Bugfender.sendUserFeedback('Love the App!', 'You are doing a great job with it.')
```

### 用户反馈模式

![](https://npmcn.com/package/%40bugfender/sdk/media/bf-user-feedback-modal.jpg)

你可以打电话 `getUserFeedback()` 打开反馈模式。 这种方法接受允许自定义模式字符串的选项对象。 我们还提供CSS变量来定制样式(见下文).

```typescript
Bugfender.getUserFeedback().then((result) => {
    if (result.isSent) {
        // User sent the feedback
        // `result.feedbackURL` contains the Bugfender feedback URL
    } else {
        // User closed the modal without sending the feedback
    }
});
```

CSS 变量 :

```css
--bf-backdrop-bg: rgba(0, 0, 0, .5);
--bf-border-radius: 4px;
--bf-color: #222;
--bf-font-heading: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";
--bf-font: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";
--bf-input-border: 1px solid #ccc;
--bf-modal-shadow: 0px 4px 12px 0px rgba(0, 0, 0, 0.25);
--bf-placeholder-color: #757575;
--bf-submit-bg: #ff5060;
--bf-submit-color: #fff;
--bf-submit-shadow: 0 2px 0 0 #a93e48;
--bf-z-index: 9999;
```

### 手动发送崩溃

您也可以手动发送崩溃信息 。 通常您不想要使用此选项, 启用自动崩溃报告, 而使用 `registerErrorHandler` 选项。 这将迫使当前会话中的所有日志发送, 即使日志发送被禁用 .

```typescript
Bugfender.sendCrash('Crash Title', `Ops, the app crashed, better check what's wrong.`);
```

### API 参考

整个API 参考文献: [https://js.bugfender.com (中文(简体) )](https://js.bugfender.com/)。 。 。 .

## 内容安全政策

如果您已经启用了 CSP, 您需要获得以下资源 :

-   `api.bugfender.com`:为"虫"API.
-   `js.bugfender.com`: 用于浏览器 `<script>`。 。 。 .

如果你选择了国家防范机制的安装,你只需要允许访问API:

```text
Content-Security-Policy: default-src api.bugfender.com;
```

否则,如果你已经通过浏览器安装了 Bugfender `<script>` aPI和JS图书馆:

```text
Content-Security-Policy: default-src api.bugfender.com js.bugfender.com;
```

有关如何配置 CSP 的更多信息请访问 [参考 MDN 文档](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP)。 。 。 .

## 更改日志

Bugfender Web SDK 的更改日志可见于 [释放注释 `js` 标签](https://bugfender.releasenotes.io/tag/js)。请访问 [普通发布注释](https://bugfender.releasenotes.io/)。 。 。 .

### 2.x 中断更改

Web SDK API 稍作修改,以兼容 [臭虫反应原生 SDK](https://www.npmjs.com/package/@bugfender/rn-bugfender)。 。 。 . **注意升级为 2.x 之前的以下断裂变化 :**

-   下面的方法是同步和返回a `Promise`数字 :
    -   `getDeviceURL`
    -   `getSessionURL`
    -   `sendIssue`
    -   `sendCrash`
    -   `sendUserFeedback`
-   Markdown已经贬值:
    -   `sendIssueMarkdown`: 方法 **删除**启用 `sendIssue` 换句话说.
    -   `sendIssue` 打开 `sendCrash`: 不包装 `text` 在Markdown代码 块回击.

## 其他 SDKs 软件

其他平台也提供bugfender:

-   iOS: (英语) [https://github.com/bugfender/ BugfenderSDK-iOS 页面存档备份,存于互联网档案馆](https://github.com/bugfender/BugfenderSDK-iOS)
-   机器人: [https://github.com/bugfender/ BugfenderSDK-android-sample 互联网档案馆的存檔,存档日期2013-12-22](https://github.com/bugfender/BugfenderSDK-android-sample)

学习更多 [臭虫师](https://bugfender.com/)。 。 。 .

## 常见问题

### @bugfender/sdk 是什么？

用于网络的 Bugfender SDK, 为应用程序定制的远程日志

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

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

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

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

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

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

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

@bugfender/sdk 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

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

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

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

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