Node.js

安装 npm install @blipit/node

@blipit/node 自动捕获未捕获的异常和未处理的 promise rejection,为 Express 和 Fastify 提供 handler,并用同一个密钥发送日志和登录尝试。使用私密密钥;它留在服务器上。 从 0.3 起,它还为 Koa、Hono 和 NestJS 提供一行接入,并为 AWS Lambda 风格的处理函数提供包装器。

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

1安装

sh
npm install @blipit/node

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将密钥保存在环境变量中

Node 使用私密密钥。请把它放在环境变量中,切勿写进代码:本地放在 .env 文件中(Node 20.6 及以上版本可用 --env-file 加载),生产环境放在托管平台的环境变量或密钥设置中(Fly secrets、Docker、systemd、Render、Vercel)。修改后请重启进程。

.env
BLIPIT_SECRET_KEY=blipit_sk_your_secret_key
sh
node --env-file=.env --import ./instrument.mjs server.mjs

4不要把密钥放进 git

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

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

5先初始化

把这段代码放在一个在你的应用之前运行的文件中,并最先导入它。

instrument.mjs
import * as Blipit from "@blipit/node";

Blipit.init({
  key: process.env.BLIPIT_SECRET_KEY,
  environment: process.env.NODE_ENV,
  release: process.env.RELEASE,
  serverName: "api",
});

6Express、Fastify、Koa、Hono 或 NestJS

在路由之后添加 handler,这样已处理和未处理的错误都会到达 Blipit,并附带请求的方法、URL 和 user agent。 Koa、Hono 和 NestJS 各只需一行:Koa 的中间件放在最前面,Hono 的放在路由之前。它们上报状态码为 500 及以上的错误。之后请求在 Pulse 页面按路由显示,例如 GET /users/:id,而不是每个 URL 一行。

js
import "./instrument.mjs";
import * as Blipit from "@blipit/node";
import express from "express";

const app = express();
app.get("/", (req, res) => res.send("ok"));
app.use(Blipit.expressErrorHandler());
app.listen(3000);
Fastify
await app.register(Blipit.fastifyPlugin());
Koa
app.use(Blipit.koaMiddleware());
Hono
app.use(Blipit.honoMiddleware());
NestJS
app.useGlobalInterceptors(Blipit.nestInterceptor());

7无服务器:AWS Lambda 和 Vercel

无服务器平台在函数一返回响应就会暂停它,而且 Lambda 不运行 Node 的 HTTP 服务器,所以请包装处理函数。wrapHandler 会记录请求(API Gateway、函数 URL 和负载均衡器事件按方法和路由命名,其他事件按函数名),上报错误,并在处理函数返回前发送所有数据;只有在有数据要发送时才会等待,最多 2 秒。traceRequest 对任何接收 Request 的处理函数做同样的事。在 Vercel 上,数据在响应之后通过 waitUntil 发送,不会造成任何延迟。在 Next.js 中请使用 withBlipit(见 Next.js 指南)。

js
import * as Blipit from "@blipit/node";

export const handler = Blipit.wrapHandler(async (event, context) => {
  return { statusCode: 200, body: "ok" };
});
traceRequest
export default { fetch: (request) => Blipit.traceRequest(request, () => app.fetch(request)) };

8手动捕获、日志和登录尝试

js
Blipit.captureException(err);
Blipit.captureMessage("cache miss rate above 50%", "warning");
Blipit.setUser({ id: "user-42" });
Blipit.log.info("order placed", { order_id: 42 });
Blipit.captureSecurity({ kind: "login_failed", actor: email, ip, userAgent, outcome: "bad_password" });
await Blipit.flush();

9依赖服务和服务器健康

从 0.2 起,SDK 还会记录你的数据库和外部服务调用,以及服务器的 CPU、内存和事件循环。请参阅依赖服务和服务器健康指南;可用 tracesSampleRate、tracing: false 和 metrics: false 控制。

10验证是否生效

打开 app.blipit.io 中的“问题”。首个事件几秒钟内就会出现,并归组为一个问题,负责人会收到邮件。

js
Blipit.captureMessage("Hello from Node");

须知

  • 遇到未捕获的异常时,SDK 会先发送待处理的事件,然后以代码 1 退出;可通过 onFatal 覆盖。
  • captureConsole: true 会把 console.log 及同类调用转为日志行,发送到日志页面。
  • 用 npm ls @blipit/node(或 pnpm list @blipit/node)查看已安装的版本。pnpm 11 会在新版本发布一天后才安装它(minimum-release-age),所以在发布当天 pnpm add 会悄悄安装上一个版本;要立即获得新版本,运行 pnpm add @blipit/node@<version> --config.minimum-release-age=0。
  • 让 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 密钥”下。