مقدمة
يلتقط Lerix الأخطاء من تطبيق React الخاص بك لتتمكّن من تصحيح المشاكل بشكل أسرع. بعد إتمام تثبيت React، استخدمuseLerix().throwError() لإرسال أخطاء مخصّصة إلى لوحة التحكم — أما
الأخطاء غير الملتقطة فتُلتقط تلقائياً، دون الحاجة لأي كود إضافي.
تأكّد من أن تطبيقك مغلّف بـ
LerixProvider قبل الإبلاغ عن الأخطاء.الإبلاغ عن خطأ
المعاملات (Parameters)
قيم BugType
قيم BugSeverity
الالتقاط التلقائي للأخطاء
يُثبّتLerixProvider التقاط الأخطاء بطريقتين، بحيث لا حاجة لتغليف أي شيء
في try/catch للحصول على تغطية أساسية:
- يلتقط
LerixErrorBoundaryالأخطاء التي تحدث أثناء العرض (rendering) — عقد حدود الأخطاء (error boundary) في React يغطّي فقط مرحلة العرض، وليس معالجات الأحداث أو الكود غير المتزامن. - تلتقط مستمعا
window.onerrorوَunhandledrejectionالعامّان كل شيء آخر — معالجات الأحداث، المؤقّتات، ورفض الوعود (promise rejections).
fallback عنصراً عادياً، أو دالة تستقبل الخطأ الملتقَط:
fallback={(error) => <p>{String(error)}</p>}.
لتعطيل المستمعَين العامَّين (مثلاً إذا كان تطبيقك يملك بالفعل نظام إبلاغ
عن الأخطاء خاصاً به وتريد فقط استدعاءات throwError اليدوية):
LerixErrorBoundary في التقاط أخطاء العرض بغضّ النظر عن هذا الخيار
— فهو مكوّن منفصل وصريح تتحكّم به عبر مكان وضعه.
الالتقاط التلقائي لتتبّع المكدس
عند استدعاءthrowError() دون تمرير معامل stack، يُلتقط تتبّع مكدس
تلقائياً من موضع الاستدعاء — لا تحتاج لتمريره صراحةً إلا عند الإبلاغ عن
تتبّع مكدس خطأ (Error) ملتقَط بنفسك بدلاً من موضع استدعاء throwError
(مثل error.stack?.split('\n')).
في الحالتين، يُحلَّل كل إطار من إطارات المكدس من موضعه المُجمَّع
(compiled/bundled) إلى ملف المصدر الأصلي وسطره، باستخدام خريطة المصدر
(source map) الخاصة بالبناء نفسه — نفس الآلية التي تستخدمها أدوات
المطوّرين (DevTools) في المتصفح لعرض تتبّعات مكدس مقروءة بدلاً من مواضع
الحزمة (bundle) المُصغَّرة. يحدث هذا تلقائياً؛ لا حاجة لأي إعداد.
يتطلّب التحليل أن تكون خريطة المصدر متاحة على رابط الإطار — وهذا صحيح
دائماً في بيئة التطوير، وصحيح في الإنتاج فقط إذا كان بناؤك يقدّم ملفات
.map علناً. إذا أبقى بناء الإنتاج خرائط المصدر خاصة (خيار شائع)، ترجع
الإطارات إلى موضعها المُجمَّع بدلاً من فشل الإبلاغ — التحليل هو أفضل
محاولة (best-effort) ولا يعطّل أو يؤخّر التقرير نفسه أبداً.تحقّق من التكامل
ترشيح الأخطاء
يتطلّب@lerix-dev/lerix-react بالإصدار 1.2.0 أو أحدث.
يحدّد خياران اختياريان في LerixProvider الأخطاء التي تُرسَل. ينطبقان على
كل تقرير: LerixErrorBoundary، والمعالجات العامة، وthrowError().
- تعمل
ignoreErrorsأولاً. النص (string) يحذف أي خطأ تحتوي رسالته عليه، دون تمييز حالة الأحرف. والتعبيرRegExpيحذف أي خطأ تطابقه رسالته. تُتجاوَز النصوص الفارغة. - ثم لا ترى
beforeSendإلا ما تبقّى. أعِد الحدث (معدّلاً أو كما هو) لإرساله، أو أعِدnullلحذفه. إذا رمت استثناءً، يُرسَل الحدث الأصلي ولا يصل الاستثناء إلى تطبيقك. - الرسالة التي تطابقها هي عنوان المشكلة، وتتضمّن صنف الخطأ، مثل
TypeError: boom.
beforeSend كائن LerixErrorEvent:
{ message, stack, type, severity, metadata? }. والحقل stack مصفوفة من
الإطارات، محلَّلة مسبقاً عبر خرائط المصدر.
كما يجمّع Lerix الأخطاء المتكرّرة في مشكلة واحدة ويرشّح الضوضاء الشائعة على
الخادم، لكل إصدارات الـ SDK. راجع
كيف تُجمَّع الأخطاء في مشكلات.