مسارات استدعاء مقروءة من JavaScript المصغّر: خرائط المصدر وتجميع الأخطاء

شيفرة JavaScript في بيئة الإنتاج مصغّرة (minified): تتقلص أسماء المتغيرات إلى حرف واحد، وتُدمج الملفات في أجزاء (chunks) بأسماء مشتقة من محتواها، وكثيراً ما يصبح الملف كله سطراً واحداً. هذا ممتاز لسرعة التحميل وسيئ جداً لتتبّع الأخطاء. يصلك الخطأ من الإنتاج هكذا:

TypeError: Cannot read properties of undefined (reading 'id')
    at e.r (index-8f3a1c.js:1:48213)
    at Object.o (index-8f3a1c.js:1:51007)

لا ملف تعرفه، ولا اسم دالة، ولا سطر يمكنك فتحه. خرائط المصدر (source maps) تحلّ هذه المشكلة. أداة البناء تعرف أصلاً كيف يقابل كل حرف في الناتج شيفرتك الأصلية؛ ارفع هذه الخريطة، فيصلك الخطأ نفسه على أنه الدالة submitOrder في الملف src/checkout/submit.ts السطر 42، مع الشيفرة المحيطة به.

يشرح هذا الدليل الإعداد مع Vite وCreate React App وNext.js وAngular وFlutter Web، ثم يوضح كيف يجمع ليركس الأخطاء الناتجة في مشكلات.

1. اجعل البناء ينتج خرائط المصدر

فعّل الخرائط، ويُفضّل أن تكون مخفية (hidden): تُكتب ملفات .map لكن الحزمة لا تشير إليها، فلا يحمّلها المتصفح أبداً.

2. ارفعها بعد كل بناء

أمر واحد يُشغَّل مباشرة بعد البناء:

npx @lerix-dev/lerix-cli upload

تجد الأداة مجلد البناء بنفسها (outputPath في Angular، أو .next أو build/web أو dist أو build أو out)، وترفع كل ملف .js.map تجده (وتتجاوز خرائط CSS وnode_modules)، ثم تحذف الخرائط من ناتج البناء حتى لا تُنشر شيفرتك الأصلية أبداً.

وتقرأ إعداداتها من متغيرات البيئة:

لماذا مفتاح خاص؟ المفتاح العام موجود داخل كل حزمة ويب، ولو اكتُفي به لاستطاع أي شخص استبدال خرائطك وتزوير مسارات الاستدعاء. احتفظ بالمفتاح الخاص في بيئة CI لا داخل التطبيق.

لا تُحذف الخرائط إلا إذا نجح رفعها كلها، فيمكنك إعادة تشغيل الأمر كما هو عند الفشل. استخدم --keep-maps للإبقاء عليها، و--dry-run لترى ما سيُرسل دون إرساله.

3. أعطِ الحزمة البرمجية الإصدار نفسه

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

<LerixProvider
  options={{
    apiKey: 'your-api-key',
    projectId: 'your-project-slug',
    release: import.meta.env.VITE_LERIX_RELEASE,
  }}
>
  <App />
</LerixProvider>

في Next.js يقرأ LerixNextProvider المتغير NEXT_PUBLIC_LERIX_RELEASE بنفسه، وفي Angular هو الخيار release في provideLerix(). استخدم قيمة لا تكتبها يدوياً: قيمة version في package.json أو معرّف الـ commit.

في GitHub Actions

jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      LERIX_RELEASE: ${{ github.sha }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci

      # The same release, available to the app at build time
      - run: npm run build
        env:
          VITE_LERIX_RELEASE: ${{ github.sha }}

      - run: npx @lerix-dev/lerix-cli upload
        env:
          LERIX_API_KEY: ${{ secrets.LERIX_API_KEY }}
          LERIX_PROJECT_ID: ${{ secrets.LERIX_PROJECT_ID }}
          LERIX_SECRET_KEY: ${{ secrets.LERIX_SECRET_KEY }}

      # Deploy dist here. It no longer contains .map files.

4. ما الذي يتغير في لوحة التحكم

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

ومسار الاستدعاء المقروء هو أيضاً ما يراه مساعد الذكاء الاصطناعي ومشكلات GitHub وخادم MCP. أمران يجب معرفتهما:

• لا تُربط إلا الأخطاء التي تصل بعد الرفع؛ الأخطاء الأقدم تبقى بمسارها المصغّر.
• ربط الخرائط لا يؤخر أي تقرير أبداً. إذا غابت الخريطة أو تأخرت يُحفظ الخطأ كما وصل.

5. كيف تتحول الأخطاء إلى مشكلات

عشرة آلاف تقرير عن خلل واحد يجب أن تكون سطراً واحداً في صندوقك، لا عشرة آلاف سطر. يعطي ليركس كل خطأ بصمة من جزأين:

1. السطر الأول من الرسالة بعد إخفاء الأجزاء المتغيرة: الأرقام والمعرّفات UUID والمعرّفات الست عشرية الطويلة والبريد والروابط. أما رموز الأخطاء الملتصقة بالنص مثل PGRST202 أو #441 فتبقى كما هي.
2. أول إطار في مسار الاستدعاء من شيفرتك أنت، مختصراً إلى اسم الدالة والملف: بلا رقم سطر ولا عمود، وبلا الجزء المشتق من المحتوى في اسم الملف. وتُتجاوز إطارات node_modules والمتصفح والحزمة البرمجية.

ولأن رقم السطر واسم الجزء مستبعدان، يبقى الخطأ المشكلةَ نفسها عبر عمليات النشر بدل أن يبدأ من الصفر مع كل بناء. ولأن مسار الاستدعاء يُربط بالخرائط قبل أخذ البصمة، يعتمد التجميع على أسماء دوالك الحقيقية.

تتتبّع كل مشكلة عدد مرات حدوثها والمستخدمين المتأثرين وأول ظهور وآخر ظهور. والحالة تسري على كل التكرارات:

• المشكلات المحلولة تُفتح من جديد تلقائياً إذا عاد الخطأ، وتصلك رسالة بريد عن هذا الخلل العائد.
• المشكلات المتجاهلة يستمر عدّها لكن دون تنبيهات، وتُخفى من القائمة الافتراضية.

6. استبعد الضجيج

بعض أخطاء المتصفح لا تحمل أي معلومة. يُسقطها الخادم لكل المشاريع:

• ‏ResizeObserver loop limit exceeded وResizeObserver loop completed with undelivered notifications
• ‏Script error.، وهي الرسالة البديلة التي يعرضها المتصفح لخطأ في سكربت من نطاق آخر، بلا رسالة ولا مسار
• الأخطاء التي يقع مسارها بالكامل داخل إضافات المتصفح

وللضجيج الخاص بتطبيقك، صفِّ على الجهاز قبل أن يُرسل أي شيء:

<LerixProvider
  options={{
    apiKey: 'your-api-key',
    projectId: 'your-project-slug',
    ignoreErrors: ['ResizeObserver loop', /^ChunkLoadError/],
    beforeSend: (event) =>
      event.message.includes('extension://') ? null : event,
  }}
>

النصوص تطابق أي جزء من الرسالة دون تمييز حالة الأحرف، والتعابير النمطية تُختبر كما كُتبت. وإرجاع null من beforeSend يُسقط الحدث. وكلاهما يعمل في المتصفح قبل أن يربط الخادم مسار الاستدعاء بالخرائط، فطابِق على نص الرسالة لا على أسماء الملفات.

قائمة مراجعة

1. خرائط مصدر مخفية مفعّلة في أداة البناء.
2. ‏npx @lerix-dev/lerix-cli upload مباشرة بعد البناء، مع LERIX_SECRET_KEY في بيئة CI.
3. الإصدار نفسه في أداة الرفع وفي الحزمة البرمجية.
4. انشر مجلد البناء بعد الرفع فقط، حتى تكون الخرائط قد حُذفت منه.
5. ارمِ خطأً واحداً في الإنتاج عمداً وتأكد أنه يشير إلى ملفك.

يحتفظ ليركس بأحدث 5,000 خريطة لكل مشروع، بحجم يصل إلى 50 ميغابايت للخريطة.