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

تتيح لك اتفاقية ملف 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>
  )
}

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

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

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

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

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

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

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