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

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

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

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

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

إنّ Firebase Admin SDK for 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 لهذا الغرض.

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

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

بدلاً من ذلك، يمكنك إزالة الحاجة إلى التجميع من خلال استيراد حِزم 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 SDKs الأخرى بدون الحاجة إلى تهيئة نُسخة من عميل App Check (غير المتوافق خارج بيئات المتصفح). يؤدي ذلك إلى إتاحة ميزة العرض على جهة الخادم للمنتجات التي تم تفعيل ميزة App Check فيها، مثل Cloud Functions وSQL Connect وCloud Firestore وRealtime Database و Vertex AI.

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