# @flareapp/js 中文文档

规范地址：https://npmcn.com/package/%40flareapp/js/

版本：2\.13\.0
npm 元数据更新时间：2026-09-17T12:50:03.062Z
中文译文更新时间：2026-11-14T21:27:49.459Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：221 kB，15 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2024-01-24T16:50:26.663Z
- 最新版本发布：2026-09-17T12:50:02.842Z
- 近 30 天下载量：60809（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：31（近 12 个月 21 个）

## 中文简介

用于 shipapp.io 的 JavaScript 客户端

## 安装

```sh
npm install @flareapp/js
```

也可以使用：`pnpm add @flareapp/js`、`yarn add @flareapp/js`、`bun add @flareapp/js`

## README

# @flareapp/js (英语)

JavaScript/ TypeScript 核心客户端 [火焰](https://flareapp.io/) 错误跟踪和记录 。 抓取前端 错误, 剖析堆栈跟踪, 收集浏览器上下文, 发送结构化日志, 并向 Flare 报告所有信息 后端 .

## 安装

```bash
npm install @flareapp/js
```

## 快开始

```js
import { flare } from '@flareapp/js';

flare.light('YOUR_FLARE_API_KEY');
```

这就是你所需要的。 客户会自动聆听未发现的例外 和未处理的承诺拒绝, 收集浏览器上下文,并向 Flare 发送错误报告.

## 识别用户

将登录用户附加到报表中, 这样您就可以看到谁受到影响 :

```javascript
import { flare } from '@flareapp/js';

flare.setUser({
    id: 123,
    email: 'jane@example.com',
    fullName: 'Jane Doe',
});
```

公认领域: `id` (-) `user.id`, (中文(简体) ), `email` (-) `user.email`, (中文(简体) ), `fullName` (-) `user.full_name`, (中文(简体) ), `ipAddress` (-) `client.address`) (中文(简体) ). 任何额外的密钥都收集到下面 `user.attributes`。通过 `null` 在登录时清除用户 : `flare.setUser(null)`。 。 。 .

## Cookie 同意书和 GDPR

客户端可以运行在同意工具后. 当同意解除时,它不会发出什么。 在征得同意之前,它甚至不汇编报告.

开关是一种方法:

```javascript
flare.setConsent(true); // allow sending
flare.setConsent(false); // stop sending, and drop anything captured earlier
```

建议流量:不调用 `flare.light(key)` 直到获得同意。 没有钥匙,什么也没有发出, 所以这涵盖了你同意代码运行的那一刻。 使用 `setConsent` 用于退出和重新授予,因为一旦设置了密钥,它是唯一干净的关闭开关.

```javascript
import { flare } from '@flareapp/js';

// Cookiebot example. OneTrust exposes OptanonWrapper; the idea is the same.
window.addEventListener('CookiebotOnAccept', () => {
    flare.light('your-project-key'); // first grant: start the client
    flare.setConsent(true); // and allow sending
});

window.addEventListener('CookiebotOnDecline', () => {
    flare.setConsent(false); // withdrawal: stop all sends, drop buffers
});
```

如果您将密钥设定在后端, 而不是等待, 请从同意开始, 然后在用户接受时打开 :

```javascript
import { flare } from '@flareapp/js';

flare.configure({ hasConsent: false }); // start off, before anything can send
flare.light('your-project-key');

window.addEventListener('CookiebotOnAccept', () => flare.setConsent(true));
window.addEventListener('CookiebotOnDecline', () => flare.setConsent(false));
```

打开 `configure({ hasConsent: false })` 首先,在导入之后,所以在早期未发现的错误可以组装报告之前,门就关闭了.

因此,没有同意工具的设置保持不变. `setConsent(false)` 停止数据离开浏览器。 它不删除 `fetch` 财务报告和审定财务报表 `XHR` 补丁 追踪和面包屑 安装, 因为这些只读 在记忆中, 从来没有自己发送。 要取出这些,打电话 `flare.configure({ enableTracing: false, enableBreadcrumbs: false })`。 。 。 .

## 日志

除了出错,客户端还可以发送结构化日志. 日志是选入的: 启用这些日志 `enableLogs`,然后调用其中的任何 八个 syslog 级别 (`debug`, (中文(简体) ), `info`, (中文(简体) ), `notice`, (中文(简体) ), `warning`, (中文(简体) ), `error`, (中文(简体) ), `critical`, (中文(简体) ), `alert`, (中文(简体) ), `emergency`) (中文(简体) ).

```js
flare.configure({ enableLogs: true });

flare.logger.info('Checkout started', { cartId: cart.id, total: cart.total });
```

日志是缓冲和分批的,当标签被隐藏时会被冲出,所以缓冲的日志可以在一个页面卸载后幸存. 可选 第二个参数是结构化的,可搜索的属性.

## 当有人离开时会发生什么

日志和横幅被分批分出,所以通常有访客离开时不在场. 客户冲它的时候 标签被隐藏或页面关闭.

浏览器将您当时可以发送的封顶: 大约64KB覆盖每个仍在飞行中的请求. 客人留下来 在60KB以下, 和日志和跨度分担预算.

切换标签是安全的。 隐藏标签触发同样的冲浪, 任何不合适的东西,当访客出去 回来.

如无相合,则批发仍为正常请求,而并非恒取. 这通常着陆,但 如果页面关闭, 可以取消 .

你只会在访问者离开前 达到许多遥测的极限 少记录这些 页面而不是提高限制.

## 文档

关于配置、钩子、上下文、面包屑、解决方案提供商的完整文档,以及更多 时间 [耀斑/docs/javascript/一般/安装](https://flareapp.io/docs/javascript/general/installation)。 。 。 .

## 折旧

> `redactFullPath` 现在是一个被贬值的化名 `redactUrlQuery`。两个名称 仍在出口并继续工作 `redactUrlQuery` 在新代码.

## 许可证

麻省理工学院许可证(MIT). 请看 [许可证文件](https://npmcn.com/package/LICENSE.md) 更多信息.

## 常见问题

### @flareapp/js 是什么？

用于 shipapp\.io 的 JavaScript 客户端

### 如何安装 @flareapp/js？

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

### @flareapp/js 支持 TypeScript 吗？

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

### @flareapp/js 支持 ESM 还是 CommonJS？

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

### @flareapp/js 可以商用吗？

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

### @flareapp/js 的下载量有多少？

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

### @flareapp/js 还在维护吗？

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