使用全面的開發人員解決方案有效管理 Next.js 中的錯誤

介紹

我很高興推出一個新的輕量級包，旨在簡化 Next.js 應用程式中的錯誤管理：nextjs-centralized-error-handler。作為開發人員，我們經常遇到錯誤處理方面的挑戰，尤其是在像 Next.js 這樣的框架中，傳統方法可能會導致重複程式碼和被忽視的場景。

從我使用 Yii2 框架的經驗中汲取靈感——內建錯誤類別簡化了錯誤管理，無需硬編碼狀態代碼或訊息——我認識到 Node.js 生態系統中也有類似的需求。這種認識促使在此套件中開發自訂錯誤類，從而增強一致性和可用性。

重要提示：此軟體套件目前處於測試階段。作為一個新發布的工具，您的回饋對於識別潛在問題並提高其穩定性至關重要。我鼓勵您嘗試 nextjs-centralized-error-handler 套件並分享您的見解，無論是透過錯誤報告還是改進建議。我們可以共同為 Next.js 社群加強這個軟體包。

目錄

• 簡介
• 快速入門
  • 安裝軟體套件
  • 包裝您的 API 路由處理程序
  • 自訂錯誤處理（可選）
• 為什麼要將 nextjs-centralized-error-handler 與 Next.js 中間件一起使用？
• 與 Next.js 13 中間件​​的比較
  • Next.js 13 中間件​​範例
  • 與 nextjs-centralized-error-handler 的比較
  • 了解範圍和靈活性：Next.js 中間件與 nextjs-centralized-error-handler
• 範例
  • 處理不同的 HTTP 方法
  • 驗證請求參數
  • 處理未經授權的存取
  • 強制有效負載限制
  • 自訂錯誤回應（進階）
• 與日誌服務整合
• 社群回饋與穩定性
• 好處一覽
• 結論

---

快速入門

1. 安裝軟體套件
   

   npm install nextjs-centralized-error-handler
   # or
   yarn add nextjs-centralized-error-handler
   

2. 包裝您的 API 路由處理程序
   

   // pages/api/example.js
   
   const { errorHandler, BadRequestError } = require('nextjs-centralized-error-handler');
   
   const handler = async (req, res) => {
     if (!req.body.name) {
       throw new BadRequestError('Name is required.');
     }
   
     res.status(200).json({ message: 'Success' });
   };
   
   export default errorHandler(handler);
   

3. 自訂錯誤處理（選購）
   

   npm install nextjs-centralized-error-handler
   # or
   yarn add nextjs-centralized-error-handler
   

---

為什麼將 nextjs-centralized-error-handler 與 Next.js 中間件一起使用？

Next.js 13 的中間件提供了強大的全域攔截功能，非常適合身份驗證和一般請求驗證等任務。然而，nextjs-centralized-error-handler 透過提供細粒度的路由級控制和中間件本身無法覆蓋的詳細響應來增強錯誤處理。以下是這個包如何補充和擴展 Next.js 中間件：

1. 特定於路由的錯誤管理：使用nextjs-centralized-error-handler，每個路由都可以定義自己的上下文錯誤處理，並使用與路由功能相匹配的定制訊息。這種模組化對於跨不同端點具有不同錯誤處理需求的複雜應用程式至關重要。

2. 具有詳細回應的自訂錯誤類別：該套件引入了具有結構化、前端友好的 JSON 回應的自訂錯誤類別（例如 BadRequestError、UnauthorizedError）。這些回應富含狀態代碼和錯誤類型等元數據，確保後端和前端團隊的錯誤處理可預測且標準化。

3. 增強的安全性和資料隱私：只有故意出現 CustomError 實例的錯誤才會將其狀態代碼和訊息傳送到客戶端。對於意外錯誤，將使用通用錯誤訊息，並將敏感詳細資訊保留在伺服器端，以最大限度地減少資訊外洩。

4. 日誌記錄並與監控工具集成：支援與日誌服務（例如 Sentry、Datadog）集成，實現超出中間件單獨實現的詳細錯誤追蹤和調試。

5. 可自訂和可擴展的錯誤處理：CustomError 類別是完全可擴展的，允許開發人員定義特定於應用程式的錯誤，隨著應用程式的發展創建靈活的錯誤處理策略。

透過將 Next.js 中間件與 nextjs-centralized-error-handler 結合，您可以實現強大且靈活的錯誤處理解決方案，支援全域和特定於路由的需求。

---

與 Next.js 13 中間件​​的比較

Next.js 13 引入了全域中間件，支援身份驗證和一般驗證等任務的請求級攔截。下面的比較顯示了 Next.js 13 中間件​​與 nextjs-centralized-error-handler 的不同之處以及何時使用它們。

Next.js 13 中間件​​範例

Next.js 13 中間件​​可以全域定義並套用於與指定模式相符的所有路由。這對於日誌記錄或授權等高級操作非常有用。

npm install nextjs-centralized-error-handler
# or
yarn add nextjs-centralized-error-handler

與 nextjs-centralized-error-handler 的比較

雖然 Next.js 中間件對於全域、高階任務很有用，但 nextjs-centralized-error-handler 可以使用自訂錯誤類別進行特定於路由的錯誤處理，以實現細粒度控制。以下是兩者如何協同工作：

Feature	Next.js 13 Middleware	nextjs-centralized-error-handler
Scope	Global, based on route pattern matching	Route-specific, applied individually to each handler
Use Case	Authentication, global request validation	Detailed error handling, custom error messages
Custom Error Responses	Limited, generalized JSON responses	Structured, frontend-compatible JSON responses
Custom Error Classes	❌	✅
Error Logging Integration	❌	✅ (supports Sentry, Datadog, etc.)
Fine-Grained Control	❌	✅
Preventing Information Leakage	Limited, as it handles errors globally without distinguishing between error types	Enhanced, distinguishes between custom and unexpected errors to prevent sensitive data exposure
Integration with Route Handlers	Middleware runs before route handlers, cannot modify responses within handlers	Wraps individual route handlers, allowing for customized responses per route
Extensibility	Limited to what middleware can handle globally	Highly extensible through custom error classes and configurable options

了解範圍和靈活性：Next.js 中間件與 nextjs-centralized-error-handler

雖然 Next.js 中間件為進階請求攔截提供了強大的機制，但需要注意的是，中間件在路由處理程序執行之前運行。這意味著處理程序內部拋出的任何異常都不會被中間件捕獲；相反，這將導致向客戶端返回通用的 500 內部伺服器錯誤。相較之下，nextjs-centralized-error-handler 擅長在單一 API 路由中進行細粒度的錯誤處理。本節闡明了它們的不同角色，並示範如何有效地一起使用它們。

場景：使用者輸入驗證

假設您正在建立一個 API 路由，需要在請求正文中提供使用者名稱。如果名稱遺失，您需要使用清晰且具體的錯誤訊息進行回應。讓我們看看每種方法如何處理這種情況。

使用 Next.js 中介軟體

在 Next.js 中，中介軟體可用於全域驗證請求。但是，它無法捕捉單一路由處理程序中引發的異常。

npm install nextjs-centralized-error-handler
# or
yarn add nextjs-centralized-error-handler

// pages/api/example.js

const { errorHandler, BadRequestError } = require('nextjs-centralized-error-handler');

const handler = async (req, res) => {
  if (!req.body.name) {
    throw new BadRequestError('Name is required.');
  }

  res.status(200).json({ message: 'Success' });
};

export default errorHandler(handler);

這裡發生了什麼事：

1. 中間件在路由處理程序之前執行以處理請求。
2. 如果 req.body.name 缺失，則會拋出錯誤。
3. 但是，中間件不會捕獲此錯誤，從而導致一般的 500 內部伺服器錯誤。

使用 nextjs-centralized-error-handler

相較之下，nextjs-centralized-error-handler 提供了一個高階函數，可以捕捉路由處理程序中拋出的錯誤。

const handler = async (req, res) => {
  // Your logic here
};

const options = {
  logger: customLoggerFunction,
  defaultMessage: 'Something went wrong!',
  formatError: (error, req) => ({
    message: error.message,
    type: error.name,
    timestamp: new Date().toISOString(),
  }),
};

export default errorHandler(handler, options);

這裡發生了什麼事：

1. errorHandler 包裝了路由處理程序，攔截其中拋出的任何錯誤。
2. 如果 req.body.name 缺失，則會拋出 BadRequestError 並被 errorHandler 捕獲。
3. 這會產生一個結構化回應，帶有適當的狀態代碼 (400) 和明確的錯誤訊息（「名稱為必填項。」）。

為什麼要同時使用這兩種方法

結合 Next.js 中間件和 nextjs-centralized-error-handler 提供了全面的錯誤處理策略：

• 全域請求驗證和驗證：使用 Next.js 中間件來處理需要跨多個路由應用程式的任務，例如驗證、授權和一般請求驗證。
• 特定於路由的詳細錯誤處理： 使用 nextjs-centralized-error-handler 來管理各個路由處理程序中發生的錯誤，從而允許根據每個路由的特定需求進行自訂和結構化錯誤回應。

範例：同時使用中間件和 nextjs-centralized-error-handler

中介軟體（middleware.js）：

npm install nextjs-centralized-error-handler
# or
yarn add nextjs-centralized-error-handler

路由處理程序 (pages/api/example.js):

// pages/api/example.js

const { errorHandler, BadRequestError } = require('nextjs-centralized-error-handler');

const handler = async (req, res) => {
  if (!req.body.name) {
    throw new BadRequestError('Name is required.');
  }

  res.status(200).json({ message: 'Success' });
};

export default errorHandler(handler);

說明：

• 中介軟體 (middleware.js): 處理驗證等全域任務。適用於基於匹配器配置的所有 /api/* 路由。
• 路由處理程序 (example.js): 處理特定於路由的邏輯。利用 nextjs-centralized-error-handler 進行詳細的錯誤處理和結構化回應。

透過使用 Next.js 中介軟體進行請求層級檢查，使用 nextjs-centralized-error-handler 進行回應層級錯誤處理，您可以實現廣泛的驗證和細粒度的錯誤管理。

---

nextjs-centralized-error-handler 的主要優點：

• 透過高階函數進行集中錯誤處理。
• 自訂錯誤類別以簡化和標準化錯誤分類。
• 前端相容的回應，使基於 Next.js 的前端更容易有效地解析和顯示錯誤訊息。

---

傳統方法與 nextjs-centralized-error-handler

在傳統的 Node.js/Express 應用程式中，集中式錯誤處理通常透過中介軟體進行管理，中間件會跨路由一致地攔截請求和錯誤。然而，在 Next.js 中，API 路由不以相同的方式支援中間件，這給集中式錯誤處理帶來了挑戰。 nextjs-centralized-error-handler 透過使用高階函數來提供跨所有 API 路由的特定於路由的錯誤處理，從而填補了這一空白。

Express 中的傳統方法（使用中間件）

在 Express 中，集中式錯誤處理是透過中間件函數實現的，這允許跨路由進行可重複使用的錯誤管理：

const handler = async (req, res) => {
  // Your logic here
};

const options = {
  logger: customLoggerFunction,
  defaultMessage: 'Something went wrong!',
  formatError: (error, req) => ({
    message: error.message,
    type: error.name,
    timestamp: new Date().toISOString(),
  }),
};

export default errorHandler(handler, options);

在這種方法中，錯誤被傳遞給 next(error)，然後觸發集中式錯誤處理中間件以跨路由做出一致的回應。

在 Next.js 中使用 nextjs-centralized-error-handler

使用nextjs-centralized-error-handler，您可以透過包裝路由處理程序的高階函數(errorHandler) 獲得為Next.js 量身定制的類似中間件的行為，在路由級別攔截和管理錯誤：

npm install nextjs-centralized-error-handler
# or
yarn add nextjs-centralized-error-handler

使用 nextjs-centralized-error-handler，您可以避免在每個路由中重複的錯誤處理程式碼。相反，自訂錯誤類別和 errorHandler 高階函數提供集中、一致的錯誤回應，從而簡化維護並在整個應用程式中擴展錯誤處理。

---

特徵

1. 集中錯誤處理

• 高階錯誤處理：此套件使用高階函數 errorHandler 來集中所有 API 路由的錯誤處理。 errorHandler 不需要重複的 try-catch 區塊，而是攔截錯誤，確保前端整合具有一致的 JSON 格式的回應結構。

2. 結構化自訂錯誤類

• 可自訂的 HTTP 錯誤類別：該套件包含預先定義的類別，例如 BadRequestError、UnauthorizedError 和 NotFoundError，每個類別都會對應到適當的 HTTP 狀態碼。這種方法提高了程式碼可讀性並減少了冗餘，允許開發人員透過擴展 CustomError 基類來建立其他自訂錯誤類型。

3. JSON 序列化和前端相容性

• 錯誤類型元資料：序列化錯誤回應包含錯誤類型等元數據，使前端能夠一致地處理特定錯誤。這透過提供清晰、可操作的回饋來增強用戶體驗，同時也確保敏感的伺服器詳細資訊不會暴露。

---

背景

什麼是錯誤處理？

錯誤處理可確保應用程式可以優雅地回應意外情況（例如無效輸入、缺乏存取權限）。具有強大錯誤處理功能的應用程式不會崩潰，而是會向使用者提供有用的回饋並記錄錯誤以進行偵錯。

Next.js API 路由中的挑戰

Next.js API 路由支援全域中間件方法，但它們本身並不支援像 Express 那樣的特定於路由的細粒度錯誤處理。否則，每個路由處理程序都需要單獨的錯誤管理，從而導致冗餘代碼和不一致的錯誤回應。 nextjs-centralized-error-handler 透過提供一個高階函數 errorHandler 來解決這個問題，該函數包裝路由處理程序以確保在路由層級進行一致且集中的錯誤處理。

---

安裝

使用 npm

npm install nextjs-centralized-error-handler
# or
yarn add nextjs-centralized-error-handler

使用紗線

// pages/api/example.js

const { errorHandler, BadRequestError } = require('nextjs-centralized-error-handler');

const handler = async (req, res) => {
  if (!req.body.name) {
    throw new BadRequestError('Name is required.');
  }

  res.status(200).json({ message: 'Success' });
};

export default errorHandler(handler);

---

用法

基本設定

將 errorHandler 和自訂錯誤類別匯入到您的 Next.js API 路由中：

const handler = async (req, res) => {
  // Your logic here
};

const options = {
  logger: customLoggerFunction,
  defaultMessage: 'Something went wrong!',
  formatError: (error, req) => ({
    message: error.message,
    type: error.name,
    timestamp: new Date().toISOString(),
  }),
};

export default errorHandler(handler, options);

自訂錯誤類別

該套件包含幾個預先定義的錯誤類別：

• 錯誤請求錯誤 (400)
• 未經授權錯誤 (401)
• 禁止錯誤 (403)
• 未發現錯誤 (404)
• 方法不允許錯誤 (405)
• 內部伺服器錯誤 (500)
• 付款要求錯誤 (402)
• 不可接受的錯誤 (406)
• 請求超時錯誤 (408)
• PayloadTooLargeError (413)
• 太多請求錯誤 (429)
• 錯誤網關錯誤 (502)
• 服務不可用錯誤 (503)
• 網關逾時錯誤 (504)
• 儲存空間不足錯誤 (507)
• 頻寬限制超出錯誤 (509)
• NetworkAuthenticationRequiredError (511)

這些類別簡化了錯誤創建，無需在每個路由中硬編碼狀態代碼：

// middleware.js (placed at the root of the app)

import { NextResponse } from 'next/server';

export function middleware(req) {
  // Example of request validation or general logging
  if (!req.headers.get('Authorization')) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
  }

  return NextResponse.next(); // Continue to the route handler
}

// Optional: Configure route matching
export const config = {
  matcher: '/api/:path*', // Applies middleware only to /api/* routes
};

預設訊息的用法範例

如果您只是實例化錯誤而不指定訊息，則它預設為預先定義的、使用者友好的訊息。

// middleware.js

import { NextResponse } from 'next/server';

export function middleware(req) {
  try {
    // You can include any logic here that might throw an error
    return NextResponse.next(); // Proceed to the route handler
  } catch (error) {
    // Handle the error and return an appropriate response
    return NextResponse.json({ error: 'An error occurred while processing your request.' }, { status: 500 });
  }
}

建立自訂錯誤

為了滿足預定義類別之外的特定需求，該套件被設計為可擴展的，允許您為高級用例創建獨特的自訂錯誤。您可以擴展 CustomError 基類來定義您自己的錯誤類型，根據特定的業務邏輯進行自訂。以下是您可能創建的自訂錯誤的一些範例：

• HTTPVersionNotSupportedError (505)
• 未實現錯誤 (501)
• VariantAlsoNegotiatesError (506)
• 衝突錯誤 (409)

例子

// pages/api/example.js

const handler = async (req, res) => {
  if (!req.body.name) {
    throw new Error('Name is required.'); // This will not be caught by middleware
  }

  res.status(200).json({ message: `Hello, ${req.body.name}!` });
};

export default handler;

此範例定義了一個自訂的 ConflictError (HTTP 409)，在發生資源衝突的情況下可能會拋出該錯誤。建立自訂錯誤使您能夠有效地處理獨特的業務邏輯或特定於應用程式的需求。

---

將 nextjs-centralized-error-handler 與 App Router 結合使用

除了支援傳統的 API 路由之外，nextjs-centralized-error-handler 還可以與 Next.js 13 中引入的 App Router 一起使用。以下是如何使用該套件在 App Router 中實現錯誤處理。

範例：將 nextjs-centralized-error-handler 與 App Router 結合使用

建立帶有錯誤處理的路由

您可以在 App Router 中建立路由並使用錯誤處理程序來有效管理錯誤。

npm install nextjs-centralized-error-handler
# or
yarn add nextjs-centralized-error-handler

解釋

• 處理函數：處理函數處理傳入的請求。它檢查名稱參數，如果遺失則拋出 BadRequestError。
• 錯誤處理：處理程序由 errorHandler 包裝，它捕獲執行期間拋出的任何錯誤並返回結構化錯誤回應。

App Router 中的錯誤處理

使用 App Router 可以以乾淨、結構化的方式來管理錯誤，同時利用 nextjs-centralized-error-handler 的強大功能。透過將兩者結合起來，您可以確保您的應用程式有效地處理錯誤，無論使用哪種路由方法。

---

自訂錯誤處理行為

除了自訂錯誤之外，該套件還允許開發人員透過以下方式完全控制錯誤處理的行為：

• 自訂日誌記錄：您可以插入任何日誌記錄功能來追蹤錯誤。這包括整合外部服務（例如 Sentry、LogRocket）或自訂記錄器。
• 錯誤訊息格式：使用formatError新增自訂欄位（例如requestId、時間戳記）。
• 預設狀態和訊息：控制未處理錯誤的預設值，確保使用者友善的回饋而不暴露伺服器詳細資訊。

錯誤處理選項

您可以使用自訂日誌記錄、錯誤格式和預設訊息的選項來配置 errorHandler：

// pages/api/example.js

const { errorHandler, BadRequestError } = require('nextjs-centralized-error-handler');

const handler = async (req, res) => {
  if (!req.body.name) {
    throw new BadRequestError('Name is required.');
  }

  res.status(200).json({ message: 'Success' });
};

export default errorHandler(handler);

formatError 的其他範例

formatError 函數非常靈活，可讓您建立符合應用程式要求的詳細且結構化的錯誤回應。以下是一些範例配置，展示了 formatError 的多功能性：

新增用戶和請求訊息

const handler = async (req, res) => {
  // Your logic here
};

const options = {
  logger: customLoggerFunction,
  defaultMessage: 'Something went wrong!',
  formatError: (error, req) => ({
    message: error.message,
    type: error.name,
    timestamp: new Date().toISOString(),
  }),
};

export default errorHandler(handler, options);

包括用於開發的詳細堆疊跟踪

// middleware.js (placed at the root of the app)

import { NextResponse } from 'next/server';

export function middleware(req) {
  // Example of request validation or general logging
  if (!req.headers.get('Authorization')) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
  }

  return NextResponse.next(); // Continue to the route handler
}

// Optional: Configure route matching
export const config = {
  matcher: '/api/:path*', // Applies middleware only to /api/* routes
};

整合應用程式元數據

// middleware.js

import { NextResponse } from 'next/server';

export function middleware(req) {
  try {
    // You can include any logic here that might throw an error
    return NextResponse.next(); // Proceed to the route handler
  } catch (error) {
    // Handle the error and return an appropriate response
    return NextResponse.json({ error: 'An error occurred while processing your request.' }, { status: 500 });
  }
}

自訂錯誤回應

formatError 函數可以根據您的要求靈活地添加或省略字段，從而輕鬆產生結構化、資訊豐富的錯誤回應。這些選項使開發人員能夠標準化其 API 中的錯誤訊息傳遞和可追溯性，使該套件能夠適應不同的應用程式。

---

安全考慮

全面的異常處理

errorHandler 高階函數單獨包裝每個路由處理程序，捕捉所有異常（包括預期的和意外的），而不需要重複的 try-catch 區塊。這種方法確保即使是第三方或不可預見的錯誤也能被攔截，從而在所有路由上實現一致且安全的錯誤回應。

防止資訊洩漏

為了保護敏感數據，我們的軟體包區分故意的已知錯誤（例如 CustomError 實例）和意外錯誤：

• 僅限自訂錯誤：僅作為CustomError（或其子類別）實例建立的錯誤在客戶端回應中包含其狀態代碼和訊息，為已知問題提供清晰、使用者友善的錯誤回饋。

• 意外錯誤的通用處理：對於不是CustomError 實例的錯誤（例如第三方函式庫問題或不可預見的伺服器錯誤），errorHandler 會自動套用狀態碼500 和一般訊息（“發生內部伺服器錯誤」）。這可以防止敏感資訊無意中暴露給客戶。

用於安全性和監控的可自訂日誌記錄

在保持對客戶端的回應安全和通用的同時，errorHandler 也支援伺服器端日誌記錄。這允許在內部記錄和監控意外錯誤，而無需向客戶端透露詳細信息，從而將安全性與有效的錯誤追蹤相結合。

範例：安全處理意外錯誤

考慮一個依賴第三方函式庫的 API 路由，這可能會引發我們無法預測的錯誤：

npm install nextjs-centralized-error-handler
# or
yarn add nextjs-centralized-error-handler

幕後發生了什麼

如果thirdPartyLibrary.doSomething()拋出一個不是CustomError的錯誤，errorHandler將：

1. 將 statusCode 設定為 500（或配置的預設StatusCode）。
2. 將訊息設定為「發生內部伺服器錯誤。請稍後再試。」（或預設訊息，如果已配置）。
3. 防止資訊外洩：確保不會將敏感詳細資訊（例如原始錯誤訊息或堆疊追蹤）傳送到客戶端。
4. 記錄錯誤伺服器端：使用提供的記錄器進行內部監控來記錄錯誤。

錯誤處理策略注意事項

errorHandler 函數區分自訂錯誤和意外錯誤：

• 自訂錯誤（CustomError 實例）：您定義的特定狀態代碼和訊息將發送到用戶端，為已知問題提供清晰且用戶友好的回饋。
• 其他錯誤：使用預設的狀態碼和訊息來防止意外錯誤導致資訊外洩。

透過以這種方式捕獲所有錯誤，nextjs-centralized-error-handler 提供了專為Next.js 應用程式量身定制的強大、安全且統一的錯誤處理解決方案，並具有內建保護功能以防止意外資料外洩。

---

範例

以下真實場景示範了 nextjs-centralized-error-handler 如何簡化各種用例的錯誤處理。

注意：如果在沒有特定訊息的情況下實例化錯誤，則會自動提供預設的、使用者友善的訊息。

1. 處理不同的HTTP方法

用例：確保 API 路由僅允許使用特定的 HTTP 方法（例如 POST），並在方法不正確時提供有意義的錯誤訊息。

在此範例中，如果傳入要求使用 POST 以外的任何方法，則會拋出 MethodNotAllowedError，以確保一致、使用者友好的回饋。如果未提供自訂訊息，則將使用預設訊息「不允許使用方法」。

npm install nextjs-centralized-error-handler
# or
yarn add nextjs-centralized-error-handler

2. 驗證請求參數

用例：檢查請求中是否存在所需參數，如果驗證失敗，則傳回結構化錯誤。

這裡，當缺少必要的參數（名稱）時，會拋出 BadRequestError 。如果未指定自訂訊息，則使用預設訊息「您的請求似乎有錯誤」。

// pages/api/example.js

const { errorHandler, BadRequestError } = require('nextjs-centralized-error-handler');

const handler = async (req, res) => {
  if (!req.body.name) {
    throw new BadRequestError('Name is required.');
  }

  res.status(200).json({ message: 'Success' });
};

export default errorHandler(handler);

3. 處理未授權訪問

用例：僅限制授權使用者的存取。如果使用者未通過身份驗證，則回應 UnauthorizedError 以表示未經授權的存取。

在此範例中，UnauthorizedError 用於確保只有經過驗證的使用者才能存取該路由。如果沒有提供自訂訊息，則預設為「未經授權的存取。請登入。」

const handler = async (req, res) => {
  // Your logic here
};

const options = {
  logger: customLoggerFunction,
  defaultMessage: 'Something went wrong!',
  formatError: (error, req) => ({
    message: error.message,
    type: error.name,
    timestamp: new Date().toISOString(),
  }),
};

export default errorHandler(handler, options);

4. 強制有效負載限制

用例：拒絕包含超過定義大小的有效負載的請求，有助於防止誤用或拒絕服務攻擊。

如果有效負載超過特定限制，則會拋出 PayloadTooLargeError 來通知客戶端。如果沒有自訂訊息，將顯示預設訊息「請求實體太大」。

// middleware.js (placed at the root of the app)

import { NextResponse } from 'next/server';

export function middleware(req) {
  // Example of request validation or general logging
  if (!req.headers.get('Authorization')) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
  }

  return NextResponse.next(); // Continue to the route handler
}

// Optional: Configure route matching
export const config = {
  matcher: '/api/:path*', // Applies middleware only to /api/* routes
};

5. 自訂錯誤回應（進階）

如果您想包含其他元資料或自訂錯誤回應，nextjs-centralized-error-handler 允許您定義 formatError 函數。可以自訂此函數以包含額外的字段，例如請求路徑或時間戳記。

有關完整詳細信息，請參閱自訂錯誤處理行為部分。這是一個簡單的例子：

// middleware.js

import { NextResponse } from 'next/server';

export function middleware(req) {
  try {
    // You can include any logic here that might throw an error
    return NextResponse.next(); // Proceed to the route handler
  } catch (error) {
    // Handle the error and return an appropriate response
    return NextResponse.json({ error: 'An error occurred while processing your request.' }, { status: 500 });
  }
}

---

與日誌記錄服務集成

為了增強可觀察性，nextjs-centralized-error-handler 支援透過任何服務（例如 Sentry、Datadog 或自訂日誌記錄解決方案）進行自訂日誌記錄。透過向errorHandler傳遞一個日誌函數（如Sentry.captureException），可以即時監控錯誤，同時確保安全性和效率。

什麼是自訂記錄器？

「自訂記錄器」是您提供給 errorHandler 以在伺服器端記錄錯誤的任何日誌記錄函數或外部服務（例如 console.log、Sentry.captureException 或自訂實作）。此日誌記錄功能不是 nextjs-centralized-error-handler 本身的一部分，但該套件旨在與您選擇的記錄器無縫整合。

安全日誌記錄的最佳實踐

• 避免記錄敏感資料：確保您的自訂記錄器不會無意中記錄敏感使用者數據，例如憑證或個人詳細資料。僅將日誌限制為基本錯誤訊息，以維護安全性並符合資料保護標準。

使用 Sentry 增強日誌記錄

如果您使用流行的監控工具 Sentry，您可以將其與此套件整合以進行生產錯誤追蹤：

關於 Sentry 的注意事項：Sentry 幫助開發人員即時追蹤、除錯和解決問題。將 Sentry 與 nextjs-centralized-error-handler 集成，您可以記錄生產中的錯誤，從而深入了解故障發生的位置和原因，而不會暴露敏感細節。

下面的範例示範如何使用 Sentry 的 captureException 函數作為帶有 errorHandler 的記錄器。

npm install nextjs-centralized-error-handler
# or
yarn add nextjs-centralized-error-handler

此設定捕獲錯誤以進行監控，同時防止向客戶洩露敏感資訊。透過利用自訂記錄器，nextjs-centralized-error-handler 將強大的安全性與有效的錯誤追蹤相結合，確保安全且可觀察的應用程式環境。

---

社群回饋和穩定性

由於這個包是新發布的，我意識到生產環境中穩定性的重要性。雖然我已經進行了測試，但現實世界的使用情況和社群的回饋對於識別任何潛在問題並進一步改進軟體包至關重要。

我鼓勵開發者將 nextjs-centralized-error-handler 整合到他們的專案中並分享他們的經驗。無論是錯誤報告、改進建議，還是只是分享它如何幫助簡化應用程式中的錯誤管理，您的回饋都是非常寶貴的。我們可以一起增強這個包，並使其對 Next.js 社群更加有效。

---

優勢一覽

• 專為 Next.js 客製化：透過集中錯誤處理來處理 Next.js API 路由限制。
• 自訂錯誤類別：用於結構化錯誤管理的預先定義和可擴充類別。
• JSON 格式的回應：前端相容且元資料豐富的錯誤訊息。
• 可自訂日誌記錄：與第三方日誌服務整合以進行錯誤監控。
• 無縫整合：快速適應現有的 Next.js 應用程式。

---

結論：

我希望 nextjs-centralized-error-handler 能夠極大地增強 Next.js 開發人員的錯誤管理，提供全面且用戶友好的方法來處理錯誤。透過集中錯誤管理、利用自訂錯誤類別以及與日誌記錄服務順利集成，該套件解決了 Next.js 應用程式開發中的常見痛點。

我邀請 dev.to 社群提供回饋並為該專案做出貢獻，因為您的見解對於完善此套件非常寶貴。您可以在 npm 上查看該軟體包並探索 GitHub 儲存庫以獲取更多詳細資訊！

探索該軟體包並為其開發做出貢獻：

• 在 npm 上查看
• 在 GitHub 上查看

您的意見對於識別問題和增強穩定性至關重要。我鼓勵您嘗試 nextjs-centralized-error-handler 並分享您的經驗。我們可以共同為 Next.js 社群推進這個軟體包。

感謝您的支持，我很高興聽到您的想法和經歷！

以上是使用全面的開發人員解決方案有效管理 Next.js 中的錯誤的詳細內容。更多資訊請關注PHP中文網其他相關文章！