Sprawdzone metody dotyczące pakietu Firebase JavaScript SDK

Ta strona zawiera wskazówki i porady dotyczące rozwiązywania problemów z JavaScriptem, które mogą wystąpić podczas korzystania z pakietu SDK Firebase JavaScript.

Masz inne problemy lub nie widzisz swojego problemu? Aby dowiedzieć się więcej o Firebase lub poszczególnych usługach, zapoznaj się z najczęstszymi pytaniami dotyczącymi Firebase.

Aktualną listę zgłoszonych problemów i sposobów ich rozwiązania znajdziesz też na Firebase JavaScriptrepozytorium GitHub pakietu SDK. Możesz tam też zgłaszać własne problemy.

Obiekty Admin SDK w Node.js nie są zgodne z pakietem SDK Firebase JavaScript

Pakiet SDK Firebase Admin SDK dla Node.js i pakiet SDK Firebase JavaScript to różne implementacje, które nie mają wspólnych definicji interfejsów, klas ani funkcji. Obiekty Admin SDK są niezgodne z funkcjami Firebase JavaScript w SDK.

Na przykład instancja obiektu Admin SDK o nazwie FirebaseApp przekazana do funkcji Firebase JavaScript pakietu SDK getDatabase powoduje ten błąd:

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

Dotyczy to całej interfejsu API pakietu SDK Firebase JavaScript, a nie tylko Realtime Database. To samo dotyczy korzystania w przeciwnym kierunku. Próba użycia typu Timestamp pakietu Cloud Firestore JS SDK z typem Firebase Admin SDK w Node.js powoduje podobne błędy.

Unikaj używania wersji pakietu SDK Firebase JavaScript, które się wykluczają

Wiele sprzecznych wersji pakietu SDK Firebase JavaScript skonfigurowanego jako zależności w projekcie spowoduje błędy czasu wykonywania, gdy instancje pakietu SDK będą przekazywane między pakietami SDK. Na przykład korzystanie z biblioteki Data Connect z niepasującą wersją biblioteki FirebaseApp powoduje ten błąd:

Error: Component data-connect has not been registered yet

Ten problem jest zwykle spowodowany aktualizacją zależności jednego z pakietów Firebase SDK, ale nie wszystkich. Zdarza się to często, gdy automatyczne narzędzie do aktualizacji zależności zmienia podzbiór zależności pakietu SDK Firebase w pliku yarn.lock lub package-lock.json projektu. Ponieważ wiele pakietów SDK Firebase JavaScript współdziała ze sobą, używanie różnych wersji pakietów SDK powoduje niezgodności w czasie wykonywania.

Aby rozwiązać ten problem, usuń katalog node_modules/ i plik yarn.lock (w przypadku yarn) lub package-lock.json (w przypadku npm) w projekcie i ponownie zainstaluj zależności.

Jeśli błędy pozostaną, debuguj problem dalej za pomocą polecenia npm ls. Spowoduje to odnotowanie zależności projektu, dzięki czemu możesz zidentyfikować sprzeczne wersje modułu firebase.

Na przykład w tym logowaniu widać, że package-using-older-firebase importuje wersję pakietu SDK Firebase JavaScript, która jest niezgodna z innymi:

$ 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

Błędy mogą też występować z powodu łączenia w aplikacji instrukcji requireimport pakietu CJS oraz ESM. Powoduje to utworzenie wielu instancji pakietu SDK Firebase JavaScript, z których każda jest inna od pozostałych, co powoduje niekompatybilność pakietu SDK Firebase JavaScript. Aby debugować ten scenariusz, zwiększ poziom szczegółowości wybranego pakietu. W tym celu możesz na przykład użyć flagi esbuild analyze.

Upewnij się, że usługa jest w pakiecie

Skrypty service worker są często tworzone w ramach osobnego potoku niż reszta aplikacji internetowej i nie są uwzględniane w domyślnej konfiguracji narzędzi do tworzenia pakietów, takich jak Webpack.

Jeśli w usługach workera używasz modułowej wersji pakietu SDK Firebase JavaScript, skonfiguruj narzędzie do tworzenia pakietów aplikacji tak, aby zawierało plik źródłowy usługi workera. W tym przykładzie użyto npx do zgrupowania firebase-sw.js workera usługi w katalogu src projektu:

npx esbuild ./src/firebase-sw.js --bundle --minify --main-fields=webworker,browser,module,main,default --outfile=public/firebase-sw.js

Aktywacja skryptu service worker, który nie jest w pakiecie, zakończy się niepowodzeniem, jeśli jego źródła importują moduły ES, które nie obsługują skryptów service worker, lub pliki, które nie istnieją w zakresie skryptu service worker. Czasami te błędy są nieme i trudno je debugować.

Więcej informacji o zbiorcach modułów w Firebase znajdziesz w artykule Korzystanie z zbiorców modułów w Firebase.Firebase JavaScript

Możesz też zrezygnować z pakowania, importując pakiety SDK compat Firebase JavaScript z 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();

Używaj FirebaseServerApp podczas pracy z renderowaniem po stronie serwera

Pakiet SDK Firebase JavaScript został pierwotnie zaprojektowany do działania w środowiskach przeglądarek. Wprowadzenie frameworków renderowania po stronie serwera (SSR) powoduje, że pakiet SDK jest używany w nowych środowiskach uruchomieniowych. Te środowisko wykonawcze udostępnia podzbiór narzędzi i interfejsów API, które oferują przeglądarki internetowe.

Na przykład niektóre pakiety Firebase SDK wymagają buforowania danych za pomocą IndexedDB, czyli interfejsu API tylko dla przeglądarki. W niektórych procesach logowania Firebase Auth może wymagać interakcji użytkownika, co jest niemożliwe w środowiskach serwera bez głowy. App Check korzysta z heurystyk przeglądarki do weryfikowania użytkownika przed utworzeniem tokenów App Check.

Podczas pracy z pakietem SDK w tych nowych środowiskach używaj pakietu FirebaseServerApp, nowej wersji pakietu FirebaseApp, który umożliwia wstępne wczytywanie wystąpienia Firebase SSR za pomocą danych zebranych po stronie klienta.

FirebaseServerApp obsługuje 2 parametry:

  • Token identyfikatora uwierzytelniania: jeśli zostanie podany, Uwierzytelnianie Firebase automatycznie zaloguje wcześniej uwierzytelnionego użytkownika, potencjalnie obejmując sesję w ramach podziału CSR/SSR.
  • Token Sprawdzania aplikacji: jeśli zostanie podany, będzie używany przez inne pakiety SDK Firebase bez konieczności inicjowania instancji klienta App Check (który nie jest obsługiwany poza środowiskami przeglądarek). Spowoduje to odblokowanie obsługi SSR w przypadku usług, w których włączono App Check, takich jak Cloud Functions, Data Connect, Cloud Firestore, Realtime Database i Vertex AI.

Aby dowiedzieć się, jak używać funkcji FirebaseServerApp w Next.js, przeczytaj artykuł Upraszczanie tworzenia aplikacji SSR za pomocą FirebaseServerApp.