萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 腳本程式專題 >> JavaScript

Node.js 錯誤監控實戰:接入 Raygun 實現自動異常捕獲與上報

生產環境中,未捕獲的異常若不及時發現會導致服務不可用、資料損毀。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 整合:自動捕獲路由異常

Express 錯誤處理中介軟體 (四參數簽名) 會接收所有路由拋出的錯誤。掛載 Raygun 官方提供的 expressHandler 即可自動上報:

var express = require('express');
var app = express();

// ... 路由定義 ...

// 最後掛載錯誤處理中介軟體 (順序很重要)
app.use(raygunClient.expressHandler);

此時所有未捕獲的同步/非同步錯誤 (透過 next(err) 傳遞) 將自動發送至 Raygun,包含堆疊追蹤、請求參數、使用者資訊、環境變數等豐富上下文。

非 Express 環境:捕獲未處理異常

方案 A:監聽 uncaughtException (不推薦用於生產)

process.on('uncaughtException', function(err) {
  raygunClient.send(err);
  // 重要:記錄後應優雅退出,因為進程狀態已不可預測
  process.exit(1);
});

警告:Node.js 文檔明確建議避免使用 uncaughtException 繼續運行,進程處於未定義狀態,未來版本可能移除。

方案 B:使用 Domain 模組 (Node.js 核心方案,已棄用但仍穩定)

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 提供請求級別的錯誤隔離,單一請求崩潰不影響其他請求處理。

方案 C:現代最佳實踐——Zone.js 或 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 支援:還原壓縮碼堆疊

上傳 Source Map 至 Raygun (API 或 CLI),可將混淆後的堆疊還原至原始碼行號,大幅縮短排查時間。

# 使用 raygun-cli 上傳
npm install -g raygun-cli
raygun sourcemap upload --apiKey YOUR_KEY --version 1.2.3 --path ./dist

總結

  • Express 應用:app.use(raygunClient.expressHandler) 一行搞定 99% 路由錯誤。
  • 非 Express/舊版 Node:改用 Domain 隔離請求錯誤,避免 uncaughtException 陷阱。
  • 現代 Node (8+):採用 async_hooks 基礎的上下文傳遞方案。
  • 務必配置 user、version、tags 並上傳 Source Map,讓錯誤可追蹤、可過濾、可定位。

接入 Raygun 只需幾分鐘,卻能為團隊帶來 7×24 小時的自動化錯誤雷達,是 Node.js 服務上線前的必備保險。

copyright © 萬盛學電腦網 all rights reserved