Zainstaluj, skonfiguruj i zintegruj pakiet lokalnego emulatora

Pakiet Firebase Local Emulator Suite można zainstalować i skonfigurować dla różnych środowisk prototypowych i testowych, od jednorazowych sesji prototypowania po przepływy pracy ciągłej integracji na skalę produkcyjną.

Zainstaluj pakiet lokalnego emulatora

Przed zainstalowaniem pakietu emulatorów będziesz potrzebować:

  • Wersja Node.js 16.0 lub nowsza.
  • Java JDK w wersji 11 lub nowszej.

Aby zainstalować pakiet emulatorów:

  1. Zainstaluj interfejs wiersza polecenia Firebase . Jeśli nie masz jeszcze zainstalowanego interfejsu CLI Firebase, zainstaluj go teraz . Aby korzystać z pakietu emulatorów, będziesz potrzebować interfejsu CLI w wersji 8.14.0 lub nowszej. Możesz sprawdzić, którą wersję zainstalowałeś, używając następującego polecenia:
    firebase --version
  2. Jeśli jeszcze tego nie zrobiłeś, zainicjuj bieżący katalog roboczy jako projekt Firebase, postępując zgodnie z instrukcjami wyświetlanymi na ekranie, aby określić, których produktów chcesz użyć:
    firebase init
  3. Skonfiguruj pakiet emulatorów. To polecenie uruchamia kreatora konfiguracji, który umożliwia wybranie interesujących emulatorów, pobranie odpowiednich plików binarnych emulatora i ustawienie portów emulatora, jeśli ustawienia domyślne nie są odpowiednie.
    firebase init emulators

Po zainstalowaniu emulatora nie są przeprowadzane żadne kontrole aktualizacji i nie będą wykonywane żadne dodatkowe automatyczne pobrania, dopóki nie zaktualizujesz wersji Firebase CLI.

Skonfiguruj pakiet emulatorów

Opcjonalnie możesz skonfigurować porty sieciowe emulatorów i ścieżkę do definicji reguł bezpieczeństwa w pliku firebase.json :

  • Zmień porty emulatora, uruchamiając firebase init emulators lub ręcznie edytując firebase.json .
  • Zmień ścieżkę do definicji reguł zabezpieczeń, edytując ręcznie firebase.json .

Jeśli nie skonfigurujesz tych ustawień, emulatory będą nasłuchiwać na swoich domyślnych portach, a emulatory Cloud Firestore, Realtime Database i Cloud Storage for Firebase będą działać z otwartymi zabezpieczeniami danych.

Komenda Opis
emulatory inicjacji Uruchom kreatora inicjalizacji emulatora. Zidentyfikuj emulatory do zainstalowania i opcjonalnie określ ustawienia portu emulatora. init emulators są nieniszczące; zaakceptowanie ustawień domyślnych spowoduje zachowanie bieżącej konfiguracji emulatora.

Konfiguracja portu

Każdy emulator wiąże się z innym portem na komputerze z preferowaną wartością domyślną.

Emulator Domyślny port
Uwierzytelnianie 9099
Interfejs pakietu emulatorów 4000
Funkcje chmury 5001
Eventarc 9299
Baza danych czasu rzeczywistego 9000
Chmura Firestore 8080
Magazyn w chmurze dla Firebase 9199
Hosting Firebase 5000
Pub/sub 8085

Konfiguracja identyfikatora projektu

W zależności od sposobu wywoływania emulatorów możesz uruchomić wiele instancji emulatora przy użyciu różnych identyfikatorów projektu Firebase lub wielu instancji emulatora dla danego identyfikatora projektu. W takich przypadkach instancje emulatora działają w oddzielnym środowisku.

Ogólnie dobrą praktyką jest ustawienie jednego identyfikatora projektu dla wszystkich wywołań emulatora, aby interfejs użytkownika pakietu emulatorów, emulatory różnych produktów i wszystkie uruchomione instancje określonego emulatora mogły się poprawnie komunikować we wszystkich przypadkach.

Local Emulator Suite generuje ostrzeżenia, gdy wykryje wiele identyfikatorów projektów w środowisku, chociaż można obejść to zachowanie, ustawiając klucz singleProjectMode na false w pliku firebase.json .

Możesz sprawdzić deklaracje identyfikatora projektu pod kątem niezgodności w:

  • Domyślny projekt w wierszu poleceń. Domyślnie identyfikator projektu zostanie pobrany podczas uruchamiania z projektu wybranego za pomocą firebase init lub firebase use . Aby wyświetlić listę projektów (i zobaczyć, który jest wybrany), użyj firebase projects:list .
  • Zasady testów jednostkowych. Identyfikator projektu jest często określany w wywołaniach metod biblioteki reguł testowania jednostkowego initializeTestEnvironment lub initializeTestApp .
  • Flaga wiersza poleceń --project . Przekazanie flagi Firebase CLI --project zastępuje projekt domyślny. Musisz upewnić się, że wartość flagi jest zgodna z identyfikatorem projektu w testach jednostkowych i inicjalizacji aplikacji.

Sprawdź także konfiguracje identyfikatorów projektów specyficzne dla platformy, które ustawiłeś podczas konfigurowania platform Apple , Android i projektów internetowych .

Konfiguracja reguł bezpieczeństwa

Emulatory pobiorą konfigurację reguł bezpieczeństwa z database , kluczy konfiguracyjnych firestore i storage w pliku firebase.json .

{
  // Existing firebase configuration ...
  "database": {
    "rules": "database.rules.json"
  },
  "firestore": {
    "rules": "firestore.rules"
  },
  "storage": {
    "rules": "storage.rules"
  }

  // ...

  // Optional emulator configuration. Default
  // values are used if absent.
  "emulators": {
    "singleProjectMode": false, // do not warn on detection of multiple project IDs
    "firestore": {
      "port": "8080"
    },
    "ui": {
      "enabled": true,      // Default is `true`
      "port": 4000          // If unspecified, see CLI log for selected port
    },
    "auth": {
      "port": "9099"
    },
    "pubsub": {
      "port": "8085"
    }
  }
}

Określanie opcji Java

Emulator bazy danych czasu rzeczywistego, emulator Cloud Firestore i część emulatora Cloud Storage for Firebase są oparte na Javie, którą można dostosować za pomocą flag JVM za pomocą zmiennej środowiskowej JAVA_TOOL_OPTIONS .

Na przykład, jeśli wystąpią błędy związane z przestrzenią sterty Java, możesz zwiększyć maksymalny rozmiar sterty Java do 4 GB:

export JAVA_TOOL_OPTIONS="-Xmx4g"
firebase emulators:start

Wiele flag można podać w cudzysłowie oddzielonych spacjami, np JAVA_TOOL_OPTIONS="-Xms2g -Xmx4g" . Flagi wpływają tylko na komponenty emulatorów oparte na Javie i nie mają wpływu na inne części interfejsu CLI Firebase, takie jak interfejs użytkownika pakietu Emulator Suite.

Uruchom emulatory

Możesz uruchomić emulatory, aby działały do ​​momentu ręcznego zakończenia, lub aby działały przez czas trwania wyznaczonego skryptu testowego, a następnie automatycznie się wyłączały.

Komenda Opis
emulatory:start Uruchom emulatory produktów Firebase skonfigurowanych w firebase.json . Procesy emulatora będą nadal działać, dopóki nie zostaną jawnie zatrzymane. Wywołanie emulators:start pobierze emulatory do ~/.cache/firebase/emulators/, jeśli nie są jeszcze zainstalowane.
Flaga Opis
--only Opcjonalny. Ogranicz uruchamianie emulatorów. Podaj rozdzieloną przecinkami listę nazw emulatorów, określając jedną lub więcej opcji „auth”, „database”, „firestore”, „functions”, „hosting” lub „pubsub”.
--inspect-functions debug_port Opcjonalny. Użyj z emulatorem Cloud Functions, aby włączyć debugowanie funkcji w punkcie przerwania na określonym porcie (lub domyślnym porcie 9229, jeśli pominięto argument). Należy pamiętać, że po podaniu tej flagi emulator Cloud Functions przełącza się na specjalny serializowany tryb wykonywania, w którym funkcje są wykonywane w jednym procesie, w kolejności (FIFO). upraszcza to debugowanie funkcji, chociaż zachowanie różni się od wieloprocesowego, równoległego wykonywania funkcji w chmurze.
--export-on-exit= Opcjonalny. Używaj z emulatorem Authentication, Cloud Firestore, Realtime Database lub Cloud Storage for Firebase. Poinstruuj emulatory, aby wyeksportowały dane do katalogu po wystąpieniu zamknięcia, zgodnie z opisem dla polecenia emulators:export . Katalog eksportu można określić za pomocą tej flagi: firebase emulators:start --export-on-exit=./saved-data . Jeśli zostanie użyte --import , domyślna ścieżka eksportu będzie taka sama; na przykład: firebase emulators:start --import=./data-path --export-on-exit . Na koniec, jeśli chcesz, przekaż różne ścieżki katalogów do flag --import i --export-on-exit .
--import= import_directory Opcjonalny. Używaj z emulatorem Authentication, Cloud Firestore, Realtime Database lub Cloud Storage for Firebase. Zaimportuj dane zapisane przy użyciu opcji uruchamiania --export-on-exit lub polecenia emulators:export do działającej instancji emulatora Authentication, Cloud Firestore, Realtime Database lub Cloud Storage for Firebase. Wszelkie dane aktualnie znajdujące się w pamięci emulatora zostaną nadpisane.
emulatory: scriptpath exec Uruchom skrypt w scriptpath po uruchomieniu emulatorów produktów Firebase skonfigurowanych w firebase.json . Procesy emulatora zostaną automatycznie zatrzymane po zakończeniu działania skryptu.
Flaga Opis
--only Opcjonalny. Ogranicz uruchamianie emulatorów. Podaj rozdzieloną przecinkami listę nazw emulatorów, określając jedną lub więcej opcji „firestore”, „baza danych”, „funkcje”, „hosting” lub „pubsub”.
--inspect-functions debug_port Opcjonalny. Użyj z emulatorem Cloud Functions, aby włączyć debugowanie funkcji w punkcie przerwania na określonym porcie (lub domyślnym porcie 9229, jeśli pominięto argument). Należy pamiętać, że po podaniu tej flagi emulator Cloud Functions przełącza się na specjalny serializowany tryb wykonywania, w którym funkcje są wykonywane w jednym procesie, w kolejności (FIFO). upraszcza to debugowanie funkcji, chociaż zachowanie różni się od wieloprocesowego, równoległego wykonywania funkcji w chmurze.
--export-on-exit= Opcjonalny. Używaj z emulatorem Authentication, Cloud Firestore, Realtime Database lub Cloud Storage for Firebase. Poinstruuj emulatory, aby wyeksportowały dane do katalogu po wystąpieniu zamknięcia, zgodnie z opisem dla polecenia emulators:export . Katalog eksportu można określić za pomocą tej flagi: firebase emulators:start --export-on-exit=./saved-data . Jeśli zostanie użyte --import , domyślna ścieżka eksportu będzie taka sama; na przykład: firebase emulators:start --import=./data-path --export-on-exit . Na koniec, jeśli chcesz, przekaż różne ścieżki katalogów do flag --import i --export-on-exit .
--import= import_directory Opcjonalny. Używaj z emulatorem Authentication, Cloud Firestore, Realtime Database lub Cloud Storage for Firebase. Zaimportuj dane zapisane przy użyciu opcji uruchamiania --export-on-exit lub polecenia emulators:export do działającej instancji emulatora Authentication, Cloud Firestore, Realtime Database lub Cloud Storage for Firebase. Wszelkie dane aktualnie znajdujące się w pamięci emulatora zostaną nadpisane.
--ui Opcjonalny. Uruchom interfejs emulatora podczas wykonywania.

Metoda firebase emulators:exec jest ogólnie bardziej odpowiednia w przypadku przepływów pracy ciągłej integracji.

Eksportuj i importuj dane emulatora

Możesz eksportować dane z emulatorów Authentication, Cloud Firestore, Realtime Database i Cloud Storage dla emulatorów Firebase, aby wykorzystać je jako wspólny, bazowy zestaw danych, który można udostępniać. Te zestawy danych można zaimportować przy użyciu flagi --import , jak opisano powyżej.

emulatory:eksportuj export_directory

Uwierzytelnianie, Cloud Firestore, baza danych czasu rzeczywistego lub Cloud Storage dla emulatora Firebase . Eksportuj dane z działającej instancji emulatora Cloud Firestore, Realtime Database lub Cloud Storage for Firebase. Określony export_directory zostanie utworzony, jeśli jeszcze nie istnieje. Jeżeli podany katalog istnieje, zostaniesz poproszony o potwierdzenie nadpisania danych poprzedniego eksportu. Możesz pominąć ten monit, używając flagi --force . Katalog eksportu zawiera plik manifestu danych, firebase-export-metadata.json .

Możesz poinstruować emulatory, aby automatycznie eksportowały dane po zamknięciu, używając flag --export-on-exit opisanych powyżej.

Zintegruj się ze swoim systemem CI

Uruchamianie skonteneryzowanych obrazów pakietu emulatorów

Instalacja i konfiguracja pakietu Emulator Suite z kontenerami w typowej konfiguracji CI jest prosta.

Warto zwrócić uwagę na kilka kwestii:

  • Pliki JAR są instalowane i buforowane w ~/.cache/firebase/emulators/ .

    • Możesz dodać tę ścieżkę do konfiguracji pamięci podręcznej CI, aby uniknąć wielokrotnego pobierania.
  • Jeśli nie masz w repozytorium pliku firebase.json , musisz dodać argument wiersza poleceń do poleceń emulators:start lub emulators:exec aby określić, które emulatory mają zostać uruchomione. Na przykład,
    --only functions,firestore .

Wygeneruj token uwierzytelniający (tylko emulator hostingu)

Jeśli Twoje przepływy pracy ciągłej integracji opierają się na Hostingu Firebase, będziesz musiał zalogować się przy użyciu tokena, aby uruchomić firebase emulators:exec . Pozostałe emulatory nie wymagają logowania.

Aby wygenerować token, uruchom firebase login:ci w swoim środowisku lokalnym; nie należy tego wykonywać z poziomu systemu CI. Postępuj zgodnie z instrukcjami, aby uwierzytelnić. Ten krok należy wykonać tylko raz na projekt, ponieważ token będzie ważny we wszystkich kompilacjach. Token należy traktować jak hasło; upewnij się, że jest to utrzymywane w tajemnicy.

Jeśli środowisko CI umożliwia określenie zmiennych środowiskowych, których można używać w skryptach kompilacji, po prostu utwórz zmienną środowiskową o nazwie FIREBASE_TOKEN , której wartością będzie ciąg tokenu dostępu. Interfejs Firebase CLI automatycznie pobierze zmienną środowiskową FIREBASE_TOKEN i emulatory uruchomią się poprawnie.

W ostateczności możesz po prostu umieścić token w skrypcie kompilacji, ale upewnij się, że niezaufane strony nie mają do niego dostępu. W przypadku tego zakodowanego podejścia możesz dodać --token "YOUR_TOKEN_STRING_HERE" do polecenia firebase emulators:exec .

Użyj interfejsu API REST centrum emulatora

Lista działających emulatorów

Aby wyświetlić listę aktualnie działających emulatorów, wyślij żądanie GET do punktu końcowego /emulators w centrum emulatorów.

curl localhost:4400/emulators

Wynikiem będzie obiekt JSON zawierający listę wszystkich działających emulatorów i ich konfiguracji hosta/portu, na przykład:

{
  "hub":{
    "name": "hub",
    "host": "localhost",
    "port": 4400
  },
  "functions": {
    "name": "functions",
    "host": "localhost",
    "port": 5001
  }
  "firestore": {
    "name": "firestore",
    "host": "localhost",
    "port": 8080
  }
}

Włącz/wyłącz wyzwalacze funkcji w tle

W niektórych sytuacjach konieczne będzie tymczasowe wyłączenie lokalnych wyzwalaczy funkcji i rozszerzeń. Na przykład możesz chcieć usunąć wszystkie dane z emulatora Cloud Firestore bez wyzwalania jakichkolwiek funkcji onDelete działających w emulatorach Cloud Functions lub Extensions.

Aby tymczasowo wyłączyć wyzwalacze funkcji lokalnych, wyślij żądanie PUT do punktu końcowego /functions/disableBackgroundTriggers w centrum emulatora.

curl -X PUT localhost:4400/functions/disableBackgroundTriggers

Wynikiem będzie obiekt JSON szczegółowo opisujący bieżący stan.

{
  "enabled": false
}

Aby włączyć wyzwalacze funkcji lokalnych po ich wyłączeniu, wyślij żądanie PUT do punktu końcowego /functions/enableBackgroundTriggers w centrum emulatora.

curl -X PUT localhost:4400/functions/enableBackgroundTriggers

Wynikiem będzie obiekt JSON szczegółowo opisujący bieżący stan.

{
  "enabled": true
}

Integracje emulatora SDK

Tabele w tej sekcji wskazują, które emulatory są obsługiwane przez zestawy SDK klienta i administratora. Przyszłość oznacza, że ​​obsługa emulatorów jest planowana, ale nie jest jeszcze dostępna.

Dostępność pakietu SDK klienta

Android Platformy Apple Sieć Interfejs Firebase
Android
Interfejs Firebase
iOS
Interfejs Firebase
Sieć
Baza danych czasu rzeczywistego 19.4.0 7.2.0 8.0.0 6.4.0 Przyszły Nie dotyczy
Chmura Firestore 21.6.0 7.2.0 8.0.0 6.4.0 Przyszły Nie dotyczy
Uwierzytelnianie 20.0.0 7.0.0 8.0.0 7.0.0 Przyszły 4.7.2
Magazyn w chmurze dla Firebase 20.0.0 8.0.0 8.4.0 7.0.0 11.0.0 Nie dotyczy
Funkcje chmury 19.1.0 7.2.0 8.0.0 Nie dotyczy Nie dotyczy Nie dotyczy
Hosting Nie dotyczy Nie dotyczy Nie dotyczy Nie dotyczy Nie dotyczy Nie dotyczy
Rozszerzenia Nie dotyczy Nie dotyczy Nie dotyczy Nie dotyczy Nie dotyczy Nie dotyczy

Dostępność pakietu Admin SDK

Węzeł Jawa Pyton Iść
Baza danych czasu rzeczywistego 8.6.0 6.10.0 2.18.0 Przyszły
Chmura Firestore 8.0.0 6.10.0 3.0.0 1.0.0
Uwierzytelnianie 9.3.0 7.2.0 5.0.0 4.2.0
Magazyn w chmurze dla Firebase 9.8.0 Przyszły Przyszły Przyszły
Funkcje chmury Nie dotyczy Nie dotyczy Nie dotyczy Nie dotyczy
Hosting Nie dotyczy Nie dotyczy Nie dotyczy Nie dotyczy
Rozszerzenia Nie dotyczy Nie dotyczy Nie dotyczy Nie dotyczy