按平台安装
Node.js
安装 npm install @blipit/node
@blipit/node 自动捕获未捕获的异常和未处理的 promise rejection,为 Express 和 Fastify 提供 handler,并用同一个密钥发送日志和登录尝试。使用私密密钥;它留在服务器上。 从 0.3 起,它还为 Koa、Hono 和 NestJS 提供一行接入,并为 AWS Lambda 风格的处理函数提供包装器。
1安装
npm install @blipit/node2获取密钥
登录 app.blipit.io,打开侧边栏中的“API 密钥”,然后选择你的项目。每个项目有两个密钥。公钥以 blipit_pk_ 开头:它用于浏览器和应用代码,只能发送事件,任何人看到都没关系。私密密钥以 blipit_sk_ 开头:它留在你的服务器或 Odoo 中,切勿放进浏览器,因为它还可以读取和更改问题。私密密钥只在创建后显示一次,请当时就复制;如果丢失,请点击“创建新的密钥”,旧密钥会立即失效。部分 SDK 还需要项目 id,它显示在同一页面上。
3将密钥保存在环境变量中
Node 使用私密密钥。请把它放在环境变量中,切勿写进代码:本地放在 .env 文件中(Node 20.6 及以上版本可用 --env-file 加载),生产环境放在托管平台的环境变量或密钥设置中(Fly secrets、Docker、systemd、Render、Vercel)。修改后请重启进程。
BLIPIT_SECRET_KEY=blipit_sk_your_secret_keynode --env-file=.env --import ./instrument.mjs server.mjs4不要把密钥放进 git
请把密钥保存在环境变量或托管平台的密钥设置中,切勿写进你提交的代码,并把 .env 文件加入 .gitignore。网页中出现公钥是正常的。如果私密密钥曾出现在 git、公开页面、截图或聊天中,请打开“API 密钥”,点击“创建新的密钥”,并在所有用过旧密钥的地方粘贴新密钥:旧密钥会立即失效。
.env
.env.local
.env.*.local5先初始化
把这段代码放在一个在你的应用之前运行的文件中,并最先导入它。
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 一行。
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);await app.register(Blipit.fastifyPlugin());app.use(Blipit.koaMiddleware());app.use(Blipit.honoMiddleware());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 指南)。
import * as Blipit from "@blipit/node";
export const handler = Blipit.wrapHandler(async (event, context) => {
return { statusCode: 200, body: "ok" };
});export default { fetch: (request) => Blipit.traceRequest(request, () => app.fetch(request)) };8手动捕获、日志和登录尝试
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 中的“问题”。首个事件几秒钟内就会出现,并归组为一个问题,负责人会收到邮件。
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 密钥”下。

