Catch up on highlights from Firebase at Google I/O 2023. Learn more

Zainstaluj, skonfiguruj i zintegruj pakiet lokalnych emulatorów

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 lokalnych emulatorów

Przed zainstalowaniem Emulator Suite będziesz potrzebować:

  • Node.js w wersji 16.0 lub nowszej.
  • 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 Firebase CLI, zainstaluj go teraz . Do korzystania z pakietu emulatorów potrzebny będzie interfejs 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 ani żadne dodatkowe automatyczne pobieranie, 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ł bezpieczeństwa, ręcznie edytując 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 startowe Uruchom kreatora inicjalizacji emulatora. Zidentyfikuj emulatory do zainstalowania i opcjonalnie określ ustawienia portu emulatora. init emulators są nieniszczące; zaakceptowanie wartości domyślnych spowoduje zachowanie bieżącej konfiguracji emulatora.

Konfiguracja portu

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

Emulator Port domyślny
Uwierzytelnianie 9099
Interfejs pakietu emulatorów 4000
Funkcje chmury 5001
Eventarc 9299
Baza danych czasu rzeczywistego 9000
Cloud Firestore 8080
Przechowywanie w chmurze dla Firebase 9199
Hosting Firebase 5000
Publikacja/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 osobnym środowisku.

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

Pakiet Local Emulator Suite generuje ostrzeżenia, gdy wykryje wiele identyfikatorów projektów w środowisku, ale można zmienić 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 z nich jest wybrany), użyj firebase projects:list .
  • Reguły testów jednostkowych. Identyfikator projektu jest często określany w wywołaniach metod biblioteki testów jednostkowych reguł initializeTestEnvironment lub initializeTestApp .
  • Linia poleceń --project flaga. Przekazanie flagi Firebase CLI --project zastępuje domyślny projekt. Musisz upewnić się, że wartość flagi jest zgodna z identyfikatorem projektu w testach jednostkowych i inicjalizacji aplikacji.

Sprawdź również konfiguracje identyfikatorów projektów dla poszczególnych platform, które ustawiłeś podczas konfigurowania platform Apple , Androida i projektów internetowych .

Konfiguracja reguł bezpieczeństwa

Emulatory pobiorą konfigurację Reguł Bezpieczeństwa z kluczy konfiguracyjnych database , firestore i storage w 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

Można podać wiele flag w cudzysłowach oddzielonych spacjami, na przykład JAVA_TOOL_OPTIONS="-Xms2g -Xmx4g" . Flagi wpływają tylko na oparte na Javie komponenty emulatorów i nie mają wpływu na inne części Firebase CLI, takie jak interfejs Emulator Suite.

Uruchom emulatory

Możesz uruchomić emulatory tak, aby działały do ​​momentu ręcznego zakończenia lub działały przez określony czas, 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ą 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 oddzieloną przecinkami listę nazw emulatorów, określając co najmniej jedną z następujących wartości: „auth”, „database”, „firestore”, „functions”, „hosting” lub „pubsub”.
--inspect-functions debug_port Opcjonalny. Użyj z emulatorem Cloud Functions, aby włączyć debugowanie punktu przerwania funkcji na określonym porcie (lub domyślnym porcie 9229, jeśli pominięto argument). Należy zauważyć, że po podaniu tej flagi emulator Cloud Functions przełącza się w specjalny tryb wykonania serializowanego, w którym funkcje są wykonywane w jednym procesie, w kolejności sekwencyjnej (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 uwierzytelniania, 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 użyto --import , domyślnie ścieżka eksportu jest taka sama; na przykład: firebase emulators:start --import=./data-path --export-on-exit . Na koniec, jeśli chcesz, przekaż różne ścieżki do katalogów do flag --import i --export-on-exit .
--import= import_directory Opcjonalny. Używaj z emulatorem uwierzytelniania, Cloud Firestore, Realtime Database lub Cloud Storage for Firebase. Importuj dane zapisane przy użyciu opcji startowej --export-on-exit lub polecenia emulators:export do działającej instancji emulatora uwierzytelniania, 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 oddzieloną przecinkami listę nazw emulatorów, określając co najmniej jeden z następujących elementów: „firestore”, „database”, „functions”, „hosting” lub „pubsub”.
--inspect-functions debug_port Opcjonalny. Użyj z emulatorem Cloud Functions, aby włączyć debugowanie punktu przerwania funkcji na określonym porcie (lub domyślnym porcie 9229, jeśli pominięto argument). Należy zauważyć, że po podaniu tej flagi emulator Cloud Functions przełącza się w specjalny tryb wykonania serializowanego, w którym funkcje są wykonywane w jednym procesie, w kolejności sekwencyjnej (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 uwierzytelniania, 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 użyto --import , domyślnie ścieżka eksportu jest taka sama; na przykład: firebase emulators:start --import=./data-path --export-on-exit . Na koniec, jeśli chcesz, przekaż różne ścieżki do katalogów do flag --import i --export-on-exit .
--import= import_directory Opcjonalny. Używaj z emulatorem uwierzytelniania, Cloud Firestore, Realtime Database lub Cloud Storage for Firebase. Importuj dane zapisane przy użyciu opcji startowej --export-on-exit lub polecenia emulators:export do działającej instancji emulatora uwierzytelniania, 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 użytkownika emulatora podczas wykonywania.

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

Eksportuj i importuj dane emulatora

Możesz wyeksportować dane z uwierzytelniania, Cloud Firestore, bazy danych czasu rzeczywistego i Cloud Storage dla emulatorów Firebase, aby użyć ich jako wspólnych bazowych zestawów danych, które można udostępniać. Te zestawy danych można zaimportować za pomocą flagi --import , jak opisano powyżej.

emulatory:eksportuj export_directory

Uwierzytelnianie, Cloud Firestore, Realtime Database 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śli określony katalog istnieje, zostaniesz poproszony o potwierdzenie, że poprzednie dane eksportu powinny zostać nadpisane. 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 opisanych powyżej flag --export-on-exit .

Zintegruj się ze swoim systemem CI

Uruchamianie konteneryzowanych obrazów Emulator Suite

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

Należy 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ąć powtarzających się pobrań.
  • Jeśli nie masz pliku firebase.json w swoim repozytorium, musisz dodać argument wiersza poleceń do polecenia emulators:start lub emulators:exec , aby określić, które emulatory mają zostać uruchomione. Na przykład,
    --only functions,firestore .

Wygeneruj token autoryzacji (tylko emulator hostingu)

Jeśli przepływy pracy ciągłej integracji opierają się na Hostingu Firebase, musisz 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 lokalnym środowisku; nie powinno to być wykonywane z systemu CI. Postępuj zgodnie z instrukcjami, aby się uwierzytelnić. Powinieneś wykonać ten krok 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óre mogą być używane w skryptach kompilacji, po prostu utwórz zmienną środowiskową o nazwie FIREBASE_TOKEN , której wartością będzie ciąg tokena dostępu. Firebase CLI automatycznie pobierze zmienną środowiskową FIREBASE_TOKEN i emulatory uruchomią się poprawnie.

W ostateczności możesz po prostu dołączyć token do skryptu kompilacji, ale upewnij się, że niezaufane strony nie mają dostępu. W przypadku tego zakodowanego na stałe podejścia możesz dodać --token "YOUR_TOKEN_STRING_HERE" do komendy firebase emulators:exec .

Użyj interfejsu API REST Emulator Hub

Wyświetl listę uruchomionych emulatorów

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

curl localhost:4400/emulators

Wynikiem będzie obiekt JSON z listą wszystkich uruchomionych emulatorów i ich konfiguracją 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 funkcji lokalnych i wyzwalaczy rozszerzeń. Na przykład możesz chcieć usunąć wszystkie dane w emulatorze Cloud Firestore bez uruchamiania jakichkolwiek funkcji onDelete , które są uruchomione w emulatorach Cloud Functions lub Extensions.

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

curl -X PUT localhost:4400/functions/disableBackgroundTriggers

Wynikiem będzie obiekt JSON z wyszczególnieniem bieżącego stanu.

{
  "enabled": false
}

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

curl -X PUT localhost:4400/functions/enableBackgroundTriggers

Wynikiem będzie obiekt JSON z wyszczególnieniem bieżącego stanu.

{
  "enabled": true
}

Integracje emulatora SDK

Tabele w tej sekcji wskazują, które emulatory są obsługiwane przez pakiety 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'a Sieć Interfejs użytkownika Firebase
Android
Interfejs użytkownika Firebase
iOS
Interfejs użytkownika Firebase
Sieć
Baza danych czasu rzeczywistego 19.4.0 7.2.0 8.0.0 6.4.0 Przyszły Nie dotyczy
Cloud 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
Przechowywanie 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
Cloud 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
Przechowywanie 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