الانتقال إلى المحتوى الرئيسي

مقدمة

يلتقط Lerix الأخطاء من تطبيق Next.js الخاص بك لتتمكّن من تصحيح المشاكل بشكل أسرع. بعد إتمام تثبيت Next.js، استخدم useLerix().throwError() لإرسال أخطاء مخصّصة إلى لوحة التحكم — أما الأخطاء غير الملتقطة فتُلتقط تلقائياً، دون الحاجة لأي كود إضافي.
تأكّد من أن تطبيقك مغلّف بـ LerixNextProvider قبل الإبلاغ عن الأخطاء.

الإبلاغ عن خطأ

المعاملات (Parameters)

قيم BugType

قيم BugSeverity

الالتقاط التلقائي للأخطاء

يُثبّت LerixNextProvider التقاط الأخطاء بطريقتين، بحيث لا حاجة لتغليف أي شيء في try/catch للحصول على تغطية أساسية:
  • يلتقط LerixErrorBoundary الأخطاء التي تحدث أثناء العرض (rendering) — عقد حدود الأخطاء في React يغطّي فقط مرحلة العرض، وليس معالجات الأحداث أو الكود غير المتزامن.
  • تلتقط مستمعا window.onerror وَ unhandledrejection العامّان كل شيء آخر.
لتعطيل المستمعَين العامَّين (يستمر LerixErrorBoundary في التقاط أخطاء العرض بغضّ النظر عن هذا الخيار):

حدود الأخطاء الخاصة بـ Next.js

يلتقط LerixErrorBoundary فقط الأخطاء الواقعة تحت المكان الذي وضعته فيه. بالنسبة للأخطاء الأعلى من ذلك — وأبرزها في التخطيط الجذري (root layout) نفسه — يتطلّب Next.js حدود أخطاء خاصة به قائمة على الملفات (error.tsx، global-error.tsx). استدعِ reportCaughtError مباشرة داخل هذه الملفات بدلاً من ذلك:
app/error.tsx

الالتقاط التلقائي لتتبّع المكدس

عند استدعاء throwError() دون تمرير معامل stack، يُلتقط تتبّع مكدس تلقائياً من موضع الاستدعاء — لا تحتاج لتمريره صراحةً إلا عند الإبلاغ عن تتبّع مكدس خطأ (Error) ملتقَط بنفسك بدلاً من موضع استدعاء throwError. في الحالتين، يُحلَّل كل إطار من إطارات المكدس من موضعه المُجمَّع إلى ملف المصدر الأصلي وسطره، باستخدام خريطة المصدر الخاصة بالبناء نفسه — بما في ذلك صيغة خريطة المصدر المُقسَّمة (sectioned) الخاصة بـ Turbopack. يحدث هذا تلقائياً؛ لا حاجة لأي إعداد.
يتطلّب التحليل أن تكون خريطة المصدر متاحة على رابط الإطار — وهذا صحيح دائماً في بيئة التطوير، وصحيح في الإنتاج فقط إذا كان بناؤك يقدّم ملفات .map علناً. إذا أبقى بناء الإنتاج خرائط المصدر خاصة، ترجع الإطارات إلى موضعها المُجمَّع بدلاً من فشل الإبلاغ.
لتحصل على تتبّعات مكدس مقروءة في الإنتاج مع إبقاء خرائط المصدر خاصة، ارفعها إلى Lerix بعد كل بناء. راجع خرائط المصدر لـ Next.js.

تحقّق من التكامل

ثم افتح لوحة التحكم — يجب أن يظهر الخطأ خلال ثوانٍ، مع تتبّع مكدس محلَّل يشير إلى هذا السطر بالتحديد.

ترشيح الأخطاء

يتطلّب @lerix-dev/lerix-nextjs بالإصدار 1.3.0 أو أحدث. يحدّد خياران اختياريان في LerixNextProvider الأخطاء التي تُرسَل. ينطبقان على كل تقرير: LerixErrorBoundary، وreportCaughtError في error.tsx، والمعالجات العامة. لا يمكن تمرير الدوال وتعابير RegExp كخصائص (props) من مكوّن خادم (Server Component)، لذا اضبط هذين الخيارين في مكوّن عميل صغير خاص بك. يبقى apiKey وprojectId مأخوذين من متغيّرات البيئة NEXT_PUBLIC_:
app/lerix.tsx
ثم استخدمه في layout.tsx بدلاً من LerixNextProvider:
app/layout.tsx
  • تعمل ignoreErrors أولاً. النص (string) يحذف أي خطأ تحتوي رسالته عليه، دون تمييز حالة الأحرف. والتعبير RegExp يحذف أي خطأ تطابقه رسالته. تُتجاوَز النصوص الفارغة.
  • ثم لا ترى beforeSend إلا ما تبقّى. أعِد الحدث (معدّلاً أو كما هو) لإرساله، أو أعِد null لحذفه. إذا رمت استثناءً، يُرسَل الحدث الأصلي ولا يصل الاستثناء إلى تطبيقك.
  • الرسالة التي تطابقها هي عنوان المشكلة، وتتضمّن صنف الخطأ، مثل TypeError: boom.
تستقبل beforeSend كائن LerixErrorEvent: { message, stack, type, severity, metadata? }. والحقل stack مصفوفة من الإطارات، محلَّلة مسبقاً عبر خرائط المصدر. كما يجمّع Lerix الأخطاء المتكرّرة في مشكلة واحدة ويرشّح الضوضاء الشائعة على الخادم، لكل إصدارات الـ SDK. راجع كيف تُجمَّع الأخطاء في مشكلات.