هندل کردن خطا

قرارداد فایل error.js به شما امکان می دهد خطاهای اجرایی غیرمنتظره در مسیرهای تو در تو را به طور ظریفی مدیریت کنید.

• به طور خودکار یک بخش مسیر و فرزندان تو در توی آن را در یک "محدوده خطای React" React Error Boundary (opens in a new tab) محصور کنید.
• با استفاده از سلسله مراتب file-system برای تنظیم دانه دانه بودن، یک رابط کاربری خطا error UI برای بخش های خاص ایجاد کنید.
• خطاها را در بخش های آسیب دیده جدا کنید و بقیه برنامه را عملکردی نگه دارید.
• قابلیت هایی را برای تلاش برای بازیابی از خطا بدون بارگذاری مجدد کامل صفحه اضافه کنید.

با اضافه کردن یک فایل error.js درون یک بخش مسیر و خروج یک کامپوننت React، یک رابط کاربری خطا ایجاد کنید:

'use client' // Error components must be Client Components
 
import { useEffect } from 'react'
 
export default function Error({
	error,
	reset,
}: {
	error: Error & { digest?: string }
	reset: () => 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 trying to re-render the segment
					() => reset()
				}
			>
				Try again
			</button>
		</div>
	)
}

فایل error.js چگونه کار می کند؟

• فایل error.js به طور خودکار یک مرز خطای React (opens in a new tab) ایجاد می کند که یک بخش فرزند تو در تو یا کامپوننت page.js را در بر wraps می گیرد.
• کامپوننت React خروجی گرفته شده از فایل error.js به عنوان کامپوننت fallback استفاده می شود.
• اگر خطایی درون مرز خطا پرتاب شود، خطا محدود می شود و کامپوننت رزرو fallback رندر می شود.
• هنگامی که کامپوننت خطای رزرو fallback error component فعال است، طرح بندی های بالای محدوده خطا وضعیت خود را حفظ می کنند و همچنان تعاملی باقی می مانند و کامپوننت خطا می تواند قابلیت هایی را برای بازیابی از خطا نمایش دهد.

بازیابی از خطاها

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

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

'use client'
 
export default function Error({
	error,
	reset,
}: {
	error: Error & { digest?: string }
	reset: () => void
}) {
	return (
		<div>
			<h2>Something went wrong!</h2>
			<button onClick={() => reset()}>Try again</button>
		</div>
	)
}

مسیرهای تو در تو

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

به عنوان مثال، یک مسیر تو در تو با دو بخش که هر دو شامل فایل های layout.js و error.js هستند، در سلسله مراتب کامپوننت ساده شده زیر رندر می شوند:

سلسله مراتب کامپوننت تو در تو بر رفتار فایل های error.js در یک مسیر تو در تو تأثیر می گذارد:

• خطاها به نزدیک ترین "محدوده خطای والد" (parent error boundary) منتقل می شوند. این بدان معنی است که یک فایل error.js خطاها را برای تمام بخش های فرزند تو در توی خود مدیریت می کند. با قرار دادن فایل های error.js در سطوح مختلف پوشه های تو در تو مسیر، می توان رابط کاربری خطا با دانه بندی بیشتر یا کمتر به دست آورد.
• یک محدوده error.js خطاهایی را که در یک کامپوننت layout.js در همان بخش پرتاب می شود را مدیریت نمی کند زیرا محدوده خطا در داخل کامپوننت آن طرح بندی تو در تو شده است.

هندل کردن خطا در طرح بندی ها

محدوده های error.js خطاهایی را که در کامپوننت های layout.js یا template.js همین بخش پرتاب می شوند را گیر نمی اندازند. این سلسله مراتب عمدی، رابط کاربری مهمی را که بین مسیرهای هم سطح به اشتراک گذاشته می شود (مانند پیمایش) در هنگام بروز خطا، قابل مشاهده و کاربردی نگه می دارد.

برای مدیریت خطاها در یک طرح بندی یا قالب خاص، یک فایل error.js را در بخش والد طرح بندی قرار دهید.

برای مدیریت خطاها در طرح بندی یا قالب ریشه، از نوعی از error.js به نام global-error.js استفاده کنید.

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

محدوده app/error.js ریشه، خطاهایی را که در کامپوننت های ریشه app/layout.js یا app/template.js پرتاب می شوند را گیر نمی اندازد.

برای مدیریت اختصاصی خطاها در این کامپوننت های ریشه، از نوعی از error.js به نام app/global-error.js که در دایرکتوری ریشه app قرار دارد، استفاده کنید.

برخلاف فایل ریشه error.js، محدوده خطای global-error.js کل برنامه را در بر می گیرد و کامپوننت رزرو fallback آن زمانی که فعال باشد، طرح بندی ریشه را جایگزین می کند. به همین دلیل، مهم است که توجه داشته باشید که global-error.js باید تگ های <html> و <body> خاص خود را تعریف کند.

global-error.js کمترین دانه بندی رابط کاربری خطا را دارد و می توان آن را "گیرنده همه catch-all" مدیریت خطا برای کل برنامه در نظر گرفت. بعید است که اغلب فعال شود زیرا کامپوننت های ریشه به طور معمول پویایی کمتری دارند و سایر محدوده های error.js اکثر خطاها را گیر می اندازند.

حتی اگر یک global-error.js تعریف شده باشد، همچنان توصیه می شود یک error.js در ریشه تعریف کنید که کامپوننت رزرو fallback آن در داخل طرح بندی ریشه رندر می شود، که شامل رابط کاربری و برندسازی به اشتراک گذاشته شده جهانی است.

'use client'
 
export default function GlobalError({
	error,
	reset,
}: {
	error: Error & { digest?: string }
	reset: () => void
}) {
	return (
		<html>
			<body>
				<h2>Something went wrong!</h2>
				<button onClick={() => reset()}>Try again</button>
			</body>
		</html>
	)
}

خوب است بدانید:

• global-error.js فقط در محیط تولید production فعال است. در توسعه development، به جای آن، پوشش خطای ما نمایش داده می شود.

هندل کردن خطاهای سمت سرور

اگر خطایی در داخل یک Server Component پرتاب شود، Next.js یک شیء Error (که در محیط production از اطلاعات حساس خطا پاک شده است) را به عنوان error پراپ به نزدیک ترین فایل error.js ارسال می کند.

ایمن سازی اطلاعات حساس خطا

در طول تولید، شیء Error که به سمت کاربر فرستاده می شود، فقط شامل یک message عمومی و یک خاصیت digest است.

این یک اقدام احتیاطی امنیتی برای جلوگیری از افشای جزئیات بالقوه حساس موجود در خطا به کاربر است.

خاصیت message حاوی یک پیام عمومی در مورد خطا است و خاصیت digest حاوی یک هش (hash) به طور خودکار تولید شده از خطا است که می تواند برای مطابقت با خطای مربوطه در لاگ های سمت سرور استفاده شود.

در طول توسعه، شیء Error که به سمت کاربر ارسال می شود، سریال سازی شده و شامل message خطای اصلی برای اشکال زدایی آسان تر خواهد بود.