生產環境中,未捕獲的異常若不及時發現會導致服務不可用、資料損毀。Raygun 提供即時錯誤追蹤、分組、趨勢分析與部署關聯功能。本文示範如何在 Node.js (Express) 應用中接入 raygun4node,實現零侵入式錯誤自動上報。
npm install raygun --save
var raygun = require('raygun');
var raygunClient = new raygun.Client().init({
apiKey: 'YOUR_RAYGUN_API_KEY' // 從 Raygun 儀表板獲取
});
Express 錯誤處理中介軟體 (四參數簽名) 會接收所有路由拋出的錯誤。掛載 Raygun 官方提供的 expressHandler 即可自動上報:
var express = require('express');
var app = express();
// ... 路由定義 ...
// 最後掛載錯誤處理中介軟體 (順序很重要)
app.use(raygunClient.expressHandler);
此時所有未捕獲的同步/非同步錯誤 (透過 next(err) 傳遞) 將自動發送至 Raygun,包含堆疊追蹤、請求參數、使用者資訊、環境變數等豐富上下文。
uncaughtException (不推薦用於生產)process.on('uncaughtException', function(err) {
raygunClient.send(err);
// 重要:記錄後應優雅退出,因為進程狀態已不可預測
process.exit(1);
});
警告:Node.js 文檔明確建議避免使用 uncaughtException 繼續運行,進程處於未定義狀態,未來版本可能移除。
var domain = require('domain');
var http = require('http');
var server = http.createServer(function(req, res) {
var d = domain.create();
d.on('error', function(err) {
raygunClient.send(err);
// 清理資源
res.statusCode = 500;
res.end('Internal Server Error');
});
d.add(req);
d.add(res);
d.run(function() {
// 此處處理請求,任何同步/非同步拋出的錯誤都會被 domain 捕獲
handleRequest(req, res);
});
});
server.listen(3000);
Domain 提供請求級別的錯誤隔離,單一請求崩潰不影響其他請求處理。
async_hooks (Node 8+)Node.js 8+ 引入 async_hooks 追蹤非同步呼叫上下文,配合 cls-rtracer 等庫可實現更精準的錯誤上下文關聯。生產環境強烈建議升級至此方案。
raygunClient.user = function(req) {
if (req.user) {
return {
identifier: req.user.id,
email: req.user.email,
fullName: req.user.name
};
}
return { identifier: req.ip }; // 匿名用戶用 IP
};
raygunClient.version = '1.2.3'; // 應用版本,關聯部署
raygunClient.tags = ['production', 'api-v2']; // 標籤過濾
try {
// 高風險操作
JSON.parse(malformedInput);
} catch (e) {
raygunClient.send(e, { customData: { input: malformedInput } });
}
上傳 Source Map 至 Raygun (API 或 CLI),可將混淆後的堆疊還原至原始碼行號,大幅縮短排查時間。
# 使用 raygun-cli 上傳
npm install -g raygun-cli
raygun sourcemap upload --apiKey YOUR_KEY --version 1.2.3 --path ./dist
app.use(raygunClient.expressHandler) 一行搞定 99% 路由錯誤。uncaughtException 陷阱。async_hooks 基礎的上下文傳遞方案。user、version、tags 並上傳 Source Map,讓錯誤可追蹤、可過濾、可定位。接入 Raygun 只需幾分鐘,卻能為團隊帶來 7×24 小時的自動化錯誤雷達,是 Node.js 服務上線前的必備保險。