۱. error.js — مدیریت خطاهای زمان اجرا
فایل error.js به‌عنوان Error Boundary عمل می‌کند و هنگام بروز خطا در یک segment، UI جایگزین نمایش می‌دهد.
'use client'
export default function Error({ error, reset }) {
useEffect(() => {
console.error(error)
}, [error])
return (
<div>
<h2>Something went wrong!</h2>
<button onClick={() => reset()}>Try again</button>
</div>
)
}ویژگی‌ها:
- error.message: پیام خطا برای دیباگ
- error.digest: شناسه هش برای تطبیق با لاگ‌های سرور
- reset(): تلاش برای رندر مجدد segment
۲. global-error.jsx — مدیریت خطای سراسری
برای مدیریت خطا در سطح root layout، از فایل global-error.tsx استفاده کنید. این فایل باید شامل تگ‌های html و body باشد.
'use client'
export default function GlobalError({ error, reset }) {
return (
<html>
<body>
<h2>Something went wrong!</h2>
<button onClick={() => reset()}>Try again</button>
</body>
</html>
)
}۳. GracefullyDegradingErrorBoundary — بازیابی ظریف
این کامپوننت HTML فعلی را قبل از خطا ذخیره کرده و در صورت بروز خطا، آن را بدون hydration نمایش می‌دهد.
if (this.state.hasError) {
return (
<>
<div dangerouslySetInnerHTML={{ __html: cachedHTML }} />
<div className="notification">An error occurred</div>
</>
)
}۴. forbidden.js — نمایش صفحه 403
فایل forbidden.js برای نمایش UI هنگام فراخوانی تابع forbidden() در فرآیند احراز هویت استفاده می‌شود.
export default function Forbidden() {
return (
<div>
<h2>Forbidden</h2>
<p>You are not authorized to access this resource.</p>
<Link href="/">Return Home</Link>
</div>
)
}۵. instrumentation.js — مشاهده‌پذیری و ردیابی خطاها
فایل instrumentation.ts برای ثبت عملکرد سرور و گزارش خطاها استفاده می‌شود.
export function register() {
registerOTel('next-app')
}
export const onRequestError = async (err, request, context) => {
await fetch('https://.../report-error', {
method: 'POST',
body: JSON.stringify({ message: err.message, request, context }),
headers: { 'Content-Type': 'application/json' },
})
}پارامترها:
- error.digest: شناسه خطا
- request: اطلاعات مسیر، متد، و headerها
- context: نوع router، نوع route، منبع render، و دلیل revalidation
۶. تعیین runtime
برای اجرای متفاوت در Node.js یا Edge:
if (process.env.NEXT_RUNTIME === 'edge') {
return require('./register.edge')
} else {
return require('./register.node')
}جمع‌بندی
Next.js با ابزارهایی مانند error.js، forbidden.js و instrumentation.js امکان مدیریت خطا، کنترل دسترسی، و نظارت دقیق را فراهم می‌کند. این ابزارها تجربه کاربری را بهبود می‌بخشند و توسعه‌دهندگان را در ساخت اپلیکیشن‌های مقاوم و قابل اعتماد یاری می‌دهند.