بهترین شیوه های Firebase JavaScript SDK

این صفحه نکات و عیب‌یابی مشکلات جاوا اسکریپت را ارائه می‌دهد که ممکن است هنگام استفاده از Firebase JavaScript SDK با آنها مواجه شوید.

چالش های دیگری دارید یا مشکل خود را نمی بینید؟ حتماً سؤالات متداول اصلی Firebase را برای سؤالات متداول pan-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 ناسازگار هستند.

به عنوان مثال، یک نمونه از FirebaseApp Admin SDK که به تابع Firebase JavaScript SDK getDatabase ارسال می‌شود، خطای زیر را ایجاد می‌کند:

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

این برای کل سطح Firebase JavaScript SDK API صادق است، نه فقط Realtime Database . برای استفاده در جهت مخالف نیز صادق است. تلاش برای استفاده از نوع Timestamp Cloud Firestore JS SDK با 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 پروژه تغییر می‌دهد. از آنجایی که بسیاری از Firebase JavaScript SDK با یکدیگر کار می کنند، استفاده از نسخه های مختلف 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

همچنین ممکن است به دلیل اختلاط عبارات require و import CJS و ESM در برنامه شما، خطاهایی رخ دهد. این چندین نمونه از Firebase JavaScript SDK ایجاد می کند که هر کدام از دیگری متمایز است، که قابلیت همکاری Firebase JavaScript SDK را از بین می برد. برای رفع اشکال این سناریو، پرحرفی باندلر انتخابی خود را افزایش دهید. برای مثال می توانید از پرچم تجزیه و تحلیل esbuild برای این منظور استفاده کنید.

اطمینان حاصل کنید که کارگران خدماتی بسته‌بندی شده‌اند

کارگران خدمات اغلب از یک خط لوله مجزا از بقیه برنامه های وب ساخته می شوند و در پیکربندی پیش فرض بسته ها مانند Webpack گنجانده نمی شوند.

اگر از نسخه مدولار Firebase JavaScript SDK در سرویس‌کار خود استفاده می‌کنید، مطمئن شوید که باندلر برنامه خود را به گونه‌ای پیکربندی کرده‌اید که فایل منبع سرویس‌کار را نیز در بر گیرد. مثال زیر از 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 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 را به محیط های زمان اجرا جدید سوق می دهد. این زمان‌های اجرا زیرمجموعه‌ای از ابزارها و APIهایی را که مرورگرهای وب ارائه می‌کنند، ارائه می‌کنند.

به عنوان مثال، برخی از Firebase SDK ها به ذخیره سازی داده با IndexedDB، یک API فقط برای مرورگر، نیاز دارند. Firebase Auth ممکن است نیاز به تعامل کاربر در جریان‌های ورود به سیستم خاص داشته باشد که در محیط‌های سرور بدون هد غیرممکن است. App Check به اکتشافات مرورگر برای تأیید اعتبار کاربر قبل از ایجاد نشانه های App Check متکی است.

هنگام کار با SDK در این محیط‌های جدید، از FirebaseServerApp ، یک نوع جدید از FirebaseApp استفاده کنید که ابزاری را برای بارگذاری اولیه نمونه SSR Firebase با داده‌هایی که از سمت سرویس گیرنده جمع‌آوری شده است، فراهم می‌کند.

FirebaseServerApp از دو پارامتر پشتیبانی می کند:

• Auth ID Token : در صورت ارائه، Firebase Auth به طور خودکار در یک کاربر تأیید شده قبلی امضا می‌کند، و به طور بالقوه یک جلسه را در سراسر تقسیم CSR / SSR در بر می‌گیرد.
• نشانه بررسی برنامه : در صورت ارائه، رمز توسط سایر SDK های Firebase بدون نیاز به مقداردهی اولیه یک نمونه از یک کلاینت App Check (که در خارج از محیط های مرورگر پشتیبانی نمی شود) استفاده می شود. این پشتیبانی SSR را برای محصولاتی که دارای App Check فعال هستند، از جمله Cloud Functions ، Data Connect ، Cloud Firestore ، Realtime Database و Vertex AI مسدود می‌کند.

برای مثال استفاده از FirebaseServerApp در Next.js ، توسعه برنامه SSR را با FirebaseServerApp ساده کنید.