Local Emulator Suite installieren, konfigurieren und integrieren

Die Firebase Local Emulator Suite kann für verschiedene Prototyping- und Testumgebungen, von einmaligen Prototyping-Sitzungen bis hin zu produktionsreifen Continuous-Integration-Workflows.

Local Emulator Suite installieren

Für die Installation der Emulator Suite benötigen Sie Folgendes:

  • Node.js Version 16.0 oder höher
  • Java JDK Version 11 oder höher

So installieren Sie die Emulator Suite:

  1. Installieren Sie Firebase CLI. Wenn Sie die Firebase CLI noch nicht installiert haben, installieren Sie sie jetzt. Für die Verwendung der Emulator Suite benötigen Sie CLI-Version 8.14.0 oder höher. Sie können Prüfen Sie mit dem folgenden Befehl, welche Version Sie installiert haben:
    firebase --version
  2. Initialisieren Sie das aktuelle Arbeitsverzeichnis, falls noch nicht geschehen als Firebase-Projekt einrichten. Folgen Sie dazu der Anleitung auf dem Bildschirm, zu verwendende Produkte:
    firebase init
  3. Richten Sie die Emulator Suite ein. Dieser Befehl startet einen Konfigurationsassistenten, können Sie relevante Emulatoren auswählen, den entsprechenden Emulator herunterladen und Emulator-Ports festlegen, wenn die Standardwerte nicht geeignet sind.
    firebase init emulators

Sobald ein Emulator installiert ist, werden keine Updateprüfungen durchgeführt und keine zusätzlichen Automatische Downloads erfolgen, bis Sie Ihre Firebase CLI-Version aktualisieren.

Emulator Suite konfigurieren

Sie können optional die Einstellung Netzwerkports und Pfad zur Sicherheit Regeldefinitionen in der Datei firebase.json:

  • Ändern Sie die Emulator-Ports, indem Sie firebase init emulators ausführen oder bearbeiten firebase.json manuell.
  • Ändern Sie den Pfad zu den Definitionen der Sicherheitsregeln, indem Sie firebase.json bearbeiten manuell.

Wenn Sie diese Einstellungen nicht konfigurieren, hören die Emulatoren ihre Standardports und die Cloud Firestore, Realtime Database und Cloud Storage for Firebase Emulatoren mit offener Datensicherheit.

Befehl Beschreibung
init emulators Starten Sie einen Emulator-Initialisierungsassistenten. Identifizieren Sie die zu installierenden Emulatoren und legen Sie optional die Porteinstellungen für den Emulator fest. init emulators ist nicht destruktiv. Wenn du die Standardeinstellungen akzeptierst, wird die aktuelle Emulatorkonfiguration beibehalten.

Portkonfiguration

Jeder Emulator bindet sich an einen anderen Port auf Ihrem Computer mit einem bevorzugten Standardport. Wert.

Emulator Standardport
Authentication 9099
Emulator Suite UI 4000
Cloud Functions 5001
Eventarc 9299
Realtime Database 9000
Cloud Firestore 8080
Cloud Storage for Firebase 9199
Firebase Hosting 5.000
Pub/Sub 8085

Konfiguration der Projekt-ID

Je nachdem, wie Sie Emulatoren aufrufen, können Sie mehrere Instanzen eines Emulator mit unterschiedlichen Firebase-Projekt-IDs oder mehreren Emulatorinstanzen für eine bestimmte Projekt-ID. In solchen Fällen werden Emulatorinstanzen in einer separaten Umgebung ausgeführt.

Es empfiehlt sich, für alle Emulatoraufrufe eine Projekt-ID festzulegen, damit Emulator Suite UI, verschiedene Produktemulatoren und alle laufenden Instanzen eines bestimmten Emulators in allen Fällen richtig kommunizieren können.

Local Emulator Suite gibt Warnungen aus, wenn mehrere Projekt-IDs erkannt werden in festgelegt haben. Sie können dieses Verhalten jedoch außer Kraft setzen, indem Sie den Parameter Schlüssel von singleProjectMode, um false in firebase.json zu erhalten.

Sie können Projekt-ID-Deklarationen in folgenden Bereichen auf Diskrepanzen prüfen:

  • Das Standardprojekt in der Befehlszeile. Standardmäßig wird die Projekt-ID beim Starten aus dem Projekt übernommen, das mit firebase init oder firebase use ausgewählt wurde. So rufen Sie die Liste der Projekte auf und prüfen, welches ausgewählt wurde: firebase projects:list verwenden.
  • Einheitentests für Regeln. Die Projekt-ID wird oft in Aufrufen der Methoden initializeTestEnvironment oder initializeTestApp der Unit-Test-Bibliothek für Regeln angegeben.
  • Das Befehlszeilen-Flag --project. Firebase-Befehlszeile übergeben Das Flag --project überschreibt das Standardprojekt. Sie müssen sicherstellen, dass der Wert des Flags in Unittests und bei der App-Initialisierung mit der Projekt-ID übereinstimmt.

Überprüfen Sie auch die plattformspezifischen Projekt-ID-Konfigurationen, die Sie während des Konfigurieren der Apple-Plattformen Android- und Web-Projekte

Konfiguration der Sicherheitsregeln

Die Emulatoren übernehmen die Konfiguration der Sicherheitsregeln aus database, Konfigurationsschlüssel für firestore und storage in 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"
    }
  }
}

Java-Optionen angeben

Der Realtime Database-Emulator, der Cloud Firestore-Emulator und ein Teil des Cloud Storage for Firebase-Emulators basieren auf Java, das über die Umgebungsvariable JAVA_TOOL_OPTIONS mit JVM-Flags angepasst werden kann.

Wenn beispielsweise Fehler im Zusammenhang mit Java-Heap-Bereichen auftreten, können Sie maximale Java-Heap-Größe auf 4 GB:

export JAVA_TOOL_OPTIONS="-Xmx4g"
firebase emulators:start

Es können mehrere Flags in Anführungszeichen angegeben werden, die durch Leerzeichen getrennt sind. Beispiel: JAVA_TOOL_OPTIONS="-Xms2g -Xmx4g" Die Flags wirken sich nur auf die Java-basierten Komponenten der Emulatoren aus und haben keine Auswirkungen auf andere Teile der Firebase-Befehlszeile, z. B. Emulator Suite UI.

Emulatoren starten

Sie können Emulatoren so starten, dass sie manuell beendet werden oder so lange laufen, wie ein bestimmtes Testscript aktiv ist, und dann automatisch heruntergefahren werden.

Befehl Beschreibung
emulators:start Starten Sie Emulatoren für die in firebase.json konfigurierten Firebase-Produkte. Emulator-Prozesse werden weiter ausgeführt, bis sie explizit beendet werden. Anrufen emulators:start lädt die Emulatoren in ~/.cache/firebase/emulators/ herunter, wenn sind sie noch nicht installiert.
Flag Beschreibung
--only Optional. Begrenzen Sie, welche Emulatoren gestartet werden. Geben Sie eine durch Kommas getrennte Liste von Emulatornamen an und geben Sie einen oder „auth“, „database“, „firestore“, „functions“, „hosting“ oder „pubsub“.
--inspect-functions debug_port Optional. Verwendung mit dem Cloud Functions-Emulator, um das Haltepunkt-Debugging von Funktionen an der angegebenen Port (oder der Standardport 9229, wenn das Argument weggelassen wird). Wenn dieses Flag angegeben wird, wechselt der Cloud Functions-Emulator zu einem speziellen serialisierten Ausführungsmodus, in dem Funktionen in einem einzelnen Prozess in sequenzieller (FIFO-)Reihenfolge ausgeführt werden. Das vereinfacht die Funktionsfehlerbehebung, das Verhalten unterscheidet sich jedoch von der parallelen Ausführung von Funktionen in der Cloud.
--export-on-exit= Optional. Wird mit Authentication, Cloud Firestore, Realtime Database oder Cloud Storage for Firebase-Emulator. Weisen Sie den Emulator an, Daten in einen Verzeichnis beim Herunterfahren, wie für emulators:export beschrieben . Das Exportverzeichnis kann mit diesem Flag angegeben werden: firebase emulators:start --export-on-exit=./saved-data Wenn --import verwendet wird, ist der Exportpfad standardmäßig derselbe: Beispiel: firebase emulators:start --import=./data-path --export-on-exit. Geben Sie abschließend bei Bedarf unterschiedliche Verzeichnispfade an die Flags --import und --export-on-exit weiter.
--import=import_directory Optional. Wird mit Authentication, Cloud Firestore, Realtime Database oder Cloud Storage for Firebase-Emulator. Daten importieren, die mit der --export-on-exit-Startoption oder dem Befehl emulators:export gespeichert wurden, in eine laufende Authentication-, Cloud Firestore-, Realtime Database- oder Cloud Storage for Firebase-Emulatorinstanz. Alle Daten, die sich derzeit im Emulatorspeicher befinden, werden überschrieben.
emulators:exec scriptpath Führen Sie das Skript unter scriptpath aus, nachdem Sie die Emulatoren für die Firebase-Produkte gestartet haben konfiguriert in firebase.json. Emulator-Prozesse werden automatisch beendet, wenn die die Ausführung des Skripts beendet.
Flag Beschreibung
--only Optional. Limit welche Emulatoren gestartet werden. Geben Sie eine durch Kommas getrennte Liste von Emulatornamen an und geben Sie einen oder „Firestore“, „Datenbank“, „Funktionen“, „Hosting“ oder „PubSub“.
--inspect-functions debug_port Optional. Verwendung mit dem Cloud Functions-Emulator, um das Haltepunkt-Debugging von Funktionen am angegebener Port (oder der Standardport 9229, wenn das Argument weggelassen wird). Beachten Sie, dass in diesem Fall gesetzt ist, wechselt der Cloud Functions-Emulator zu einem speziellen serialisierten Ausführungsmodus, in dem Funktionen in einem einzigen Prozess ausgeführt werden, in sequenzielle Reihenfolge (FIFO) Das vereinfacht die Fehlerbehebung, unterscheidet sich von der parallelen Multiprozessausführung von Funktionen in der Cloud.
--export-on-exit= Optional. Wird mit Authentication, Cloud Firestore, Realtime Database oder Cloud Storage for Firebase-Emulator. Weisen Sie den Emulator an, Daten in einen Verzeichnis beim Herunterfahren, wie für emulators:export beschrieben . Das Exportverzeichnis kann mit diesem Flag angegeben werden: firebase emulators:start --export-on-exit=./saved-data Wenn --import verwendet wird, ist der Exportpfad standardmäßig derselbe: Beispiel: firebase emulators:start --import=./data-path --export-on-exit. Schließlich: Bei Bedarf können Sie verschiedene Verzeichnispfade an --import übergeben und --export-on-exit-Flags.
--import=import_directory Optional. Verwendung mit dem Authentication-, Cloud Firestore-, Realtime Database- oder Cloud Storage for Firebase-Emulator. Daten importieren, die mit der --export-on-exit-Startoption oder dem emulators:export-Befehl gespeichert wurden, in eine laufende Authentication-, Cloud Firestore-, Realtime Database- oder Cloud Storage for Firebase-Emulatorinstanz. Alle Daten, die sich derzeit im Arbeitsspeicher des Emulators befinden werden überschrieben.
--ui Optional. Führen Sie während der Ausführung die Emulator-UI aus.

Die Methode firebase emulators:exec eignet sich besser für Continuous-Integration-Workflows.

Emulator-Daten exportieren und importieren

Sie können Daten aus den Authentication-, Cloud Firestore-, Realtime Database- und Cloud Storage for Firebase-Emulatoren exportieren, um sie als freigegebene, gemeinsame Baseline-Daten zu verwenden. Diese Datasets können mit dem Flag --import importiert werden: beschrieben.

emulators:export export_directory

Authentication-, Cloud Firestore-, Realtime Database- oder Cloud Storage for Firebase-Emulator. Daten aus einer laufenden Cloud Firestore, Realtime Database oder Cloud Storage for Firebase exportieren Emulatorinstanz. Die angegebene export_directory wird dann erstellt, wenn dies der Fall ist noch nicht vorhanden sind. Wenn das angegebene Verzeichnis vorhanden ist, werden Sie aufgefordert, zu bestätigen, dass die vorherigen Exportdaten überschrieben werden sollen. Sie können diese Aufforderung überspringen, indem Sie die --force-Flag. Das Exportverzeichnis enthält eine Datenmanifestdatei, firebase-export-metadata.json

Sie können die Emulatoren anweisen, Daten beim Herunterfahren automatisch zu exportieren. Verwenden Sie dazu die --export-on-exit-Flags.

In Ihr CI-System einbinden

Container Emulator Suite-Images ausführen

Die Installation und Konfiguration der Emulator Suite mit Containern in einer typischen CI-Umgebung ist unkompliziert.

Es sind einige Probleme zu beachten:

  • JAR-Dateien werden unter ~/.cache/firebase/emulators/ installiert und im Cache gespeichert.

    • Sie sollten diesen Pfad Ihrer CI-Cache-Konfiguration hinzufügen, um wiederholte Downloads.
  • Wenn Sie keine firebase.json-Datei in Ihrem Repository haben, müssen Sie ein Befehlszeilenargument für den Befehl emulators:start oder emulators:exec um anzugeben, welche Emulatoren gestartet werden sollen. Beispiel:
    --only functions,firestore

Authentifizierungstoken generieren (nur Hosting-Emulator)

Wenn Ihre Continuous-Integration-Workflows auf Firebase Hosting basieren, Sie müssen sich mit einem Token anmelden, um firebase emulators:exec auszuführen. Die andere Emulatoren erfordern keine Anmeldung.

Führen Sie firebase login:ci in Ihrer lokalen Umgebung aus, um ein Token zu generieren. sollte dies nicht über ein CI-System erfolgen. Folge der Anleitung zur Authentifizierung. Sie sollten diesen Schritt nur einmal pro Projekt ausführen, da das Token für alle Builds gültig ist. Das Token sollte wie ein Passwort behandelt werden. dass sie geheim gehalten werden.

Wenn Sie in Ihrer CI-Umgebung Umgebungsvariablen angeben können, die die in den Build-Skripts verwendet werden, erstellen Sie einfach eine Umgebungsvariable FIREBASE_TOKEN, wobei der Wert der Zugriffstokenstring ist. Firebase CLI automatisch die Umgebungsvariable FIREBASE_TOKEN und den Emulatoren ordnungsgemäß starten.

Als letzte Möglichkeit können Sie das Token einfach in Ihr Build-Script aufnehmen. Achten Sie jedoch darauf, dass nicht vertrauenswürdige Dritte keinen Zugriff darauf haben. Für diese hartcodierte können Sie --token "YOUR_TOKEN_STRING_HERE" zum firebase emulators:exec-Befehl.

Emulator Hub REST API verwenden

Laufende Emulatoren auflisten

Um die derzeit ausgeführten Emulatoren aufzulisten, senden Sie eine GET-Anfrage an /emulators des Emulator Hub.

curl localhost:4400/emulators

Das Ergebnis ist ein JSON-Objekt, das alle laufenden Emulatoren und ihre Host-/Portkonfiguration. Beispiel:

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

Trigger für Hintergrundfunktionen aktivieren/deaktivieren

Manchmal müssen Sie die lokale Funktion Erweiterungsauslöser. Beispielsweise möchten Sie vielleicht alle Daten in der Cloud Firestore-Emulators, ohne onDelete-Funktionen auszulösen, die im Emulator Cloud Functions oder Extensions ausgeführt werden.

Senden Sie eine PUT-Anfrage an den /functions/disableBackgroundTriggers-Endpunkt des Emulator Hubs.

curl -X PUT localhost:4400/functions/disableBackgroundTriggers

Das Ergebnis ist ein JSON-Objekt, das den aktuellen Status enthält.

{
  "enabled": false
}

Senden Sie eine PUT, um lokale Funktionstrigger zu aktivieren, nachdem sie deaktiviert wurden Anfrage an den /functions/enableBackgroundTriggers-Endpunkt des Emulators Hub

curl -X PUT localhost:4400/functions/enableBackgroundTriggers

Das Ergebnis ist ein JSON-Objekt, das den aktuellen Status enthält.

{
  "enabled": true
}

Emulator SDK-Integrationen

In den Tabellen in diesem Abschnitt wird angegeben, welche Emulatoren von Client- und Admin-SDKs unterstützt werden. Zukünftig bedeutet, dass die Unterstützung des Emulators geplant ist, aber noch nicht abgeschlossen ist. verfügbar.

Verfügbarkeit des Client SDK

Android Apple-Plattformen Web Firebase-UI
Android
Firebase-UI
iOS
Firebase-UI
Web
Realtime Database 19.4.0 7.2.0 8.0.0 6.4.0 Zukünftig
Cloud Firestore 21.6.0 7.2.0 8.0.0 6.4.0 Zukünftig
Authentication 20.0.0 7.0.0 8.0.0 7.0.0 Zukünftig 4.7.2
Cloud Storage for Firebase 20.0.0 8.0.0 8.4.0 7.0.0 11.0.0
Cloud Functions 19.1.0 7.2.0 8.0.0
Hosting
Extensions

Verfügbarkeit des Admin SDK

Knoten Java Python Go
Realtime Database 8.6.0 6.10.0 2.18.0 Zukünftig
Cloud Firestore 8.0.0 6.10.0 3.0.0 1.0.0
Authentication 9.3.0 7.2.0 5.0.0 4.2.0
Cloud Storage for Firebase 9.8.0 Zukünftig Zukünftig Zukünftig
Cloud Functions
Hosting
Extensions