@bugfender/sdk

中文文档

4.0.1发布于 2026/07/23Apache-2.0TypeScriptCommonJS近 30 天下载 2.3万

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

文档目录23 节

目录
应用程序样本
安装
国家预防机制
浏览器
使用量
发送日志
隐藏 console 日志
禁用 UI 事件记录
网络记录 (Web SDK)
高级使用
发送问题
发送带有标签的日志
使用 LogLevel 语句
设备相关数据
收集用户反馈
用户反馈模式
手动发送崩溃
API 参考
内容安全政策
更改日志
2.x 中断更改
其他 SDKs 软件

臭虫网络 SDK

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

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

应用程序样本

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

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

安装

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

国家预防机制

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

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

npm install @bugfender/sdk

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

// 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> 与您的应用程序的应用密钥。对于所有可用的选项见我们的参考文献。。。 .

类型脚本

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

浏览器

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

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

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

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

// 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> 与您的应用程序的应用密钥。对于所有可用的选项见我们的参考文献。。。 .

使用量

在您初始化了 SDK 之后, 您才能开始使用它。完整的API 参考访问 URL : 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 键.

<!-- 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)

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

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

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

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

发送带有标签的日志

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

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

使用 `LogLevel` 语句

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

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

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

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

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

浏览器 <script> 标签 :

Bugfender.LogLevel

设备相关数据

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

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

您可以在博客上找到更多信息相关设备信息。。。 .

收集用户反馈

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

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

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

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 变量 :

--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 选项。这将迫使当前会话中的所有日志发送, 即使日志发送被禁用 .

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

API 参考

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

内容安全政策

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

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

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

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

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

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

有关如何配置 CSP 的更多信息请访问参考 MDN 文档。。。 .

更改日志

Bugfender Web SDK 的更改日志可见于释放注释 js 标签。请访问普通发布注释。。。 .

2.x 中断更改

Web SDK API 稍作修改,以兼容臭虫反应原生 SDK。。。 . 注意升级为 2.x 之前的以下断裂变化 :

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

其他 SDKs 软件

其他平台也提供bugfender:

学习更多臭虫师。。。 .

版本与发布记录

@bugfender/sdk 共发布 41 个版本，首次发布于 2020/03/31；过去 12 个月发布了 4 个版本。

版本	发布日期	距今
`4.0.1`latest	2026/07/23	3 个月前
`4.0.0`	2026/04/28	6 个月前
`3.1.0`	2026/01/19	9 个月前
`3.0.0`	2026/01/16	9 个月前
`2.4.0`	2025/11/07	1 年前
`2.3.0`	2024/05/14	2 年前

其他发布通道：alpha → 2.0.0-alpha.0。

关于 @bugfender/sdk 的常见问题

@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 和提交记录判断。