الحصول على تقارير أعطال قابلة للقراءة في لوحة بيانات Crashlytics (الويب)

اختيار المنصة: +iOS Android الويب Flutter Unity


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

لإزالة تشويش تتبُّع تسلسل استدعاء الدوال البرمجية وعرض أسماء الملفات الأصلية وأرقام الأسطر في تقارير Error Reporting، استخدِم الأمر Firebase في واجهة سطر الأوامر لتحميل خرائط المصدر (ملفات .js.map) إلى Firebase.

المتطلبات الأساسية

قبل تحميل خرائط المصدر، تأكَّد من تثبيت الإصدار 15.35.0 من واجهة سطر الأوامر (CLI) في Firebase أو إصدار أحدث. كيفية تثبيت واجهة سطر أوامر Firebase أو تحديثها

الخطوة 1: تفعيل إنشاء خريطة المصدر في إصدار إطار العمل

اضبط إطار عمل الواجهة الأمامية أو أداة التجميع لإنشاء ملفات المصدر الخاصة بالإصدار العلني (.js.map) أثناء عملية إنشاء تطبيقك:

Angular

في Angular، يجب ضبط خيار sourceMap داخل ملف مساحة العمل angular.json أو تمرير علامة تجاوز واجهة سطر الأوامر --source-map:

الخيار 1 (يُنصح به): تعديل angular.json

افتح ملف angular.json وابحث عن إعدادات التصميم المحدّدة التي تريد استهدافها (مثل development أو production). اضبط المَعلمة sourceMap ضمن مجموعة الرموز البرمجية options أو configurations المحدّدة:

"projects": {
  "APP_NAME": {
    "architect": {
      "build": {
        "options": {
          "sourceMap": true
        },
        "configurations": {
          "production": {
            "sourceMap": {
              "scripts": true,
              "vendor": false
            }
          }
        }
      }
    }
  }
}

الخيار 2: تجاوز سطر الأوامر

إذا كنت بحاجة إلى خرائط المصدر فقط لإصدار تحقّق لمرة واحدة أو جلسة تصحيح أخطاء، أضِف العلامة --source-map مباشرةً إلى أمر إصدار Angular CLI:

ng build --configuration production --source-map

Next.js

يُرجى تعديل ملف next.config.ts (أو next.config.js) لتفعيل إنشاء خريطة المصدر في المتصفّح أثناء عمليات الإنشاء من خلال ضبط productionBrowserSourceMaps على true:

// next.config.ts
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  // Enable browser source map emission for Crashlytics stack trace de-obfuscation
  productionBrowserSourceMaps: true,
  // ... rest of your Next.js configuration
};

export default nextConfig;

يخزّن Next.js حِزم برامج العميل التي تم إنشاؤها وملفات .js.map لخرائط المصدر داخل دليل .next في جذر مشروعك.

React / Vite

إذا كان تطبيق React يستخدم Vite كأداة تجميع للإصدار، يُرجى تعديل ملف vite.config.ts لإصدار خرائط المصدر ضمن خيارات الإصدار:

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  build: {
    // Emit sourcemap files for Crashlytics upload
    sourcemap: true,
  },
});

يخزّن Vite حِزم النتائج التي تم إنشاؤها وملفات .js.map داخل دليل dist تلقائيًا.

الخطوة 2: تحميل خرائط المصدر باستخدام واجهة سطر الأوامر في Firebase

بعد أن ينشئ إطار العمل حِزم الإنتاج وملفات .js.map، يمكنك تحميل خرائط المصدر باستخدام الأمر firebase crashlytics:sourcemap:upload:

firebase crashlytics:sourcemap:upload \
  --project PROJECT_ID \
  --app FIREBASE_APP_ID \
  --debug DIRECTORY

يبحث هذا الأمر بشكل متكرر عن جميع ملفات .js.map ضمن مسار DIRECTORY المقدَّم (dist أو .next) ويحمّلها إلى Cloud Storage لربط الرموز.

الخطوة 3: التعامل مع خرائط المصدر

إنّ إنشاء خرائط المصدر إلى جانب مواد عرض تطبيق الويب يمكن أن يعرّضها لطلبات المتصفّح العلنية، ما قد يؤدي إلى تسرُّب الرمز المصدر الأصلي. يمكنك منع ذلك بدون فقدان عمليات تتبُّع تسلسل استدعاء الدوال البرمجية التي تم إلغاء تشويشها، وذلك من خلال ضبط خادم الويب لرفض وصول الجمهور إلى ملفات .js.map، أو من خلال تمرير علامة --clean إلى firebase crashlytics:sourcemap:upload لحذف ملفات .js.map تلقائيًا من دليل الإصدار المحلي بعد تحميلها إلى Firebase.

التشغيل الآلي في مسار الإصدار

لتحميل خرائط المصدر تلقائيًا إلى Crashlytics وحذف ملفات .js.map المحلية قبل النشر، يُرجى تعديل النص البرمجي build في ملف package.json لتمرير العلامة --clean إلى firebase crashlytics:sourcemap:upload:

Angular

"scripts": {
  "build": "ng build && firebase crashlytics:sourcemap:upload --project PROJECT_ID --app FIREBASE_APP_ID --clean --debug dist"
}

Next.js

"scripts": {
  "build": "next build && firebase crashlytics:sourcemap:upload --project PROJECT_ID --app FIREBASE_APP_ID --clean --debug .next"
}

React / Vite

"scripts": {
  "build": "vite build && firebase crashlytics:sourcemap:upload --project PROJECT_ID --app FIREBASE_APP_ID --clean --debug dist"
}

الخطوات التالية

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