我很高興推出一個新的輕量級包，旨在簡化 Next.js 應用程式中的錯誤管理：nextjs-centralized-error-handler。作為開發人員，我們經常遇到錯誤處理方面的挑戰，尤其是在像 Next.js 這樣的框架中，傳統方法可能會導致重複程式碼和被忽視的場景。
從我使用 Yii2 框架的經驗中汲取靈感——內建錯誤類別簡化了錯誤管理，無需硬編碼狀態代碼或訊息——我認識到 Node.js 生態系統中也有類似的需求。這種認識促使在此套件中開發自訂錯誤類，從而增強一致性和可用性。
重要提示：此軟體套件目前處於測試階段。作為一個新發布的工具，您的回饋對於識別潛在問題並提高其穩定性至關重要。我鼓勵您嘗試 nextjs-centralized-error-handler 套件並分享您的見解，無論是透過錯誤報告還是改進建議。我們可以共同為 Next.js 社群加強這個軟體包。
安裝軟體套件
npm install nextjs-centralized-error-handler # or yarn add nextjs-centralized-error-handler
包裝您的 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);
自訂錯誤處理（選購）
npm install nextjs-centralized-error-handler # or yarn add nextjs-centralized-error-handler
Next.js 13 的中間件提供了強大的全域攔截功能，非常適合身份驗證和一般請求驗證等任務。然而，nextjs-centralized-error-handler 透過提供細粒度的路由級控制和中間件本身無法覆蓋的詳細響應來增強錯誤處理。以下是這個包如何補充和擴展 Next.js 中間件：
特定於路由的錯誤管理：使用nextjs-centralized-error-handler，每個路由都可以定義自己的上下文錯誤處理，並使用與路由功能相匹配的定制訊息。這種模組化對於跨不同端點具有不同錯誤處理需求的複雜應用程式至關重要。
具有詳細回應的自訂錯誤類別：該套件引入了具有結構化、前端友好的 JSON 回應的自訂錯誤類別（例如 BadRequestError、UnauthorizedError）。這些回應富含狀態代碼和錯誤類型等元數據，確保後端和前端團隊的錯誤處理可預測且標準化。
增強的安全性和資料隱私：只有故意出現 CustomError 實例的錯誤才會將其狀態代碼和訊息傳送到客戶端。對於意外錯誤，將使用通用錯誤訊息，並將敏感詳細資訊保留在伺服器端，以最大限度地減少資訊外洩。
日誌記錄並與監控工具集成：支援與日誌服務（例如 Sentry、Datadog）集成，實現超出中間件單獨實現的詳細錯誤追蹤和調試。
可自訂和可擴展的錯誤處理：CustomError 類別是完全可擴展的，允許開發人員定義特定於應用程式的錯誤，隨著應用程式的發展創建靈活的錯誤處理策略。
透過將 Next.js 中間件與 nextjs-centralized-error-handler 結合，您可以實現強大且靈活的錯誤處理解決方案，支援全域和特定於路由的需求。
Next.js 13 引入了全域中間件，支援身份驗證和一般驗證等任務的請求級攔截。下面的比較顯示了 Next.js 13 中間件與 nextjs-centralized-error-handler 的不同之處以及何時使用它們。
Next.js 13 中間件可以全域定義並套用於與指定模式相符的所有路由。這對於日誌記錄或授權等高級操作非常有用。
npm install nextjs-centralized-error-handler # or yarn add 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 中間件為進階請求攔截提供了強大的機制，但需要注意的是，中間件在路由處理程序執行之前運行。這意味著處理程序內部拋出的任何異常都不會被中間件捕獲；相反，這將導致向客戶端返回通用的 500 內部伺服器錯誤。相較之下，nextjs-centralized-error-handler 擅長在單一 API 路由中進行細粒度的錯誤處理。本節闡明了它們的不同角色，並示範如何有效地一起使用它們。
假設您正在建立一個 API 路由，需要在請求正文中提供使用者名稱。如果名稱遺失，您需要使用清晰且具體的錯誤訊息進行回應。讓我們看看每種方法如何處理這種情況。
在 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);
這裡發生了什麼事：
相較之下，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);
這裡發生了什麼事：
結合 Next.js 中間件和 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);
說明：
透過使用 Next.js 中介軟體進行請求層級檢查，使用 nextjs-centralized-error-handler 進行回應層級錯誤處理，您可以實現廣泛的驗證和細粒度的錯誤管理。
在傳統的 Node.js/Express 應用程式中，集中式錯誤處理通常透過中介軟體進行管理，中間件會跨路由一致地攔截請求和錯誤。然而，在 Next.js 中，API 路由不以相同的方式支援中間件，這給集中式錯誤處理帶來了挑戰。 nextjs-centralized-error-handler 透過使用高階函數來提供跨所有 API 路由的特定於路由的錯誤處理，從而填補了這一空白。
在 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)，然後觸發集中式錯誤處理中間件以跨路由做出一致的回應。
使用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 高階函數提供集中、一致的錯誤回應，從而簡化維護並在整個應用程式中擴展錯誤處理。
錯誤處理可確保應用程式可以優雅地回應意外情況（例如無效輸入、缺乏存取權限）。具有強大錯誤處理功能的應用程式不會崩潰，而是會向使用者提供有用的回饋並記錄錯誤以進行偵錯。
Next.js API 路由支援全域中間件方法，但它們本身並不支援像 Express 那樣的特定於路由的細粒度錯誤處理。否則，每個路由處理程序都需要單獨的錯誤管理，從而導致冗餘代碼和不一致的錯誤回應。 nextjs-centralized-error-handler 透過提供一個高階函數 errorHandler 來解決這個問題，該函數包裝路由處理程序以確保在路由層級進行一致且集中的錯誤處理。
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);
該套件包含幾個預先定義的錯誤類別：
這些類別簡化了錯誤創建，無需在每個路由中硬編碼狀態代碼：
// 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 基類來定義您自己的錯誤類型，根據特定的業務邏輯進行自訂。以下是您可能創建的自訂錯誤的一些範例：
// 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)，在發生資源衝突的情況下可能會拋出該錯誤。建立自訂錯誤使您能夠有效地處理獨特的業務邏輯或特定於應用程式的需求。
除了支援傳統的 API 路由之外，nextjs-centralized-error-handler 還可以與 Next.js 13 中引入的 App Router 一起使用。以下是如何使用該套件在 App Router 中實現錯誤處理。
您可以在 App Router 中建立路由並使用錯誤處理程序來有效管理錯誤。
npm install nextjs-centralized-error-handler # or yarn add nextjs-centralized-error-handler
使用 App Router 可以以乾淨、結構化的方式來管理錯誤，同時利用 nextjs-centralized-error-handler 的強大功能。透過將兩者結合起來，您可以確保您的應用程式有效地處理錯誤，無論使用哪種路由方法。
除了自訂錯誤之外，該套件還允許開發人員透過以下方式完全控制錯誤處理的行為：
您可以使用自訂日誌記錄、錯誤格式和預設訊息的選項來配置 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 的多功能性：
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將：
errorHandler 函數區分自訂錯誤和意外錯誤：
透過以這種方式捕獲所有錯誤，nextjs-centralized-error-handler 提供了專為Next.js 應用程式量身定制的強大、安全且統一的錯誤處理解決方案，並具有內建保護功能以防止意外資料外洩。
以下真實場景示範了 nextjs-centralized-error-handler 如何簡化各種用例的錯誤處理。
注意：如果在沒有特定訊息的情況下實例化錯誤，則會自動提供預設的、使用者友善的訊息。
用例：確保 API 路由僅允許使用特定的 HTTP 方法（例如 POST），並在方法不正確時提供有意義的錯誤訊息。
在此範例中，如果傳入要求使用 POST 以外的任何方法，則會拋出 MethodNotAllowedError，以確保一致、使用者友好的回饋。如果未提供自訂訊息，則將使用預設訊息「不允許使用方法」。
npm install nextjs-centralized-error-handler # or yarn add nextjs-centralized-error-handler
用例：檢查請求中是否存在所需參數，如果驗證失敗，則傳回結構化錯誤。
這裡，當缺少必要的參數（名稱）時，會拋出 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);
用例：僅限制授權使用者的存取。如果使用者未通過身份驗證，則回應 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);
用例：拒絕包含超過定義大小的有效負載的請求，有助於防止誤用或拒絕服務攻擊。
如果有效負載超過特定限制，則會拋出 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
};
如果您想包含其他元資料或自訂錯誤回應，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 與 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 社群更加有效。
我希望 nextjs-centralized-error-handler 能夠極大地增強 Next.js 開發人員的錯誤管理，提供全面且用戶友好的方法來處理錯誤。透過集中錯誤管理、利用自訂錯誤類別以及與日誌記錄服務順利集成，該套件解決了 Next.js 應用程式開發中的常見痛點。
我邀請 dev.to 社群提供回饋並為該專案做出貢獻，因為您的見解對於完善此套件非常寶貴。您可以在 npm 上查看該軟體包並探索 GitHub 儲存庫以獲取更多詳細資訊！
探索該軟體包並為其開發做出貢獻：
您的意見對於識別問題和增強穩定性至關重要。我鼓勵您嘗試 nextjs-centralized-error-handler 並分享您的經驗。我們可以共同為 Next.js 社群推進這個軟體包。
感謝您的支持，我很高興聽到您的想法和經歷！
以上是使用全面的開發人員解決方案有效管理 Next.js 中的錯誤的詳細內容。更多資訊請關注PHP中文網其他相關文章！
