خانه / مستندات / Next JS / مدیریت خطاها / مدیریت خطاهای پیش بینی نشده

مدیریت خطاهای پیش بینی نشده

استثناهای پیش‌بینی‌نشده، خطاهای غیرمنتظره‌ای هستند که نشان‌دهنده باگ یا مشکلی در برنامه می‌باشند و نباید در روند عادی اجرا رخ دهند. این خطاها باید با استفاده از throw ایجاد شوند تا توسط مرزهای خطا (Error Boundaries) شناسایی و مدیریت گردند.

مرزهای خطای تودرتو (Nested Error Boundaries)

فریم‌ورک Next.js برای مدیریت این خطاها از Error Boundaries استفاده می‌کند. این مرزها، خطاهای رخ‌داده در کامپوننت‌های فرزند (Child Components) را شناسایی کرده و به جای کرش کردن کل درخت کامپوننت، یک رابط کاربری جایگزین (Fallback UI) نمایش می‌دهند.

برای ایجاد یک Error Boundary، کافی است یک فایل error.tsx در داخل یک Route Segment ایجاد کرده و یک کامپوننت React را از آن اکسپورت کنید:

// app/dashboard/error.tsx
'use client' // Error boundaries must be Client Components
 
import { useEffect } from 'react'
 
export default function ErrorPage({
  error,
  unstable_retry,
}: {
  error: Error & { digest?: string }
  unstable_retry: () => void
}) {
  useEffect(() => {
    // Log the error to an error reporting service
    console.error(error)
  }, [error])
 
  return (
    <div>
      <h2>Something went wrong!</h2>
      <button
        onClick={
          // Attempt to recover by re-fetching and re-rendering the segment
          () => unstable_retry()
        }
      >
        Try again
      </button>
    </div>
  )
}

خطاها به سمت بالاترین مرز خطای والد (Nearest Parent Error Boundary) سرریز (Bubble up) می‌شوند. این ویژگی به شما اجازه می‌دهد با قرار دادن فایل‌های error.tsx در سطوح مختلف ساختار مسیرها، خطاها را با دقت و جزئیات کامل مدیریت کنید.

💥 خطا در Sub-Component رخ می‌دهد
│
▼
❌ Dashboard Widget کرش می‌کند
│
▼
❌ صفحه dashboard/page.tsx کرش می‌کند
│
▼
🛡️ 📄 dashboard/error.tsx خطا را می‌گیرد!
│
▼
✅ نمایش Fallback UI به جای بخش کرش‌شده
│
▼
✅ بقیه برنامه (Header, Stats, Settings) سالم می‌مانند

برای مدیریت خطا در سطح کامپوننت، تابع unstable_catchError به شما اجازه می‌دهد Error Boundaryهایی بسازید که بتوانند هر بخشی از درخت کامپوننت شما را پوشش دهند:

// app/custom-error-boundary.tsx
'use client'
 
import { unstable_catchError as catchError, type ErrorInfo } from 'next/error'
 
function ErrorFallback(
  props: { title: string },
  { error, unstable_retry }: ErrorInfo
) {
  return (
    <div>
      <h2>{props.title}</h2>
      <p>{error.message}</p>
      <button onClick={() => unstable_retry()}>Try again</button>
    </div>
  )
}
 
export default catchError(ErrorFallback)

سپس از کامپوننت برگشتی به عنوان یک Wrapper در هر Layout یا Page استفاده کنید:

// app/some-component.tsx
import ErrorBoundary from './custom-error-boundary'
 
export default function Component({ children }: { children: React.ReactNode }) {
  return <ErrorBoundary title="Dashboard Error">{children}</ErrorBoundary>
}

توجه بسیار مهم: مرزهای خطا، خطاهای داخل Event Handlerها را شناسایی نمی‌کنند. طراحی آن‌ها فقط برای گرفتن خطاهای حین رندر (Rendering) است تا به جای کرش کل برنامه، یک UI جایگزین نمایش داده شود.

به طور کلی، خطاهای موجود در Event Handlerها یا کدهای ناهمگام (Async)، توسط Error Boundaryها مدیریت نمی‌شوند، زیرا این خطاها بعد از مرحله رندر اجرا می‌شوند.

برای مدیریت این موارد، باید خطا را به صورت دستی (Manually) گرفته و با استفاده از useState یا useReducer ذخیره کنید، سپس رابط کاربری را برای اطلاع‌رسانی به کاربر به‌روزرسانی نمایید.

'use client'
 
import { useState } from 'react'
 
export function Button() {
  const [error, setError] = useState(null)
 
  const handleClick = () => {
    try {
      // do some work that might fail
      throw new Error('Exception')
    } catch (reason) {
      setError(reason)
    }
  }
 
  if (error) {
    /* render fallback UI */
  }
 
  return (
    <button type="button" onClick={handleClick}>
      Click me
    </button>
  )
}

نکته تخصصی: خطاهای مدیریت‌نشده‌ای که در داخل startTransition (از هوک useTransition) رخ می‌دهند، به نزدیک‌ترین Error Boundary سرریز خواهند شد.

'use client'
 
import { useTransition } from 'react'
 
export function Button() {
  const [pending, startTransition] = useTransition()
 
  const handleClick = () =>
    startTransition(() => {
      throw new Error('Exception')
    })
 
  return (
    <button type="button" onClick={handleClick}>
      Click me
    </button>
  )
}

خطاهای سراسری (Global Errors)

اگرچه کمتر رایج است، اما شما می‌توانید خطاها را در Root Layout و با استفاده از فایل global-error.tsx (که در پوشه ریشه app قرار دارد) مدیریت کنید؛ حتی زمانی که از بین‌المللی‌سازی (Internationalization) استفاده می‌کنید.

رابط کاربری خطای سراسری باید تگ‌های <html> و <body> مخصوص به خود را تعریف کند، زیرا هنگام فعال شدن، جایگزین Root Layout یا Template اصلی می‌شود.

// app/global-error.tsx
'use client' // Error boundaries must be Client Components
 
export default function GlobalError({
  error,
  unstable_retry,
}: {
  error: Error & { digest?: string }
  unstable_retry: () => void
}) {
  return (
    // global-error must include html and body tags
    <html>
      <body>
        <h2>Something went wrong!</h2>
        <button onClick={() => unstable_retry()}>Try again</button>
      </body>
    </html>
  )
}

این محتوا کاملا رایگان توسط تیم کدلپر ترجمه شده و در اختیار شما کاربران عزیز قرار گرفته است، هر گونه کپی برداری برای مقاصد غیر رایگان و بدون ذکر منبع، مورد پیگیری قانونی قرار میگیرد.

ترجمه شده از منبع: https://nextjs.org/docs/app