# @everframe/react 中文文档

规范地址：https://npmcn.com/package/%40everframe/react/

版本：1\.6\.7
npm 元数据更新时间：2026-10-28T20:33:38.748Z
中文译文更新时间：2026-11-14T05:13:03.751Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：1.6 MB，26 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：6 个
- peer 依赖：react ^18\.0\.0 \|\| ^19\.0\.0，react-dom ^18\.0\.0 \|\| ^19\.0\.0
- 首次发布：2026-09-25T06:58:01.592Z
- 最新版本发布：2026-10-28T20:33:37.477Z
- 近 30 天下载量：2298（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：15（近 12 个月 15 个）

## 中文简介

为 Everframe 反应 SDK —— AI- ready in-app bug 报告有截图,注释,会话回放,面包屑和崩溃抓取.

## 安装

```sh
npm install @everframe/react
```

也可以使用：`pnpm add @everframe/react`、`yarn add @everframe/react`、`bun add @everframe/react`

## README

# @ everfram/ 反应

反应 (web) SDK for Everframe——AI-ready bug reporting 嵌入到您的应用程序中.

麻省理工学院 · 反应 18 · 19 · 仅无害环境管理 · 节点 20+

## 安装

```bash
pnpm add @everframe/react
# or
npm install @everframe/react
```

可选但建议:安装 `displayName` 保存插件, 使组件名称能够幸存 :

```bash
# Babel users (Webpack / CRA / Next.js with Babel config)
pnpm add -D @everframe/babel-plugin-displayname

# SWC users (Next.js default since 12+)
pnpm add -D @everframe/swc-plugin-displayname
```

## 快速启动

把你的应用程序包起来一次 提供商会挂起浮出气泡,登记出热键,拥有记者模式生命周期.

```tsx
// app/layout.tsx (Next.js app router)
import { EverframeProvider } from '@everframe/react';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        <EverframeProvider config={{ sdkKey: 'evf_live_xxxxxxxxxxxxxxxx' }}>
          {children}
        </EverframeProvider>
      </body>
    </html>
  );
}
```

从任何地方按程序打开记者 :

```tsx
'use client';
import { useEverframe } from '@everframe/react';

export function HelpButton() {
  const { open } = useEverframe();
  return <button onClick={open}>Report a bug</button>;
}
```

## 报告发现的例外情况

使用 `useEverframe().captureException(error)` 内部组件,或顶层 在捕获块或错误边界中导出 :

```tsx
import { captureException } from '@everframe/react';

try {
  await saveCart();
} catch (error) {
  captureException(error);
}
```

报告被标记为处理和不致命,并使用现有的编辑、用户 上下文,面包屑,和送货箱。 调用返回 `void`没有 打开用户界面,不确认服务器收到。 顶级导出为 没有挂载的提供商,则不开放. `kill()`, (中文(简体) ), `disabled`,以及 `crashReporting.disabled` 也压制捕捉.

配置 `appVersion` 财务报告和审定财务报表 `appBuild` 由提供者识别释放 和部署的建筑。 该建筑被存储为 `context.app.build` 错误和 用户备案的报告; 尚未提供自动源图处理.

相同的错误对象 被捕获一次 每个SDK实例 通过钩,顶级, 和自动处理器。 第一个被接受的捕捉决定了分类. 明确和自动捕捉,每个指纹可报告1起,10起 每个 SDK 实例, 独立 。 运输检讨保留报告编号.

## 无边界捕获出错

当组件在渲染时、效果或生命周期方法中投掷时 且内部没有出错边界 `EverframeProvider` 抓住它,回击卸载 整棵树 提供商报告错误为致命的崩溃(`source: 'crash'`, (中文(简体) ), `fatal: true`,机制 `onerror`),带有 React 组件堆栈 信件后( 3)`This error is located at:`) (中文(简体) ). 不需要错误边界 . 报告在发送前保存到发件箱,所以失败的发件出局 在下一页负载上.

提供者然后对同样的错误不作改动: 您的错误边界 {\\fn华文楷体\\fs16\\1cHE0E0E0}否则反应会报告给 页面中,SDK识别到并且不再报告。 错误 a 提供者渔获量不自动报告;呼叫 `captureException` 从那个边界 `componentDidCatch`,与反应 组件堆栈, 因此错误页显示它发生在 : `captureException(error, { componentStack: info.componentStack })`。反应 开发构建报告失败的实现或效果 `window.onerror` 在此之前 任何边界都能看到,所以在开发中,这种误差可以作为非致命的 错误,而不是或者包括致命报告.

`tests/render-error-browser.mjs` 在Chrimium中检查此内容与真实反应 建立:

```sh
node tests/render-error-browser.mjs /tmp/render-error-proof
node tests/render-error-browser.mjs /tmp/render-error-proof-18 --react-root <dir with react@18 installed>
```

## 触发器

默认 SDK 安装 :

-   **应用程序的仪表盘配置的热键**,默认为 `Cmd/Ctrl+Shift+B` (单位:千美元)`Mod+Shift+B`) (中文(简体) ). 仪表板值具有权威性;没有SDK侧面 超过.

`Mod` 决定: `Cmd` 关于macOS和 `Ctrl` 别的地方.

一个可见的触发器(bulble,菜单项等)是主机应用程序的责任——呼叫 `useEverframe().open()` 从你自己的按钮 提出记者.

要报告崩溃和出错而不让用户提交报告, 设置 `reporter: { disabled: true }` 在提供者配置中。 那届会议没有 热键,没有回复按钮或收件箱,以及 `open()` 拒绝方式 `EverframeReporterDisabledError`。会话重放时只使用应用程序的崩溃 采样率(默认为0)和网络机构保持不动. 见 [只崩溃的会话](https://npmcn.com/package/docs/session-replay.md#crash-only-sessions)。 。 。 .

### 三星和LG电视机

在三星Tizen或LG WebOS电视上,提供商设置了设备连接和 远程捕捉手势相同 `@everframe/web` 已经 过 `debugBuild: true` 用于调试构建和 `quickCapture: { disabled: true }` 改为 关掉 见 [三星和LG电视的快取](https://npmcn.com/package/%40everframe/sdk-web/README.md#quick-capture-on-samsung-and-lg-tvs)。 。 。 .

## 严格的CSP环境

如果您的应用程序设置了严格的 CSP( Q)`script-src 'self' 'nonce-...'`),将非ce线入SDK,所以截图抓取的动态注入样式被接受:

```tsx
// Next.js: read the nonce from headers() in your layout
import { headers } from 'next/headers';

export default async function RootLayout({ children }: { children: React.ReactNode }) {
  const nonce = (await headers()).get('x-nonce') ?? '';
  return (
    <EverframeProvider config={{ sdkKey: 'evf_live_xxxxxxxxxxxxxxxx', cspNonce: nonce }}>
      {children}
    </EverframeProvider>
  );
}
```

## 标记敏感内容(PRIV-02)

3个等同的表面——选择符合你编码的任意:

```tsx
import { Sensitive, useEverframe } from '@everframe/react';
import { useEffect, useRef } from 'react';

// 1. Component wrapper
<Sensitive><CreditCardNumber /></Sensitive>

// 2. data-attribute (works on any DOM element)
<div data-everframe-sensitive>{value}</div>

// 3. Ref hook
function MyField({ value }: { value: string }) {
  const ref = useRef<HTMLDivElement>(null);
  const { markSensitive } = useEverframe();
  useEffect(() => {
    if (ref.current) markSensitive(ref);
  }, [markSensitive]);
  return <div ref={ref}>{value}</div>;
}
```

三个解析到相同的内部敏感-rect注册;这些矩形下方的像素在截图字节离开设备之前的捕捉时间被空白.

## 捆绑笔记

SDK只使用无害环境管理。 一些 Next.js + monrepo 设置需要切换工作空间包:

```ts
// next.config.ts
transpilePackages: ['@everframe/react', '@everframe/sdk-core', '@everframe/protocol'],
```

总是装入量~136 KB gzip(`pnpm size-limit`,预算240KB). 沉重的捕捉和注释依赖性——rrweb,反应-konva,和现代屏幕shot——是懒惰的输入,不在此数;它们只有在记者实际打开时才加载.

## 示例

见 [`examples/react-web/`](https://github.com/scriptx-com/everframe/tree/main/examples/react-web) 用于一个Next.js的狗粮项目,涵盖严格的CSP固定和标准的SSD固定.

## 常见问题

### @everframe/react 是什么？

为 Everframe 反应 SDK —— AI- ready in-app bug 报告有截图,注释,会话回放,面包屑和崩溃抓取\.

### 如何安装 @everframe/react？

在项目目录运行 npm install @everframe/react，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^18\.0\.0 \|\| ^19\.0\.0）、react-dom（^18\.0\.0 \|\| ^19\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @everframe/react 支持 TypeScript 吗？

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

### @everframe/react 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @everframe/react 需要什么版本的 Node\.js？

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

### @everframe/react 可以商用吗？

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

### @everframe/react 的下载量有多少？

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

### @everframe/react 还在维护吗？

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