Next.js 和 React

安装 npm install @blipit/nextjs

@blipit/nextjs 只需在布局中放一个组件,就能提供浏览器错误、Web 指标、会话回放和“报告问题”按钮;在 instrumentation.ts 中加一行,即可捕获服务端组件、路由处理程序和 server action 的错误。普通 React 应用使用 @blipit/browser。

粘贴到 Claude Code、Cursor 或任何 AI 编程助手中。它包含步骤和代码。在 app.blipit.io 的“API 密钥”页面,同一提示词已填好你的密钥。
视频:在任何技术栈中安装 Blipit,从 0:32 开始

1安装

sh
npm install @blipit/nextjs

2获取密钥

登录 app.blipit.io,打开侧边栏中的“API 密钥”,然后选择你的项目。每个项目有两个密钥。公钥以 blipit_pk_ 开头:它用于浏览器和应用代码,只能发送事件,任何人看到都没关系。私密密钥以 blipit_sk_ 开头:它留在你的服务器或 Odoo 中,切勿放进浏览器,因为它还可以读取和更改问题。私密密钥只在创建后显示一次,请当时就复制;如果丢失,请点击“创建新的密钥”,旧密钥会立即失效。部分 SDK 还需要项目 id,它显示在同一页面上。

app.blipit.io 中的 API 密钥:公钥(blipit_pk_)用于浏览器代码,私密密钥(blipit_sk_)用于服务器和 Odoo。
app.blipit.io 中的 API 密钥:公钥(blipit_pk_)用于浏览器代码,私密密钥(blipit_sk_)用于服务器和 Odoo。
新的私密密钥只显示一次。请立即复制:它以哈希形式存储,无法再次显示。
新的私密密钥只显示一次。请立即复制:它以哈希形式存储,无法再次显示。

3把密钥放进 .env.local

在项目根目录创建 .env.local,写入供浏览器使用的公钥;如果你使用下面的服务端功能,还要写入供服务器使用的私密密钥。只有以 NEXT_PUBLIC_ 开头的名称会传到浏览器,所以切勿给私密密钥加这个前缀。保存文件后重启 npm run dev。对于生产环境,在你的托管平台中添加相同的变量(在 Vercel 上:Project、Settings、Environment Variables,勾选 Production 和 Preview),然后重新部署:NEXT_PUBLIC_ 的值会写入构建产物,因此在添加变量之前完成的部署中密钥为空。

.env.local
NEXT_PUBLIC_BLIPIT_KEY=blipit_pk_your_public_key
BLIPIT_SECRET_KEY=blipit_sk_your_secret_key

4浏览器端

在根布局中添加一次该组件。它从 NEXT_PUBLIC_BLIPIT_KEY 读取公钥。如果该变量为空,它不会启动任何功能,并会在浏览器控制台中说明。

app/layout.tsx
import { Blipit } from "@blipit/nextjs";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <Blipit
          publicKey={process.env.NEXT_PUBLIC_BLIPIT_KEY!}
          environment={process.env.NEXT_PUBLIC_VERCEL_ENV ?? "development"}
          release={process.env.NEXT_PUBLIC_VERCEL_GIT_COMMIT_SHA}
          replay={{ onErrorSampleRate: 1 }}
        />
        {children}
      </body>
    </html>
  );
}

5服务端

Next.js 15 及更高版本会在 server component、route handler 和 server action 出错时调用 onRequestError。instrumentation.ts 中的一行代码即可将其接入 Blipit。从 @blipit/nextjs 0.2.1 起,同一行代码也适用于带有 middleware.ts 的应用和 Edge 路由(runtime = "edge"):应用可以正常构建,middleware 和 Edge 的错误也会上报。Next.js 14 没有 onRequestError,因此请像第二个示例那样用 withBlipit 包裹每个 route handler 和 server action:它会上报错误并重新抛出,并跳过重定向和 notFound()。在服务器环境中设置 BLIPIT_SECRET_KEY,切勿设为 NEXT_PUBLIC_。

instrumentation.ts
export { captureRequestError as onRequestError } from "@blipit/nextjs/server";
app/api/orders/route.ts
import { withBlipit } from "@blipit/nextjs/server";

export const GET = withBlipit(async (request: Request) => {
  return Response.json(await loadOrders());
});

6依赖服务和服务器健康

从 @blipit/nextjs 0.3 起,同时导出 register,让 Blipit 在服务器启动时开始运行。之后数据库和外部服务调用会显示在依赖服务页面,服务器的 CPU、内存和事件循环会显示在服务器健康页面。在 Edge 运行时中不做任何事。 在 Vercel 上,register 可能看不到传入请求:从 @blipit/nextjs 0.4 起,用 withBlipit 包装路由处理函数和 server action,每个都会成为 Pulse 页面上的一个请求,并附带其数据库和外部服务调用,在响应之后发送,不会拖慢响应。

instrumentation.ts
export { captureRequestError as onRequestError, register } from "@blipit/nextjs/server";
app/api/orders/route.ts
import { withBlipit } from "@blipit/nextjs/server";

export const GET = withBlipit(async (request: Request) => Response.json(await loadOrders()));

7由 error.tsx 捕获的错误

被 error.tsx 或 global-error.tsx 边界捕获的错误永远不会到达浏览器的错误处理程序,因此需要在边界中上报。这两个文件都是客户端组件。

app/error.tsx
"use client";

import { useEffect } from "react";
import { captureException } from "@blipit/nextjs";

export default function Error({ error, reset }: { error: Error & { digest?: string }; reset: () => void }) {
  useEffect(() => {
    captureException(error);
  }, [error]);
  return (
    <div>
      <p>Something went wrong.</p>
      <button onClick={() => reset()}>Try again</button>
    </div>
  );
}
app/global-error.tsx
"use client";

import { useEffect } from "react";
import { captureException } from "@blipit/nextjs";

export default function GlobalError({ error }: { error: Error & { digest?: string } }) {
  useEffect(() => {
    captureException(error);
  }, [error]);
  return (
    <html>
      <body>
        <p>Something went wrong.</p>
      </body>
    </html>
  );
}

8不要把密钥放进 git

请把密钥保存在环境变量或托管平台的密钥设置中,切勿写进你提交的代码,并把 .env 文件加入 .gitignore。网页中出现公钥是正常的。如果私密密钥曾出现在 git、公开页面、截图或聊天中,请打开“API 密钥”,点击“创建新的密钥”,并在所有用过旧密钥的地方粘贴新密钥:旧密钥会立即失效。

.gitignore
.env
.env.local
.env.*.local

9Content Security Policy

如果你的网站发送 Content Security Policy,请允许 script-src https://blipit.io(script 标签,以及首次使用时从 blipit.io/sdk/<version>/ 加载的报告编辑器和回放插件)、connect-src https://in.blipit.io(事件、截图和屏幕录制都发送到 in.blipit.io)、img-src data:(截图由页面的一张图片绘制而成)和 media-src blob:(录制内容在报告窗口中播放)。截图会重新加载页面的图片和字体,因此它们的主机也要加入 connect-src,否则会显示为空白。无需修改 style-src。使用 script 标签时,请从你自己的 .js 文件中调用 Blipit.init,或为内联脚本设置 nonce,因为严格的策略会阻止内联脚本。 要在屏幕录制中录入声音,网站的 Permissions-Policy 头必须允许 microphone=(self),屏幕录制还需要 display-capture=(self);设置为 microphone=() 时,录制没有声音。

10Source map(可选)

为了让堆栈跟踪显示你的源码而不是压缩后的 bundle,请在构建步骤中为每个 release 上传 map 文件。

sh
BLIPIT_KEY=<secret key> npx @blipit/cli sourcemaps upload .next/static --release "$VERCEL_GIT_COMMIT_SHA"

11错误报告:“报告问题”按钮

SDK 使用你的公钥启动后,每个页面的右下角就会出现一个“报告问题”按钮,使用访客的语言。点击后会打开报告器:一张可标注的页面截图、一个元素选择器、可选的屏幕录制,以及标题和描述。你可以像下面这样在代码中更改位置、样式、文字、颜色和快捷键,也可以在 app.blipit.io 的“项目设置”›“错误报告小组件”中一次性为所有网站更改;代码中的选项优先。“错误报告按钮”指南用截图和在线演示展示了每个选项。

app/layout.tsx
<Blipit
  publicKey={process.env.NEXT_PUBLIC_BLIPIT_KEY!}
  feedbackWidget={{
    position: "bottom-left",
    style: "icon",
    text: "Report Issue",
    color: "#E11D48",
    shortcut: "ctrl+shift+b",
  }}
/>
默认的“报告问题”按钮,位于右下角。
默认的“报告问题”按钮,位于右下角。
报告器:已标注的截图、标题和问题描述。
报告器:已标注的截图、标题和问题描述。

12从你自己的按钮打开报告器

用 <BlipitReportButton /> 把官方按钮放在任何位置,服务器组件中也可以:它显示 Blipit 图标和访客语言的“报告问题”,并打开报告窗口。想用自己的设计?调用 openReport 的组件必须是客户端组件,所以要在文件顶部加上 "use client"。<Blipit /> 必须已经放在 app/layout.tsx 中。不使用 Next.js 的 React 应用从 @blipit/nextjs/react 导入按钮,从 @blipit/browser 导入 openReport。

app/header.tsx
import { BlipitReportButton } from "@blipit/nextjs";

export function Header() {
  return (
    <header>
      <a href="/">Acme</a>
      <BlipitReportButton />
    </header>
  );
}
不使用 Next.js 的 React
import { BlipitReportButton } from "@blipit/nextjs/react";

<BlipitReportButton variant="outline" size="sm" />
app/report-issue.tsx
"use client";

import { openReport } from "@blipit/nextjs";

export function ReportIssue() {
  return <button onClick={() => openReport()}>Report Issue</button>;
}
React(@blipit/browser)
import { openReport } from "@blipit/browser";

export function ReportIssue() {
  return <button onClick={() => openReport()}>Report Issue</button>;
}
网站页眉中的官方“报告问题”按钮。
网站页眉中的官方“报告问题”按钮。
一个 Next.js 应用:页眉中的自定义 Report Issue 按钮打开了 Blipit 报告器。
一个 Next.js 应用:页眉中的自定义 Report Issue 按钮打开了 Blipit 报告器。

13隐藏默认按钮

如果只想保留你自己的按钮,可以在代码中用 feedbackWidget: false 关闭浮动按钮(在 <Blipit /> 上使用 feedbackWidget={false}),或在项目的“错误报告小组件”设置中关闭“显示错误报告按钮”,从而在所有使用该密钥的网站上隐藏它。无论哪种方式,openReport() 和 attachReport() 都能继续使用。

app/layout.tsx
<Blipit publicKey={process.env.NEXT_PUBLIC_BLIPIT_KEY!} feedbackWidget={false} />

14预填报告器并添加上下文

在用户登录后调用 setUser:报告者的姓名和邮箱会自动填写,你回复或更改状态时对方会收到邮件。setReportMetadata 会把你自己的字段(例如套餐或购物车数量)添加到每份报告中;它在报告发送时运行,因此值始终是最新的。

app/blipit-user.tsx
"use client";

import { useEffect } from "react";
import { setReportMetadata, setUser } from "@blipit/nextjs";

export function BlipitUser({ user }: { user: { id: string; name: string; email: string; plan: string } }) {
  useEffect(() => {
    setUser({ id: user.id, username: user.name, email: user.email });
    setReportMetadata(() => ({ plan: user.plan }));
  }, [user]);
  return null;
}

15验证是否生效

重新加载应用。右下角会出现“报告问题”按钮,一分钟内页面浏览会显示在 app.blipit.io 的“Web 指标”下。然后添加一个调用 captureMessage 的按钮,或一个会抛出错误的按钮,并点击它:事件会在几秒内出现在“问题”下。

tsx
"use client";
import { captureMessage } from "@blipit/nextjs";

export function TestBlipit() {
  return <button onClick={() => captureMessage("Hello from Next.js")}>Send a test event</button>;
}

16如果按钮或事件没有出现

  • 打开浏览器控制台,查找以 [blipit] 开头的行。开启 debug(在 init 中设置 debug: true,或在 <Blipit /> 上设置 debug),即可查看按钮是已显示、在代码中被关闭,还是被项目设置隐藏。
  • Next.js 只会把名称以 NEXT_PUBLIC_ 开头的变量发送到浏览器,所以请使用 NEXT_PUBLIC_BLIPIT_KEY。Vite 只发送 VITE_ 变量,所以请使用 VITE_BLIPIT_KEY。使用其他任何名称,浏览器中的密钥都会为空,Blipit 也不会启动。
  • 添加或修改 .env 或 .env.local 后,请重启开发服务器。它只在启动时读取这些文件。
  • 在 Vercel 或其他任何托管平台上,在项目的环境变量中添加相同的变量,然后重新部署。NEXT_PUBLIC_ 和 VITE_ 的值会写入构建产物,因此正在运行的部署永远看不到之后添加的值。
  • 请使用公钥(blipit_pk_)。私密密钥(blipit_sk_)在浏览器中会被拒绝并在控制台报错;如果它曾出现在页面上,请创建新的私密密钥。
  • 在 Next.js 中,<Blipit /> 应放在根 app/layout.tsx(或 pages/_app.tsx)中,这样它会在每个页面运行。在其他应用中,在入口文件中、应用渲染之前调用一次 init。
  • 必须在 app.blipit.io 的“项目设置”›“错误报告小组件”中开启“显示错误报告按钮”,并且你的代码不能传入 feedbackWidget: false。SDK 会将项目设置缓存最多一小时,因此请在无痕窗口中测试更改。
  • 广告拦截器和隐私扩展可能会拦截 in.blipit.io。请在关闭扩展的无痕窗口中重试。
  • 如果你的网站发送 Content Security Policy,请允许 script-src https://blipit.io、connect-src https://in.blipit.io、img-src data: 和 media-src blob:。报告编辑器在第一次点击时从 blipit.io/sdk 加载,截图由一张 data: 图片绘制,屏幕录制也会上传到 in.blipit.io。开启 debug 后,控制台会提示策略何时阻止了截图。 要在屏幕录制中录入声音,网站的 Permissions-Policy 头必须允许 microphone=(self),屏幕录制还需要 display-capture=(self);设置为 microphone=() 时,录制没有声音。
  • 用 npm ls @blipit/browser @blipit/nextjs(或 pnpm list @blipit/browser @blipit/nextjs)查看已安装的版本,并与更新日志对比。pnpm 11 会在新版本发布一天后才安装它(minimum-release-age),所以在发布当天 pnpm add 会悄悄安装上一个版本。要立即获得新版本:pnpm add @blipit/browser@<version> @blipit/nextjs@<version> --config.minimum-release-age=0。
  • 仍未解决?请把控制台中的 [blipit] 行发邮件至 support@blipit.io。

须知

  • 不用 Next.js 的纯 React:npm install @blipit/browser,并在渲染前调用 Blipit.init;参见“任意网站”。
  • 在服务端省略 environment 和 release 时,默认取 VERCEL_ENV 和 VERCEL_GIT_COMMIT_SHA。
  • 让 Blipit 保持最新:《让 Blipit 保持最新》指南(docs.blipit.io/updates)介绍了更新横幅、重要版本的邮件、开发控制台中的提示以及此平台的更新命令。
  • 每个应用每个平台一个项目:每个项目在创建时选择自己的平台(Android、iOS、React Native、Flutter、Web、Backend 或 Odoo),Blipit 会以明确的错误拒绝来自其他平台的数据,所以 iOS 应用和 Android 应用需要两个项目、两个密钥。各平台的发布、版本、崩溃率和商店构建都不同,混在一个项目里会让这些数据全部失真。Web 项目也接收同一 Web 应用的服务器端数据(Next.js 服务器或 Node),React Native 或 Flutter 项目也接收它自己的 Android 和 iOS 原生崩溃报告。

遇到问题?发邮件至 support@blipit.io。每个项目的密钥和项目 id 在 app.blipit.io 的“API 密钥”下。