任意网站

安装 npm install @blipit/browser

Blipit 浏览器 SDK 只有 10 KB。它会捕获未捕获的错误、未处理的 promise rejection 和失败的请求,保留导致每个错误的点击和请求,记录 Web 指标,在每个页面放置“报告问题”按钮,并可在发生错误时录制会话回放。在打包应用中通过 npm 安装,或在任意页面中加入一个 script 标签。

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

1获取密钥

登录 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。
新的私密密钥只显示一次。请立即复制:它以哈希形式存储,无法再次显示。
新的私密密钥只显示一次。请立即复制:它以哈希形式存储,无法再次显示。

2使用 npm

在入口文件中、应用渲染之前,用公钥调用一次 init。使用 Vite(React、Vue、Svelte)时,把密钥以 VITE_BLIPIT_KEY 保存在 .env 中;只有 VITE_ 开头的变量会传到浏览器,而且开发服务器只在启动时读取 .env。

sh
npm install @blipit/browser
.env
VITE_BLIPIT_KEY=blipit_pk_your_public_key
src/main.js
import * as Blipit from "@blipit/browser";

Blipit.init({
  key: import.meta.env.VITE_BLIPIT_KEY,
  environment: import.meta.env.MODE,
  release: "2026.09.28",
  replay: { onErrorSampleRate: 1 },
});

3不用打包器:一个 script 标签

把这段代码粘贴到每个页面的 <head> 中,或粘贴到你所用平台的自定义代码位置,并写入你的公钥。这没有问题:公钥只能发送事件。

html
<script src="https://blipit.io/sdk/blipit.js"></script>
<script>
  Blipit.init({ key: "blipit_pk_your_public_key", environment: "production", release: "2026.09.28", replay: { onErrorSampleRate: 1 } });
</script>

4不要把密钥放进 git

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

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

5告诉 Blipit 用户是谁(可选)

登录后附加用户信息,问题就能显示受影响的人,回放也可以按用户查找。

js
Blipit.setUser({ id: "42", email: "ana@example.com" });

6React、Vue、Angular 和 Svelte:上报已捕获的错误

框架会在浏览器看到之前捕获组件内部的错误,所以也要把这些错误传给 Blipit。其他地方未捕获的错误会自动上报。

React 19(src/main.tsx)
createRoot(document.getElementById("root")!, {
  onCaughtError: (error) => Blipit.captureException(error),
  onUncaughtError: (error) => Blipit.captureException(error),
}).render(<App />);
或者,React 18 及更早版本:错误边界
class ErrorBoundary extends React.Component<{ children: React.ReactNode }, { failed: boolean }> {
  state = { failed: false };
  static getDerivedStateFromError() {
    return { failed: true };
  }
  componentDidCatch(error: Error) {
    Blipit.captureException(error);
  }
  render() {
    return this.state.failed ? <p>Something went wrong.</p> : this.props.children;
  }
}
Vue(src/main.ts)
const app = createApp(App);
app.config.errorHandler = (err) => Blipit.captureException(err);
app.mount("#app");
Angular(app.config.ts)
import { ErrorHandler } from "@angular/core";
import * as Blipit from "@blipit/browser";

class BlipitErrorHandler implements ErrorHandler {
  handleError(error: unknown) {
    Blipit.captureException(error);
    console.error(error);
  }
}

export const appConfig = { providers: [{ provide: ErrorHandler, useClass: BlipitErrorHandler }] };
SvelteKit(src/hooks.client.ts)
import * as Blipit from "@blipit/browser";
import type { HandleClientError } from "@sveltejs/kit";

export const handleError: HandleClientError = ({ error }) => {
  Blipit.captureException(error);
};

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

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

js
Blipit.init({
  key: import.meta.env.VITE_BLIPIT_KEY,
  feedbackWidget: {
    position: "bottom-left",
    style: "icon",
    text: "Report Issue",
    color: "#E11D48",
    shortcut: "ctrl+shift+b",
  },
});
默认的“报告问题”按钮,位于右下角。
默认的“报告问题”按钮,位于右下角。
报告器:已标注的截图、标题和问题描述。
报告器:已标注的截图、标题和问题描述。

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

要在你自己的页眉或菜单中放置“报告问题”按钮,请使用官方按钮:Blipit.reportButton() 会返回一个现成的按钮,带有 Blipit 图标和访客语言的“报告问题”;React 应用可以渲染 @blipit/nextjs/react 中的 <BlipitReportButton />(npm install @blipit/nextjs)。想用自己的设计?从任意点击处理函数调用 openReport(),或用 attachReport(element) 绑定一个已有的元素。两种方式打开的报告窗口都与悬浮按钮完全相同。Blipit 图标只能放在“报告问题”旁边使用,就像官方按钮那样。

官方按钮,纯 HTML
<nav id="help-menu"></nav>
<script>
  document.getElementById("help-menu").append(Blipit.reportButton());
</script>
官方按钮,React
import { BlipitReportButton } from "@blipit/nextjs/react";

export function Header() {
  return (
    <header>
      <a href="/">Acme</a>
      <BlipitReportButton variant="outline" size="sm" />
    </header>
  );
}
官方按钮,Vue
<script setup>
import { onMounted, ref } from "vue";
import { reportButton } from "@blipit/browser";

const slot = ref();
onMounted(() => slot.value.append(reportButton({ variant: "outline", size: "sm" })));
</script>

<template>
  <span ref="slot"></span>
</template>
纯 HTML
<button id="report-issue">Report Issue</button>
<script>
  Blipit.attachReport(document.getElementById("report-issue"));
</script>

<button onclick="Blipit.openReport()">Report Issue</button>
React
import { openReport } from "@blipit/browser";

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

<template>
  <button @click="openReport()">Report Issue</button>
</template>
网站页眉中的官方“报告问题”按钮。
网站页眉中的官方“报告问题”按钮。
页眉中的自定义 Report Issue 按钮会打开 Blipit 报告器。
页眉中的自定义 Report Issue 按钮会打开 Blipit 报告器。

9隐藏默认按钮

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

js
Blipit.init({ key: import.meta.env.VITE_BLIPIT_KEY, feedbackWidget: false });

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

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

js
Blipit.setUser({ id: "42", username: "Ana Lima", email: "ana@example.com" });

Blipit.setReportMetadata(() => ({ plan: "pro", cartItems: cart.length }));

11全部选项和函数

  • key:公钥(blipit_pk_)。必填。
  • environment 和 release:显示在每个事件上;release 用于回归检测和 source map。environment 默认为 production。
  • debug: true 会把 SDK 的操作记录到控制台,每行以 [blipit] 开头。
  • sampleRate(0 到 1)、ignoreErrors(字符串或正则)和 beforeSend(修改事件,或返回 null 以丢弃)控制发送的内容。autoMuteExtensions(默认开启)会丢弃仅来自浏览器扩展的错误。
  • webVitals(默认开启)、replay({ sessionSampleRate, onErrorSampleRate })和 autoSessionTracking(无崩溃率,需要 release)。
  • feedbackWidget: false 会隐藏“报告问题”按钮;传入包含 position、style、text、color、font、match 和 shortcut 的对象则可更改它。theme: "light"、"dark" 或 "auto" 设置报告器的主题。
  • user({ id, name, email })和 company(名称或 { id, name })会填入报告器并添加到报告中。
  • endpoint:仅用于自托管的接收服务;默认值为 https://in.blipit.io/api/v1/events。
  • 函数:captureException(error)、captureMessage(text, level)、setUser、setTag(key, value)、addBreadcrumb({ category, message })、openReport()、attachReport(element)、reportButton(options)、updateWidget(options)、setReportMetadata(fn)、showFeedback() 和 flush(),后者在排队的事件发送完成后返回一个 promise。
  • 在仪表板中更改的小组件设置最多一小时内会传到浏览器,因为 SDK 会缓存这么久;无痕窗口会立即显示更改。

12验证是否生效

重新加载你的网站。右下角会出现“报告问题”按钮,一分钟内页面浏览会显示在 app.blipit.io 的“Web 指标”下。然后发送一个测试事件:在代码中调用一次 captureMessage,或者在使用 script 标签时,在浏览器控制台中运行下面这一行。它会在几秒内出现在“问题”下。

js
Blipit.captureMessage("Hello from " + location.host, "info");

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

  • 打开浏览器控制台,查找以 [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。

须知

  • 选项:sampleRate(0 到 1)、ignoreErrors(字符串或正则)、beforeSend 用于丢弃或修改事件、maxBreadcrumbs、webVitals(默认开启)、autoSessionTracking 用于无崩溃率(需要 release)。
  • blipit.io/sdk/blipit.js 始终提供最新版本(0.3.23)。如果你想自行控制升级,固定版本位于 blipit.io/sdk/0.3.23/blipit.js。
  • 如果你的网站发送 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=() 时,录制没有声音。
  • 让 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 密钥”下。