خرائط المصدر لا تعمل

خرائط المصدر لا تُحلّ: استرجع مسارات استدعاء مقروءة

أخطاء JavaScript عندك تعرض إطارات مصغّرة مثل a.js:1:48213 بدل ملفاتك الأصلية. في تسع حالات من عشر، سلاسل الإصدار غير متطابقة.

كيف تبدو المشكلة

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

ثاني أكبر سبب هو عدم تطابق المسارات: رُفعت الخرائط للإصدار الصحيح، لكن المسارات التي سُجّلت تحتها لا توافق العناوين التي حمّل المتصفح الحزم منها فعلًا — فيخطئ البحث عن الإطار.

الأسباب الجذرية الشائعة

عدم تطابق سلسلة الإصدار

الإصدار المضبوط في تهيئة الـ SDK (مثل release: process.env.NEXT_PUBLIC_RELEASE) يختلف عن الإصدار الذي رُفعت الخرائط تحته — حتى بادئة v أو SHA مختصر مقابل كامل تكسر التطابق.

لا إصدار مضبوط أصلًا

إذا أرسل الـ SDK أحداثًا بلا إصدار، فلا يوجد ما تُطابَق معه الخرائط المرفوعة. يجب ضبط خيار release في التهيئة حتى يعمل حلّ خرائط المصدر.

عدم توافق المسارات والعناوين

يجب تسجيل ملفات الخرائط تحت مسارات توافق عناوين الحزم المقدَّمة. بادئة CDN أو أسماء ملفات مُجزّأة أو مسار عام مختلف بين البناء والنشر — كلها تجعل البحث يخطئ.

نشر جديد بخرائط قديمة

كل نشر يغيّر الحزم هو إصدار جديد ويحتاج رفعًا جديدًا. أحداث الحزم الجديدة لا يمكن أن تُحلّ بخرائط النشر السابق.

التشخيص خطوة بخطوة

قارن ما يحمله الحدث بما رفعته — الإصدار أولًا والمسارات ثانيًا.

  1. 1

    اقرأ الإصدار على حدث حقيقي

    افتح خطأ مصغّرًا حديثًا في لوحة AllStak ولاحظ سلسلة الإصدار التي وصل بها بالضبط — بما فيها أي بادئة أو لاحقة أو قيمة مفقودة. هذه هي السلسلة التي يجب رفع خرائطك تحتها.

  2. 2

    تأكد من وجود خرائط لهذا الإصدار بالضبط

    تحقّق من الإصدار الذي رفع خطّ بنائك الخرائط له. v1.4.2 و 1.4.2 إصداران مختلفان؛ وكذلك SHA مختصر مقابل كامل. يجب أن تتطابق السلسلتان حرفًا بحرف.

  3. 3

    وفّق إصدار الـ SDK مع الرفع

    اضبط خيار release في تهيئة الـ SDK من متغيّر CI نفسه الذي تستخدمه خطوة الرفع (مثل commit SHA)، حتى يتفق الطرفان دائمًا بحكم البناء.

  4. 4

    افحص توافق المسارات مع العناوين المقدَّمة

    افتح تبويب الشبكة في المتصفح ولاحظ العنوان الذي تُحمَّل منه كل حزمة. يجب أن توافق مسارات الخرائط المرفوعة هذه العناوين — عدّل مسارات الرفع إذا اختلفت بادئة CDN أو المسار العام.

  5. 5

    أعد الرفع للنشر الحالي

    إذا تغيّرت الحزم العاملة منذ آخر رفع، ارفع خرائط جديدة للإصدار الحالي. الأحداث المصغّرة الموجودة تبقى مصغّرة؛ ويسري الحلّ على الأحداث الواصلة بعد وجود خرائط إصدارها.

  6. 6

    أطلق خطأ جديدًا وتحقّق

    ارمِ خطأ تجريبيًا من التطبيق المنشور وتأكد أن الحدث الجديد يعرض أسماء الملفات وأرقام الأسطر الأصلية. إذا نجح، اربط الرفع بخطّ CI ليحدث مع كل نشر.

كيف تمنع تكرارها

  • اشتق الإصدار من متغيّر CI واحد (commit SHA أو رقم نسخة) يستخدمه كل من تهيئة الـ SDK ورفع الخرائط.
  • اجعل رفع الخرائط خطوة CI إلزامية مع كل نشر للواجهة — لا عملًا يدويًا لاحقًا.
  • بعد كل نشر، تأكد أن خطأ جديدًا واحدًا يُحلّ إلى المصدر قبل إغلاق الإصدار.
  • استمر بتوليد خرائط المصدر في بناء الإنتاج حتى لو لم تقدّمها للعموم — وارفعها إلى AllStak بدلًا من ذلك.

ما زلت عالقًا؟

إذا تطابقت سلاسل الإصدار وتوافقت المسارات وما زالت الإطارات تعود مصغّرة، راسلنا على [email protected] باسم مشروعك وسلسلة الإصدار ورابط حدث متأثر — ونستطيع فحص ما رآه المحلّل. وتغطي صفحة حالة AllStak أي مشاكل معالجة من جهة المنصّة.

الأسئلة الشائعة

هل تصبح الأحداث المصغّرة القديمة مقروءة بعد رفع الخرائط؟

يسري الحلّ على أحداث الإصدارات التي لها خرائط. والأحداث التي وصلت بإطارات مصغّرة قبل وجود خرائط إصدارها تبقى كما الُتقطت — أطلق خطأ جديدًا للتحقق من الإصلاح.

هل أحتاج رفع الخرائط مع كل نشر؟

نعم، كلما تغيّرت الحزم. كل نشر يجب أن يضبط إصدارًا جديدًا في تهيئة الـ SDK ويرفع الخرائط المطابقة — ولهذا فإن أتمتتها في CI هي الإعداد الموثوق الوحيد.

ماذا أستخدم كسلسلة إصدار؟

أي قيمة فريدة لكل نشر يستطيع كل من الـ SDK وخطوة الرفع قراءتها — معظم الفرق تستخدم commit SHA من git أو رقم نسخة مثل [email protected] من متغيّر CI.

هل تقديم ملفات .map للعموم يغني عن الرفع؟

ارفع الخرائط إلى AllStak للإصدار المطابق — فهذا ما يستخدمه الحلّ. ويمكنك بعدها إبقاء ملفات .map الإنتاجية خاصة، وهو ما تفضّله معظم الفرق.

استكشف المزيد

القدرات

حسب إطار العمل

قارن

مسارات استدعاء مقروءة مع كل نشر

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

ابدأ مجاناً عرض الأسعار