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

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

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

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

لا تتوافق بُنى Admin SDK لـ Node.js مع حزمة Firebase JavaScript SDK

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

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

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

ينطبق ذلك على واجهة برمجة التطبيقات الكاملة لحزمة Firebase JavaScript SDK، وليس على Realtime Database فقط. وينطبق أيضًا على الاستخدام في الاتجاه المعاكس. تؤدي محاولة استخدام الـ Cloud Firestore JS SDK's Timestamp نوع مع الـ Firebase Admin SDK لـ Node.js إلى ظهور أخطاء مماثلة.

تجنَّب استخدام إصدارات متعارضة من حزمة Firebase JavaScript SDK

سيؤدي استخدام إصدارات متعدّدة ومتعارضة من Firebase JavaScript SDK تم ضبطها كعناصر تابعة في مشروع إلى ظهور أخطاء في وقت التشغيل عند تمرير نُسخ حزمة SDK بين حِزم SDK. على سبيل المثال، يؤدي استخدام مكتبة SQL Connect مع إصدار غير متطابق من FirebaseApp إلى ظهور الخطأ التالي:

Error: Component data-connect has not been registered yet

تحدث هذه المشكلة عادةً بسبب تعديل عنصر تابع واحد من حِزم Firebase SDK، وليس جميعها. يحدث ذلك غالبًا عندما تغيِّر أداة تعديل العناصر التابعة التلقائية مجموعة فرعية من العناصر التابعة لحزمة Firebase SDK ضمن ملف yarn.lock أو package-lock.json الخاص بالمشروع. بما أنّ العديد من Firebase JavaScript حِزم SDK تتوافق مع بعضها البعض، يؤدي استخدام إصدارات مختلفة من حِزم SDK إلى ظهور حالات عدم توافق في وقت التشغيل.

لحلّ هذه المشكلة، احذف الدليل node_modules/ والملف yarn.lock (بالنسبة إلى yarn) أو package-lock.json (بالنسبة إلى npm) في مشروعك وأعِد تثبيت العناصر التابعة.

إذا استمرت الأخطاء، يمكنك تحديد المشكلة وحلّها بشكل أكبر باستخدام الأمر npm ls command. سيؤدي ذلك إلى تسجيل العناصر التابعة لمشروعك حتى تتمكّن من تحديد الإصدارات المتعارضة من الوحدة firebase.

على سبيل المثال، يعرض السجلّ التالي package-using-older-firebase الذي يستورد إصدارًا متعارضًا من Firebase JavaScript SDK:

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

تأكَّد من تجميع مشغّلي الخدمات

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

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

كانت حزمة Firebase JavaScript SDK مخصّصة في الأصل للتشغيل في بيئات المتصفّح. يؤدي طرح أُطر عمل العرض على جهة الخادم (SSR) إلى استخدام حزمة SDK في بيئات وقت تشغيل جديدة. توفّر أوقات التشغيل هذه مجموعة فرعية من الأدوات وواجهات برمجة التطبيقات التي توفّرها متصفّحات الويب.

على سبيل المثال، تتطلّب بعض حِزم Firebase SDK تخزين البيانات مؤقتًا باستخدام IndexedDB، وهي واجهة برمجة تطبيقات خاصة بالمتصفّح فقط. قد يتطلّب Firebase Auth تفاعل المستخدم في بعض مسارات تسجيل الدخول التي لا يمكن تنفيذها في بيئات الخادم بدون واجهة مستخدم رسومية. App Check تعتمد على الإحصاءات التقريبية للمتصفّح للتحقّق من صحة المستخدم قبل إنشاء رموز App Check.

عند استخدام حزمة SDK في هذه البيئات الجديدة، استخدِم FirebaseServerApp، وهو نوع جديد من FirebaseApp يوفّر وسائل تحميل نُسخة SSR من Firebase مسبقًا بالبيانات التي تم جمعها من جهة العميل.

تتوافق FirebaseServerApp مع مَعلَمَتين:

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

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