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

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

چالش‌های دیگری دارید یا مشکل خود را نمی‌بینید؟ برای سوالات متداول بیشتر در مورد Firebase یا سوالات متداول مربوط به محصول، حتماً به بخش اصلی سوالات متداول Firebase مراجعه کنید.

همچنین می‌توانید مخزن گیت‌هاب Firebase JavaScript SDK را برای فهرست به‌روز مشکلات گزارش‌شده و عیب‌یابی بررسی کنید و مشکلات خود را در آنجا ثبت کنید.

Admin SDK برای سازه‌های Node.js با SDK JavaScript Firebase سازگار نیست.

Firebase Admin SDK برای Node.js و کیت Firebase JavaScript فایربیس، پیاده‌سازی‌های مجزایی هستند که رابط، کلاس یا تعاریف تابع را به اشتراک نمی‌گذارند. نمونه‌هایی از اشیاء Admin SDK با توابع کیت توسعه Firebase JavaScript سازگار نیستند.

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

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

این موضوع نه فقط در مورد Realtime Database ، بلکه در مورد کل سطح API Firebase JavaScript SDK نیز صادق است. همچنین در مورد استفاده در جهت مخالف نیز صادق است. تلاش برای استفاده از نوع Timestamp مربوط Cloud Firestore JS SDK با Firebase Admin SDK برای Node.js خطاهای مشابهی ایجاد می‌کند.

از استفاده از نسخه‌های متناقض کیت توسعه نرم‌افزار JavaScript Firebase خودداری کنید.

چندین نسخه متناقض از 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های JavaScript Firebase با یکدیگر تعامل دارند، استفاده از نسخه‌های مختلف 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 را مختل می‌کنند. برای اشکال‌زدایی این سناریو، میزان شفافیت bundler مورد نظر خود را افزایش دهید. به عنوان مثال، می‌توانید از پرچم analyze مربوط به esbuild برای این منظور استفاده کنید.

مطمئن شوید که سرویس ورکرها به صورت دسته‌ای (bundle) هستند

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

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

از طرف دیگر، می‌توانید با وارد کردن بسته‌های SDK JavaScript compat Firebase از 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 استفاده کنید

کیت توسعه نرم‌افزار جاوا JavaScript Firebase JavaScript SDK) در ابتدا برای اجرا در محیط‌های مرورگر در نظر گرفته شده بود. معرفی چارچوب‌های رندر سمت سرور (SSR)، استفاده از SDK را به محیط‌های زمان اجرای جدید سوق می‌دهد. این زمان‌های اجرا زیرمجموعه‌ای از ابزارها و APIهایی را که مرورگرهای وب ارائه می‌دهند، فراهم می‌کنند.

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

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

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

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

برای مثال، به بخش «توسعه ساده‌تر برنامه SSR با FirebaseServerApp» FirebaseServerApp کنید.