按平台安装
Next.js 和 React
安装 npm install @blipit/nextjs
@blipit/nextjs 只需在布局中放一个组件,就能提供浏览器错误、Web 指标、会话回放和“报告问题”按钮;在 instrumentation.ts 中加一行,即可捕获服务端组件、路由处理程序和 server action 的错误。普通 React 应用使用 @blipit/browser。
1安装
npm install @blipit/nextjs2获取密钥
登录 app.blipit.io,打开侧边栏中的“API 密钥”,然后选择你的项目。每个项目有两个密钥。公钥以 blipit_pk_ 开头:它用于浏览器和应用代码,只能发送事件,任何人看到都没关系。私密密钥以 blipit_sk_ 开头:它留在你的服务器或 Odoo 中,切勿放进浏览器,因为它还可以读取和更改问题。私密密钥只在创建后显示一次,请当时就复制;如果丢失,请点击“创建新的密钥”,旧密钥会立即失效。部分 SDK 还需要项目 id,它显示在同一页面上。
3把密钥放进 .env.local
在项目根目录创建 .env.local,写入供浏览器使用的公钥;如果你使用下面的服务端功能,还要写入供服务器使用的私密密钥。只有以 NEXT_PUBLIC_ 开头的名称会传到浏览器,所以切勿给私密密钥加这个前缀。保存文件后重启 npm run dev。对于生产环境,在你的托管平台中添加相同的变量(在 Vercel 上:Project、Settings、Environment Variables,勾选 Production 和 Preview),然后重新部署:NEXT_PUBLIC_ 的值会写入构建产物,因此在添加变量之前完成的部署中密钥为空。
NEXT_PUBLIC_BLIPIT_KEY=blipit_pk_your_public_key
BLIPIT_SECRET_KEY=blipit_sk_your_secret_key4浏览器端
在根布局中添加一次该组件。它从 NEXT_PUBLIC_BLIPIT_KEY 读取公钥。如果该变量为空,它不会启动任何功能,并会在浏览器控制台中说明。
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_。
export { captureRequestError as onRequestError } from "@blipit/nextjs/server";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 页面上的一个请求,并附带其数据库和外部服务调用,在响应之后发送,不会拖慢响应。
export { captureRequestError as onRequestError, register } from "@blipit/nextjs/server";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 边界捕获的错误永远不会到达浏览器的错误处理程序,因此需要在边界中上报。这两个文件都是客户端组件。
"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>
);
}"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 密钥”,点击“创建新的密钥”,并在所有用过旧密钥的地方粘贴新密钥:旧密钥会立即失效。
.env
.env.local
.env.*.local9Content 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 文件。
BLIPIT_KEY=<secret key> npx @blipit/cli sourcemaps upload .next/static --release "$VERCEL_GIT_COMMIT_SHA"14预填报告器并添加上下文
在用户登录后调用 setUser:报告者的姓名和邮箱会自动填写,你回复或更改状态时对方会收到邮件。setReportMetadata 会把你自己的字段(例如套餐或购物车数量)添加到每份报告中;它在报告发送时运行,因此值始终是最新的。
"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 的按钮,或一个会抛出错误的按钮,并点击它:事件会在几秒内出现在“问题”下。
"use client";
import { captureMessage } from "@blipit/nextjs";
export function TestBlipit() {
return <button onClick={() => captureMessage("Hello from Next.js")}>Send a test event</button>;
}须知
- 不用 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 密钥”下。





