שיטות מומלצות ל-Firebase JavaScript SDK

בדף הזה מופיעים טיפים לפתרון בעיות ב-JavaScript שאתם עשויים להיתקל בהן במהלך השימוש ב-SDK‏ Firebase JavaScript.

נתקלת בבעיות אחרות או שהבעיה שלך לא מופיעה כאן? מומלץ לעיין בשאלות הנפוצות הראשיות בנושא Firebase כדי לקבל מידע נוסף על Firebase באופן כללי או על מוצרים ספציפיים.

אפשר גם לעיין בFirebase JavaScriptמאגר ה-SDK ב-GitHub כדי לראות רשימה עדכנית של בעיות שדווחו ופתרונות לבעיות, ולדווח שם על בעיות משלכם.

הקונסטרוקציות של Admin SDK ל-Node.js לא תואמות ל-Firebase JavaScript SDK

‫Firebase Admin SDK ל-Node.js ו-Firebase JavaScript SDK הם הטמעות נפרדות שלא חולקות הגדרות של ממשק, מחלקה או פונקציה. מופעים של אובייקטים מסוג Admin SDK לא תואמים לפונקציות של Firebase JavaScript SDK.

לדוגמה, מופע של Admin SDK שמועבר לפונקציית Firebase JavaScript SDK getDatabase יפיק את השגיאה הבאה:FirebaseApp

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

זה נכון לכל Firebase JavaScript SDK API surface, ולא רק ל-Realtime Database. הדבר נכון גם לגבי שימוש בכיוון ההפוך. כשמנסים להשתמש בסוג Cloud Firestore של JS SDK Timestamp עם Firebase Admin SDK עבור Node.js, מתקבלות שגיאות דומות.

מומלץ להימנע משימוש בגרסאות סותרות של Firebase JavaScript SDK

אם מוגדרות כמה גרסאות סותרות של Firebase JavaScript SDK כתלות בפרויקט, יתרחשו שגיאות בזמן הריצה כשמועברים מופעים של SDK בין חבילות SDK. לדוגמה, שימוש בספרייה Data Connect עם גרסה לא תואמת של FirebaseApp גורם לשגיאה הבאה:

Error: Component data-connect has not been registered yet

הבעיה הזו נגרמת בדרך כלל בגלל עדכון של תלות באחד מחבילות Firebase SDK, אבל לא בכולן. המצב הזה קורה בדרך כלל כשכלי אוטומטי לעדכון תלויות משנה משנה קבוצת משנה של תלויות משנה ב-Firebase SDK בקובץ 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 שמייבא גרסה מתנגשת של 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

יכול להיות שגם ערבוב של הצהרות CJS ו-ESM‏ require ו-import באפליקציה יגרום לשגיאות. כך נוצרים כמה מופעים של Firebase JavaScript SDK, שכל אחד מהם שונה מהאחרים, ולכן לא ניתן להשתמש ב-Firebase JavaScript SDK. כדי לנפות באגים בתרחיש הזה, צריך להגדיל את רמת הפירוט של חבילת ה-bundler שבחרתם. לדוגמה, אפשר להשתמש בסימן esbuild analyze למטרה הזו.

מוודאים ש-service workers נכללים בחבילה

קובצי שירות (service worker) נוצרים בדרך כלל מצינור עיבוד נתונים נפרד משאר אפליקציית האינטרנט, והם לא נכללים בהגדרות ברירת המחדל של כלי חבילה כמו Webpack.

אם אתם משתמשים בגרסה המודולרית של Firebase JavaScript SDK ב-service worker, עליכם לוודא שהגדרתם את כלי האריזה של האפליקציה כך שיכלול את קובץ המקור של ה-service worker. בדוגמה הבאה נעשה שימוש ב-npx כדי לארוז את ה-service worker של השירות 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 באפליקציה.

לחלופין, אפשר לייבא את חבילות ה-SDK של compat Firebase JavaScript מ-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 נועד במקור לפעול בסביבות דפדפן. ההשקה של מסגרות Server-Side Rendering ‏ (SSR) מאפשרת שימוש ב-SDK בסביבות זמן ריצה חדשות. סביבות זמן הריצה האלה מספקות קבוצת משנה של כלים וממשקי API שדפדפני אינטרנט מספקים.

לדוגמה, חלק מערכות Firebase SDK דורשות אחסון במטמון של נתונים באמצעות IndexedDB, שהוא API שפועל רק בדפדפן. יכול להיות ש-Firebase Auth ידרוש אינטראקציה של המשתמש בתהליכי כניסה מסוימים, ואינטראקציה כזו לא אפשרית בסביבות שרת ללא ממשק גרפי. ‫App Check מסתמך על היוריסטיקה של הדפדפן כדי לאמת את המשתמש לפני יצירת טוקנים של App Check.

כשעובדים עם ה-SDK בסביבות החדשות האלה, צריך להשתמש ב-FirebaseServerApp, גרסה חדשה של FirebaseApp שמספקת את האמצעים לטעינה מראש של מופע Firebase של SSR עם נתונים שנאספו בצד הלקוח.

הפונקציה FirebaseServerApp תומכת בשני פרמטרים:

• טוקן מזהה לאימות: אם הוא מסופק, Firebase Auth מבצע כניסה אוטומטית של משתמש שאומת בעבר, ויכול להיות שהסשן יתפרס על פני CSR או SSR.
• App Check Token: אם מספקים את הטוקן, ערכות ה-SDK האחרות של Firebase משתמשות בו בלי צורך לאתחל מופע של לקוח App Check (שלא נתמך מחוץ לסביבות דפדפן). השינוי הזה מאפשר תמיכה ב-SSR במוצרים שבהם App Check מופעל, כמו Cloud Functions, Data Connect, Cloud Firestore, Realtime Database ו-Vertex AI.

דוגמה לשימוש ב-FirebaseServerApp ב-Next.js מופיעה במאמר Streamline SSR app development with FirebaseServerApp.