تقدّم هذه الصفحة نصائح وإرشادات لتحديد وحلّ المشاكل المتعلّقة بلغة 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 فقط.
وينطبق ذلك أيضًا على الاستخدام في الاتجاه المعاكس. محاولة استخدام النوع Cloud Firestore في حزمة تطوير البرامج (SDK) بلغة JavaScript مع Firebase Admin SDK في Node.js تؤدي إلى ظهور أخطاء مشابهة.Timestamp
تجنُّب استخدام إصدارات متعارضة من حزمة تطوير البرامج (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 يوفّر وسيلة لتحميل مثيل Firebase الخاص بعرض الصفحات من جهة الخادم (SSR) مسبقًا بالبيانات التي تم جمعها من جهة العميل.
تتوافق 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.