Rollbar.js Node.js 接入实战：Express 服务端错误追踪的 5 步配置法

Rollbar.js Node.js 接入实战：Express 服务端错误追踪的 5 步配置法

【免费下载链接】rollbar.jsError tracking and logging from Javascript to Rollbar项目地址: https://gitcode.com/gh_mirrors/ro/rollbar.js

Rollbar.js 是一款专业的错误追踪与日志记录工具，支持从浏览器到 Node.js 服务端的完整错误监控。本文面向新手，手把手教你在 Express 应用中完成Rollbar.js 服务端错误追踪的 5 步接入，快速定位线上 Bug、减少故障排查时间。

为什么需要 Node.js 服务端错误追踪？

浏览器端的报错你看得见，但服务端悄悄抛出的异常、未处理的 Promise 拒绝，往往只会让用户看到"500 错误"，却无人知晓原因。

Rollbar.js 的核心能力包括：

• 跨平台：同一套 SDK 覆盖 Node.js、React、Angular、Next.js 等前端与服务端场景
• 自动错误分组：相同错误自动聚合为一个 Item，避免告警风暴
• 遥测时间线（Telemetry）：错误发生前后的"面包屑"事件，还原故障现场
• 请求上下文自动附加：上报错误时自动携带 URL、请求头、IP 等信息，便于复现

服务端实现位于src/server/目录，Express 专用中间件在src/server/middleware/rollbarExpressMiddleware.js。

第 1 步：一键安装 rollbar SDK

在项目中执行 npm 安装（仓库地址：https://gitcode.com/gh_mirrors/ro/rollbar.js）：

npm install --save rollbar

如果你使用 yarn，则执行yarn add rollbar。

第 2 步：初始化 Rollbar 实例并配置 Access Token

在 Express 入口文件（如server.js）顶部初始化实例。accessToken填你在 Rollbar 控制台创建的POST Server Item Access Token（服务端专用令牌）：

const Rollbar = require('rollbar'); const rollbar = Rollbar.init({ accessToken: 'POST_SERVER_ITEM_ACCESS_TOKEN', captureUncaught: true, captureUnhandledRejections: true, payload: { code_version: '1.0.0' }, });

几个关键点：

• environment默认读取NODE_ENV环境变量，可区分 development / production
• 服务端默认选项定义在src/server/defaults.js与src/server/rollbar.js的Rollbar.defaultOptions中，例如默认开启 IP 捕获、敏感字段脱敏（scrubFields、scrubHeaders）

第 3 步：挂载 Express 错误处理中间件

这是 Express 接入的核心一步。在所有路由之后挂载errorHandler()中间件：

app.get('/error', function (req, res) { throw new Error('Hello World'); }); // 注意：必须放在所有路由定义之后 app.use(rollbar.errorHandler());

errorHandler()会拦截 Express 错误流，自动将err连同request上下文一起上报，然后再把错误交给后续中间件。实现见src/server/rollbar.js中的Rollbar.prototype.errorHandler。

💡 官方完整示例可参考examples/universal-node/server.js，该示例演示了服务端渲染 + Express 错误捕获的全栈接入方式。

第 4 步：捕获未捕获异常与 Promise 拒绝

在 Node.js 中，最致命的往往不是路由里抛出的错误，而是：

• 未被 try/catch 捕获的异常（uncaughtException）
• 未被 catch 的 Promise 拒绝（unhandledRejection）

初始化时开启两个开关即可全局接管：

const rollbar = Rollbar.init({ accessToken: '你的TOKEN', captureUncaught: true, // 捕获未捕获异常 captureUnhandledRejections: true // 捕获未处理的 Promise 拒绝 });

开启后，任何逃逸出 Express 错误流的异常都会被 Rollbar 兜底上报，避免"静默失败"。相关逻辑在setupUnhandledCapture、handleUncaughtExceptions方法中实现。

第 5 步：验证上报效果与进阶配置

启动服务后，访问会抛错的接口（如/error），即可在 Rollbar 控制台看到新的错误 Item，包含堆栈、请求 URL、主机名等信息。

常用进阶配置：

📊 开启autoInstrument后，SDK 会自动包装http.request、https.request、fetch以及process.stdout/stderr，把出站请求和日志都记录为遥测事件（实现见src/server/telemetry.js）。这样排查问题时，你能看到错误发生前服务调用了哪些下游接口、返回了什么状态码。

常见问题速查

• 错误没上报？检查enabled、transmit是否为true，以及accessToken是否使用了 Server Token 而非 Client Token
• 测试环境想静音？设置enabled: false或调高reportLevel
• 敏感数据泄露？默认的scrubFields/scrubHeaders已脱敏常见敏感字段（如password、Authorization），可按需扩充
• Lambda 场景？使用rollbar.lambdaHandler(handler)包装处理函数，还能捕获超时错误

小结

只需 5 步——安装 SDK → 初始化配置 → 挂载 Express 错误中间件 → 开启全局异常捕获 → 验证与进阶调优，就能让你的 Express 应用具备专业的服务端错误追踪能力。配合 Rollbar 控制台的自动分组、遥测时间线和告警通知，团队协作排查线上问题将事半功倍。更多框架示例（React、Angular、Next.js 等）可在仓库examples/目录中按需参考。

【免费下载链接】rollbar.jsError tracking and logging from Javascript to Rollbar项目地址: https://gitcode.com/gh_mirrors/ro/rollbar.js