تقدّم هذه الصفحة نصائح وإرشادات لتحديد وحلّ المشاكل المتعلّقة بلغة JavaScript التي قد تواجهها عند استخدام حزمة تطوير البرامج (SDK) الخاصة بـ Firebase JavaScript.
هل تواجه تحديات أخرى أو لم تظهر لك مشكلتك؟ ننصحك بالاطّلاع على الأسئلة الشائعة الرئيسية حول Firebase للحصول على مزيد من الأسئلة الشائعة حول Firebase أو منتجات معيّنة.
يمكنك أيضًا الاطّلاع على مستودع GitHub الخاص بحزمة تطوير البرامج (SDK) Firebase JavaScript للحصول على قائمة محدّثة بالمشاكل التي تم الإبلاغ عنها وحلّها، كما يمكنك الإبلاغ عن المشاكل التي تواجهك هناك.
لا تتوافق بنى Admin SDK الخاصة بـ Node.js مع حزمة تطوير البرامج (SDK) Firebase JavaScript
إنّ Firebase Admin SDK لمنصة Node.js وFirebase JavaScript SDK هما تنفيذان مختلفان لا يتشاركان تعريفات الواجهة أو الفئة أو الدالة. لا تتوافق مثيلات عناصر Admin SDK مع وظائف حزمة تطوير البرامج (SDK) Firebase JavaScript.
على سبيل المثال، يؤدي تمرير مثيل من Admin SDK إلى الدالة getDatabase في حزمة تطوير البرامج (SDK) Firebase JavaScript إلى ظهور الخطأ التالي:FirebaseApp
TypeError: Cannot read properties of undefined (reading 'getProvider')
at _getProvider
at getDatabase
وينطبق ذلك على مساحة واجهة برمجة التطبيقات لحزمة تطوير البرامج (SDK) بالكامل Firebase JavaScript، وليس Realtime Database فقط.
وينطبق ذلك أيضًا على الاستخدام في الاتجاه المعاكس. تؤدي محاولة استخدام النوع Timestamp في حزمة تطوير البرامج (SDK) بلغة JavaScript Cloud Firestore مع Firebase Admin SDK في Node.js إلى ظهور أخطاء مشابهة.
تجنُّب استخدام إصدارات متعارضة من حزمة تطوير البرامج (SDK) الخاصة بـ Firebase JavaScript
سيؤدي إعداد إصدارات متعدّدة ومتعارضة من حزمة تطوير البرامج (SDK) Firebase JavaScript كعناصر تابعة في أحد المشاريع إلى حدوث أخطاء أثناء التشغيل عند تمرير مثيلات حزمة تطوير البرامج (SDK) بين حِزم SDK. على سبيل المثال، يؤدي استخدام مكتبة Data Connect مع إصدار غير متوافق من FirebaseApp إلى ظهور الخطأ التالي:
Error: Component data-connect has not been registered yet
تحدث هذه المشكلة عادةً بسبب تعديل إحدى حِزم Firebase SDK بدون تعديل الحِزم الأخرى. يحدث هذا الموقف غالبًا عندما تغيّر أداة تلقائية لتعديل التبعيات مجموعة فرعية من تبعيات حزمة تطوير البرامج (SDK) الخاصة بـ Firebase ضمن ملف yarn.lock أو package-lock.json الخاص بالمشروع. بما أنّ العديد من حِزم تطوير البرامج (SDK) Firebase JavaScript تعمل معًا، فإنّ استخدام إصدارات مختلفة من حِزم تطوير البرامج (SDK) يؤدي إلى حدوث مشاكل في عدم التوافق أثناء التشغيل.
لحلّ هذه المشكلة، احذف الدليل node_modules/ والملف yarn.lock (لـ yarn) أو الملف package-lock.json (لـ npm) في مشروعك، ثم أعِد تثبيت التبعيات.
إذا استمرت الأخطاء، يمكنك تحديد المشكلة وحلّها باستخدام الأمر npm ls. سيؤدي ذلك إلى تسجيل التبعيات الخاصة بمشروعك حتى تتمكّن من تحديد الإصدارات المتعارضة من الوحدة firebase.
على سبيل المثال، يعرض السجلّ التالي عملية استيراد package-using-older-firebase لإصدار متعارض من حزمة تطوير البرامج (SDK) Firebase JavaScript:
$ npm ls firebase --all
your-app@0.0.0
├── firebase@11.2.0
├─┬ @angular/fire@19.0.0
│ ├── firebase@11.2.0 deduped
│ └─┬ rxfire@6.1.0
│ └── firebase@10.14.1 deduped
└─┬ package-using-older-firebase@0.1.0
└─── firebase@10.14.1
قد تحدث أخطاء أيضًا بسبب الجمع بين عبارات CJS وESM require وimport في تطبيقك، ما يؤدي إلى إنشاء مثيلات متعددة لحزمة تطوير البرامج (SDK) الخاصة بـ Firebase JavaScript،
كل منها يختلف عن الآخر، ما يؤدي إلى تعطُّل إمكانية التشغيل التفاعلي لحزمة تطوير البرامج (SDK) الخاصة بـ Firebase JavaScript.
يمكنك زيادة مستوى تفصيل أداة تجميع الحِزم التي تختارها لتصحيح الأخطاء في هذا السيناريو. على سبيل المثال، يمكنك استخدام علامة esbuild analyze لهذا الغرض.
التأكّد من تجميع عاملي الخدمة
غالبًا ما يتم إنشاء مشغّلي الخدمات من مسار منفصل عن بقية تطبيقات الويب، ولا يتم تضمينهم في الإعدادات التلقائية لحزم مثل Webpack.
إذا كنت تستخدم الإصدار النمطي من حزمة تطوير البرامج (SDK) الخاصة بـ Firebase JavaScript ضمن عامل الخدمة، تأكَّد من ضبط أداة تجميع التطبيقات لتضمين ملف مصدر عامل الخدمة. يستخدم المثال التالي npx لتجميع برنامج
firebase-sw.js service worker في الدليل src الخاص بالمشروع:
npx esbuild ./src/firebase-sw.js --bundle --minify --main-fields=webworker,browser,module,main,default --outfile=public/firebase-sw.js
سيتعذّر تفعيل عامل خدمة غير مجمَّع إذا كان مصدره استيراد وحدات ES التي لا تتوافق مع عوامل الخدمة أو الملفات غير المتوفّرة في نطاق عامل الخدمة. وفي بعض الأحيان، لا تظهر أي رسائل خطأ، ما يصعّب تحديد المشكلة.
يمكنك الاطّلاع على استخدام أدوات تجميع الوحدات مع Firebase للحصول على مزيد من المعلومات حول تجميع الإصدار المعياري من حزمة تطوير البرامج (SDK) Firebase JavaScript في تطبيقك.
بدلاً من ذلك، يمكنك إلغاء الحاجة إلى التجميع من خلال استيراد حِزم compat
Firebase JavaScript SDK من شبكة توصيل المحتوى (CDN):
// Give the service worker access to Firebase Messaging.
// Replace 10.13.2 with the version of the Firebase JS SDK you're using
// in your app.
importScripts('https://www.gstatic.com/firebasejs/10.13.2/firebase-app-compat.js');
importScripts('https://www.gstatic.com/firebasejs/10.13.2/firebase-messaging-compat.js');
// Initialize the Firebase app in the service worker by passing in
// your app's Firebase config object.
// https://firebase.google.com/docs/web/setup#config-object
firebase.initializeApp({
...
});
// Retrieve an instance of Firebase Messaging so that it can handle
// background messages.
const messaging = firebase.messaging();
استخدِم FirebaseServerApp عند العمل مع ميزة "العرض من جهة الخادم"
كان الهدف من حزمة تطوير البرامج (SDK) Firebase JavaScript في الأصل أن تعمل في بيئات المتصفح. أدّى طرح أُطر العرض على جهة الخادم (SSR) إلى توسيع نطاق استخدام حِزم SDK ليشمل بيئات وقت تشغيل جديدة. توفّر بيئات التشغيل هذه مجموعة فرعية من الأدوات وواجهات برمجة التطبيقات التي توفّرها متصفحات الويب.
على سبيل المثال، تتطلّب بعض حِزم تطوير البرامج (SDK) من Firebase تخزين البيانات مؤقتًا باستخدام IndexedDB، وهي واجهة برمجة تطبيقات مخصّصة للمتصفّح فقط. قد يتطلّب Firebase Auth تفاعل المستخدم في بعض عمليات تسجيل الدخول التي لا يمكن إجراؤها في بيئات الخادم غير المرئية. تعتمد App Check على إحصاءات المتصفّح للتحقّق من المستخدم قبل إنشاء رموز App Check المميّزة.
عند استخدام حزمة SDK في هذه البيئات الجديدة، استخدِم
FirebaseServerApp، وهو نوع جديد
من FirebaseApp يوفّر وسيلة لتحميل نسخة SSR Firebase مسبقًا
بالبيانات التي تم جمعها من جهة العميل.
تتوافق FirebaseServerApp مع مَعلمتَين:
- رمز تعريف المصادقة: إذا تم توفيره، تسجِّل خدمة Firebase Auth تلقائيًا دخول مستخدم تمت مصادقته سابقًا، ما قد يؤدي إلى ربط جلسة بين عملية عرض من جهة العميل (CSR) وعملية عرض من جهة الخادم (SSR).
- رمز App Check المميّز: في حال توفّره، تستخدم حِزم تطوير البرامج (SDK) الأخرى من Firebase الرمز المميّز بدون الحاجة إلى تهيئة مثيل من عميل App Check (وهو غير متاح خارج بيئات المتصفّح). يؤدي ذلك إلى إتاحة إمكانية استخدام SSR في المنتجات التي تم تفعيلها، مثل App Check وCloud Functions وData Connect وCloud Firestore وRealtime Database وVertex AI.
يمكنك الاطّلاع على تبسيط عملية تطوير تطبيقات SSR باستخدام
FirebaseServerApp
للحصول على مثال حول كيفية استخدام FirebaseServerApp في Next.js.