React — تتبع الأخطاء

مقدمة

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

تأكّد من أن تطبيقك مغلّف بـ LerixProvider قبل الإبلاغ عن الأخطاء.

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

import { useLerix, BugSeverity } from '@lerix-dev/lerix-react';

function MyComponent() {
  const lerix = useLerix();

  const onSomethingFailed = async () => {
    try {
      await riskyOperation();
    } catch (error) {
      lerix.throwError(
        String(error),
        undefined,
        undefined,
        BugSeverity.HIGH,
        { userId: '123', action: 'payment', amount: 100 },
      );
    }
  };
}

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

المعامل	النوع	مطلوب	الوصف
`issue`	`string`	نعم	رسالة الخطأ أو وصفه
`stack`	`string[]`	لا	أطر تتبّع المكدس (Stack trace). إذا حُذف، يُلتقط تلقائياً من موضع الاستدعاء — راجع الالتقاط التلقائي لتتبّع المكدس أدناه
`type`	`BugType`	لا	تصنيف نوع الخطأ (الافتراضي: `RUNTIME_ERROR`)
`severity`	`BugSeverity`	لا	مستوى الخطورة (الافتراضي: `MEDIUM`)
`metadata`	`Record<string, unknown>`	لا	سياق إضافي يُرفق بالتقرير

قيم `BugType`

القيمة	الوصف
`RUNTIME_ERROR`	استثناء غير معالَج يُرمى أثناء التشغيل
`LOGIC_BUG`	سلوك غير صحيح لا يرمي استثناءً
`UI_BUG`	خلل بصري أو في التخطيط (layout)
`NETWORK_ERROR`	طلب شبكة فاشل أو مُشوَّه
`PERFORMANCE`	بطء، تقطّع (jank)، أو استهلاك موارد مفرط
`COMPATIBILITY`	خلل يظهر على متصفّح أو جهاز محدّد
`VALIDATION_ERROR`	إدخال غير صالح تجاوز التحقق رغم أنه لا ينبغي
`SECURITY`	خلل متعلّق بالأمان
`CRASH`	توقّف التطبيق بشكل غير متوقّع
`UNKNOWN`	لا شيء مما سبق

قيم `BugSeverity`

القيمة	الوصف
`CRITICAL`	يعطّل وظيفة أساسية أو يؤثّر على جميع المستخدمين
`HIGH`	تأثير كبير، لكن يوجد حل بديل (workaround)
`MEDIUM`	ملحوظ لكن تأثيره محدود
`LOW`	بسيط أو شكلي
`UNKNOWN`	لم يتم تقييم الخطورة بعد

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

يُثبّت LerixProvider التقاط الأخطاء بطريقتين، بحيث لا حاجة لتغليف أي شيء في try/catch للحصول على تغطية أساسية:

يلتقط LerixErrorBoundary الأخطاء التي تحدث أثناء العرض (rendering) — عقد حدود الأخطاء (error boundary) في React يغطّي فقط مرحلة العرض، وليس معالجات الأحداث أو الكود غير المتزامن.
تلتقط مستمعا window.onerror وَ unhandledrejection العامّان كل شيء آخر — معالجات الأحداث، المؤقّتات، ورفض الوعود (promise rejections).

خلافاً لمعالج الأعطال في تطبيق أصلي (native)، لا يكون تبويب المتصفح على وشك الإنهاء عند حدوث أحد هذين — لذا يُرسَل التقرير فوراً بدلاً من حفظه لتشغيل لاحق.

import { LerixErrorBoundary } from '@lerix-dev/lerix-react';

<LerixErrorBoundary fallback={<p>Something went wrong.</p>}>
  <App />
</LerixErrorBoundary>

يمكن أن يكون fallback عنصراً عادياً، أو دالة تستقبل الخطأ الملتقَط: fallback={(error) => <p>{String(error)}</p>}. لتعطيل المستمعَين العامَّين (مثلاً إذا كان تطبيقك يملك بالفعل نظام إبلاغ عن الأخطاء خاصاً به وتريد فقط استدعاءات throwError اليدوية):

<LerixProvider options={{ apiKey: '...', projectId: '...', enableCrashReporting: false }}>

يستمر LerixErrorBoundary في التقاط أخطاء العرض بغضّ النظر عن هذا الخيار — فهو مكوّن منفصل وصريح تتحكّم به عبر مكان وضعه.

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

عند استدعاء throwError() دون تمرير معامل stack، يُلتقط تتبّع مكدس تلقائياً من موضع الاستدعاء — لا تحتاج لتمريره صراحةً إلا عند الإبلاغ عن تتبّع مكدس خطأ (Error) ملتقَط بنفسك بدلاً من موضع استدعاء throwError (مثل error.stack?.split('\n')). في الحالتين، يُحلَّل كل إطار من إطارات المكدس من موضعه المُجمَّع (compiled/bundled) إلى ملف المصدر الأصلي وسطره، باستخدام خريطة المصدر (source map) الخاصة بالبناء نفسه — نفس الآلية التي تستخدمها أدوات المطوّرين (DevTools) في المتصفح لعرض تتبّعات مكدس مقروءة بدلاً من مواضع الحزمة (bundle) المُصغَّرة. يحدث هذا تلقائياً؛ لا حاجة لأي إعداد.

يتطلّب التحليل أن تكون خريطة المصدر متاحة على رابط الإطار — وهذا صحيح دائماً في بيئة التطوير، وصحيح في الإنتاج فقط إذا كان بناؤك يقدّم ملفات .map علناً. إذا أبقى بناء الإنتاج خرائط المصدر خاصة (خيار شائع)، ترجع الإطارات إلى موضعها المُجمَّع بدلاً من فشل الإبلاغ — التحليل هو أفضل محاولة (best-effort) ولا يعطّل أو يؤخّر التقرير نفسه أبداً.

لتحصل على تتبّعات مكدس مقروءة في الإنتاج مع إبقاء خرائط المصدر خاصة، ارفعها إلى Lerix بعد كل بناء. راجع خرائط المصدر لـ React.

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

lerix.throwError('Test error');

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

البدء

أطر العمل

الوحدات

المطورون

React — تتبع الأخطاء

مقدمة

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

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

قيم `BugType`

قيم `BugSeverity`

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

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

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

​مقدمة

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

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

​قيم BugType

​قيم BugSeverity

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

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

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

مقدمة

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

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

قيم `BugType`

قيم `BugSeverity`

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

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

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