تقدّم هذه الصفحة نصائح وإرشادات لتحديد وحلّ المشاكل المتعلّقة بلغة 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 FirebaseApp إلى الدالة getDatabase في حزمة تطوير البرامج (SDK) الخاصة بـ Firebase JavaScript إلى ظهور الخطأ التالي:
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). على سبيل المثال، يؤدي استخدام مكتبة SQL 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 للحصول على مزيد من المعلومات حول تجميع الإصدار المعياري من حزمة تطوير البرامج 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).
- رمز فحص التطبيقات المميّز: في حال توفّره، تستخدم حِزم تطوير البرامج (SDK) الأخرى من Firebase الرمز المميّز بدون الحاجة إلى تهيئة مثيل من عميل App Check (وهو غير متاح خارج بيئات المتصفّح). يؤدي ذلك إلى إتاحة إمكانية استخدام SSR في المنتجات التي تم تفعيل App Check فيها، مثل Cloud Functions وSQL Connect وCloud Firestore وRealtime Database وVertex AI.
يمكنك الاطّلاع على تبسيط عملية تطوير تطبيقات العرض من جهة الخادم باستخدام
FirebaseServerApp
للاطّلاع على مثال حول كيفية استخدام FirebaseServerApp في Next.js.