معالجة الأخطاء

تسمح لك اتفاقية ملف error.js بالتعامل مع أخطاء وقت التشغيل غير المتوقعة بطريقة أنيقة في المسارات المتداخلة.

• تغليف مقطع المسار وأطفاله المتداخلين تلقائيًا في حدود خطأ React.
• إنشاء واجهة مستخدم للأخطاء مخصصة لمقاطع محددة باستخدام التسلسل الهرمي لنظام الملفات لضبط الدقة.
• عزل الأخطاء للمقاطع المتأثرة مع الحفاظ على بقية التطبيق يعمل.
• إضافة وظيفة لمحاولة الاسترداد من الخطأ دون إعادة تحميل كامل للصفحة.

قم بإنشاء واجهة مستخدم للأخطاء عن طريق إضافة ملف error.js داخل مقطع مسار وتصدير مكون React:

'use client' // مكونات الخطأ يجب أن تكون مكونات عميل

import { useEffect } from 'react'

export default function Error({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  useEffect(() => {
    // تسجيل الخطأ في خدمة إعداد التقارير عن الأخطاء
    console.error(error)
  }, [error])

  return (
    <div>
      <h2>حدث خطأ ما!</h2>
      <button
        onClick={
          // محاولة الاسترداد عن طريق إعادة عرض المقطع
          () => reset()
        }
      >
        حاول مرة أخرى
      </button>
    </div>
  )
}

'use client' // مكونات الخطأ يجب أن تكون مكونات عميل

import { useEffect } from 'react'

export default function Error({ error, reset }) {
  useEffect(() => {
    // تسجيل الخطأ في خدمة إعداد التقارير عن الأخطاء
    console.error(error)
  }, [error])

  return (
    <div>
      <h2>حدث خطأ ما!</h2>
      <button
        onClick={
          // محاولة الاسترداد عن طريق إعادة عرض المقطع
          () => reset()
        }
      >
        حاول مرة أخرى
      </button>
    </div>
  )
}

كيف يعمل error.js

• ينشئ error.js تلقائيًا حدود خطأ React التي تغلف مقطع طفل متداخل أو مكون page.js.
• يتم استخدام مكون React المصدر من ملف error.js كمكون احتياطي.
• إذا تم طرح خطأ داخل حدود الخطأ، يتم احتواء الخطأ ويتم عرض المكون الاحتياطي.
• عندما يكون مكون الخطأ الاحتياطي نشطًا، تحافظ التخطيطات فوق حدود الخطأ على حالتها وتبقى تفاعلية، ويمكن لمكون الخطأ عرض وظيفة للاسترداد من الخطأ.

الاسترداد من الأخطاء

قد يكون سبب الخطأ مؤقتًا في بعض الأحيان. في هذه الحالات، قد تحل محاولة بسيطة للمحاولة مرة أخرى المشكلة.

يمكن لمكون الخطأ استخدام دالة reset() لدفع المستخدم لمحاولة الاسترداد من الخطأ. عند التنفيذ، ستقوم الدالة بمحاولة إعادة عرض محتويات حدود الخطأ. إذا نجحت، يتم استبدال مكون الخطأ الاحتياطي بنتيجة إعادة العرض.

'use client'

export default function Error({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  return (
    <div>
      <h2>حدث خطأ ما!</h2>
      <button onClick={() => reset()}>حاول مرة أخرى</button>
    </div>
  )
}

'use client'

export default function Error({ error, reset }) {
  return (
    <div>
      <h2>حدث خطأ ما!</h2>
      <button onClick={() => reset()}>حاول مرة أخرى</button>
    </div>
  )
}

المسارات المتداخلة

يتم عرض مكونات React التي تم إنشاؤها من خلال ملفات خاصة في تسلسل هرمي متداخل محدد.

على سبيل المثال، يتم عرض مسار متداخل مع مقطعين يحتويان على ملفات layout.js و error.js في التسلسل الهرمي للمكونات المبسط التالي:

يحتوي التسلسل الهرمي للمكونات المتداخلة على آثار لسلوك ملفات error.js عبر مسار متداخل:

• تنتقل الأخطاء إلى أقرب حدود خطأ أصلية. هذا يعني أن ملف 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 التطبيق بالكامل، ويستبدل مكونها الاحتياطي التخطيط الجذري عند التنشيط. بسبب هذا، من المهم ملاحظة أن global-error.js يجب أن يحدد علامات <html> و <body> الخاصة به.

يعتبر global-error.js أقل واجهة مستخدم للأخطاء دقة ويمكن اعتباره معالجة أخطاء "شاملة" للتطبيق بأكمله. من غير المحتمل أن يتم تشغيله كثيرًا لأن المكونات الجذرية عادةً ما تكون أقل ديناميكية، وستلتقط حدود error.js الأخرى معظم الأخطاء.

حتى إذا تم تعريف global-error.js، لا يزال يوصى بتحديد error.js جذري سيتم عرض مكونه الاحتياطي داخل التخطيط الجذري، والذي يتضمن واجهة مستخدم وعلامة تجارية مشتركة عالميًا.

'use client'

export default function GlobalError({
  error,
  reset,
}: {
  error: Error & { digest?: string }
  reset: () => void
}) {
  return (
    <html>
      <body>
        <h2>حدث خطأ ما!</h2>
        <button onClick={() => reset()}>حاول مرة أخرى</button>
      </body>
    </html>
  )
}

'use client'

export default function GlobalError({ error, reset }) {
  return (
    <html>
      <body>
        <h2>حدث خطأ ما!</h2>
        <button onClick={() => reset()}>حاول مرة أخرى</button>
      </body>
    </html>
  )
}

معلومة جيدة:

• يتم تمكين global-error.js فقط في الإنتاج. في التطوير، سيظهر تراكب الخطأ الخاص بنا بدلاً من ذلك.

التعامل مع أخطاء الخادم

إذا تم طرح خطأ داخل مكون خادم، سيقوم Next.js بإعادة توجيه كائن Error (تمت إزالة معلومات الخطأ الحساسة في الإنتاج) إلى أقرب ملف error.js كخاصية error.

تأمين معلومات الخطأ الحساسة

خلال الإنتاج، يتضمن كائن Error المعاد توجيهه إلى العميل خاصية message عامة وخاصية digest فقط.

هذا إجراء أمان لتجنب تسريب تفاصيل حساسة محتملة متضمنة في الخطأ إلى العميل.

تحتوي خاصية message على رسالة عامة حول الخطأ وتحتوي خاصية digest على تجزئة تم إنشاؤها تلقائيًا للخطأ يمكن استخدامها لمطابقة الخطأ المقابل في سجلات جانب الخادم.

خلال التطوير، سيكون كائن Error المعاد توجيهه إلى العميل متسلسلاً وسيتضمن message الخطأ الأصلي لسهولة التصحيح.