أفضل الممارسات المتعلقة بحزمة تطوير البرامج (SDK) لـ JavaScript في Firebase

تقدّم هذه الصفحة نصائح وخطوات تحديد المشاكل وحلّها في JavaScript التي قد تواجهها عند استخدام حزمة SDK Firebase JavaScript.

هل لديك مشاكل أخرى أو لا تظهر لك مشكلتك؟ يُرجى الاطّلاع على الأسئلة الشائعة الرئيسية حول Firebase للحصول على المزيد من الأسئلة الشائعة حول Firebase بشكل عام أو حول منتج معيّن.

يمكنك أيضًا الاطّلاع على Firebase JavaScript حزمة SDK GitHub المستودع للحصول على قائمة محدّثة ب المشاكل التي تم الإبلاغ عنها وتحديد المشاكل وحلّها، ويمكنك أيضًا إرسال مشاكلك هناك.

Admin SDK لإنشاءات Node.js غير متوافقة مع حزمة تطوير البرامج (SDK) Firebase JavaScript

إنّ حزمة Firebase Admin SDK لنظام التشغيل Node.js وحزمة Firebase JavaScript SDK هما تنفيذان مختلفان لا يتشاركان تعريفات الواجهات أو الفئات أو الدوالّ. إنّ نُسخ عناصر Admin SDK غير متوافقة مع وظائف Firebase JavaScript SDK.

على سبيل المثال، تؤدي إحدى نُسخ FirebaseApp في Admin SDK التي تم تمريرها إلى دالة Firebase JavaScript SDK getDatabase إلى ظهور الخطأ التالي:

TypeError: Cannot read properties of undefined (reading 'getProvider')
 at _getProvider
 at getDatabase

وينطبق ذلك على جميع واجهات برمجة تطبيقات حزمة تطوير البرامج (SDK) لنظام التشغيل Firebase JavaScript، وليس على Realtime Database فقط. وينطبق ذلك أيضًا على الاستخدام في الاتجاه المعاكس. يؤدي محاولة استخدام نوع Timestamp لCloud Firestore JS SDK مع 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

قد تحدث أيضًا أخطاء بسبب خلط عبارات require وimport في CJS وESM في تطبيقك. يؤدي ذلك إلى إنشاء مثيلات متعددة من حزمة تطوير البرامج (SDK) Firebase JavaScript، كل منها مختلف عن الآخر، ما يؤدي إلى إيقاف إمكانية التشغيل التفاعلي لحزمة تطوير البرامج (SDK) Firebase JavaScript. يمكنك زيادة مستوى التفصيل في أداة تجميع الحِزم التي تختارها لتصحيح أخطاء هذا السيناريو. على سبيل المثال، يمكنك استخدام العلامة esbuild analyze لهذا الغرض.

تأكَّد من تجميع مهام الخدمة.

غالبًا ما يتم إنشاء مشغّلي الخدمات من سلسلة مهام منفصلة عن بقية التطبيقات المتوافقة مع الويب، ولا يتم تضمينها في الإعداد التلقائي لأدوات تجميع الحِزم، مثل Webpack.

إذا كنت تستخدم الإصدار المُركّب من حزمة SDK لنظام التشغيل Firebase JavaScript في خدمة worker، تأكَّد من ضبط أداة تجميع التطبيقات لتضمين ملف مصدر service worker. يستخدم المثال التالي npx لتجميع عامل الخدمة firebase-sw.js في دليل 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 لميزة "الاستجابة السريعة للطلبات" مسبقًا بالبيانات التي تم جمعها من جهة العميل.

تتيح FirebaseServerApp مَعلمتَين:

• رمز تعريف المصادقة: في حال توفّره، تسجِّل Firebase Auth دخول مستخدم تمّت مصادقة هويته سابقًا تلقائيًا، ما قد يشمل جلسة على مستوى CSR / SSR.
• رمز App Check المميّز: في حال توفّره، تستخدم حِزم تطوير البرامج (SDK) الأخرى في Firebase رمز المميّز بدون الحاجة إلى بدء تشغيل مثيل لعميل App Check (الذي لا يكون متوافقًا خارج بيئات المتصفّحات). يؤدي ذلك إلى إتاحة استخدام ميزة SSR للمنتجات التي تم تفعيل App Check فيها، مثل Cloud Functions وData Connect وCloud Firestore وRealtime Database وVertex AI.

اطّلِع على مقالة تسهيل تطوير التطبيقات المستندة إلى نموذج الاستجابة السريعة باستخدام FirebaseServerApp في Next.js للحصول على مثال على استخدام FirebaseServerApp في Next.js.