تقدّم هذه الصفحة نصائح وإرشادات لتحديد وحلّ المشاكل المتعلّقة بلغة 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) JavaScript Firebase:
$ 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 في تطبيقك.
بدلاً من ذلك، يمكنك إلغاء الحاجة إلى تجميع حِزم SDK من خلال استيراد حِزم 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.