Local Emulator Suite installieren, konfigurieren und integrieren

Die Firebase Local Emulator Suite kann für verschiedene Prototyp- und Testumgebungen installiert und konfiguriert werden, von einmaligen Prototyping-Sitzungen bis hin zu Continuous-Integration-Workflows im Produktionsmaßstab.

Local Emulator Suite installieren

Vor der 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. Sie benötigen die Befehlszeilenversion 8.14.0 oder höher, um die Emulator Suite verwenden zu können. Mit dem folgenden Befehl können Sie prüfen, welche Version installiert ist:
    firebase --version
  2. Falls noch nicht geschehen, initialisieren Sie das aktuelle Arbeitsverzeichnis als Firebase-Projekt. Folgen Sie der Anleitung auf dem Bildschirm, um anzugeben, welche Produkte verwendet werden sollen:
    firebase init
  3. Richten Sie die Emulator Suite ein. Mit diesem Befehl wird ein Konfigurationsassistent gestartet, mit dem Sie gewünschte Emulatoren auswählen, die entsprechenden Emulator-Binärdateien herunterladen und Emulatorports festlegen können, wenn die Standardeinstellungen nicht geeignet sind.
    firebase init emulators

Nach der Installation eines Emulators werden keine Updates mehr geprüft und es werden keine weiteren automatischen Downloads durchgeführt, bis Sie die Version der Firebase CLI aktualisieren.

Emulator Suite konfigurieren

Optional können Sie die Netzwerkports der Emulatoren und den Pfad zu den Sicherheitsregeln in der Datei firebase.json konfigurieren:

  • Sie können die Emulatorports ändern, indem Sie firebase init emulators ausführen oder firebase.json manuell bearbeiten.
  • Ändern Sie den Pfad zu den Definitionen für Sicherheitsregeln, indem Sie firebase.json manuell bearbeiten.

Wenn Sie diese Einstellungen nicht konfigurieren, hören die Emulatoren auf ihren Standardports und die Cloud Firestore-, Realtime Database- und Cloud Storage for Firebase-Emulatoren werden mit offener Datensicherheit ausgeführt.

Befehl Beschreibung
init emulators Starten Sie einen Emulator-Initialisierungsassistenten. Geben Sie die zu installierenden Emulatoren an und legen Sie optional die Emulator-Porteinstellungen fest. init emulators ist nicht zerstörerisch. Wenn Sie die Standardeinstellungen akzeptieren, bleibt die aktuelle Emulatorkonfiguration erhalten.

Portkonfiguration

Jeder Emulator wird mit einem bevorzugten Standardwert an einen anderen Port auf Ihrem Computer gebunden.

Emulator Standardport
Authentication 9099
App Hosting 5002
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 Emulators mit verschiedenen Firebase-Projekt-IDs oder mehrere Emulatorinstanzen für eine bestimmte Projekt-ID ausführen. 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 in der Umgebung erkannt werden. Sie können dieses Verhalten jedoch überschreiben, indem Sie den Schlüssel singleProjectMode in firebase.json auf false setzen.

Sie können die Deklarationen der Projekt-IDs in folgenden Bereichen auf Abweichungen 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. Mit firebase projects:list können Sie die Liste der Projekte aufrufen und sehen, welches ausgewählt ist.
  • Regeln für Unit-Tests Die Projekt-ID wird oft in Aufrufen der Methoden initializeTestEnvironment oder initializeTestApp der Unit-Test-Bibliothek für Regeln angegeben.
  • Das Flag --project in der Befehlszeile Wenn Sie das Flag --project an die Firebase CLI übergeben, wird das Standardprojekt überschrieben. Der Wert des Flags muss mit der Projekt-ID in den Unit-Tests und bei der App-Initialisierung übereinstimmen.

Prüfen Sie auch die plattformspezifischen Projekt-ID-Konfigurationen, die Sie beim Konfigurieren Ihrer Apple-Plattformen, Android- und Webprojekte festgelegt haben.

Konfiguration von Sicherheitsregeln

Die Emulatoren übernehmen die Konfiguration der Sicherheitsregeln aus den Konfigurationsschlüsseln database, 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 dem Java-Heap-Speicher auftreten, können Sie die maximale Java-Heap-Größe auf 4 GB erhöhen:

export JAVA_TOOL_OPTIONS="-Xmx4g"
firebase emulators:start

Mehrere Flags können in Anführungszeichen und durch Leerzeichen getrennt angegeben werden, z. B. 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. Emulatorprozesse werden so lange ausgeführt, bis sie explizit beendet werden. Wenn Sie emulators:start aufrufen, werden die Emulatoren in ~/.cache/firebase/emulators/ heruntergeladen, falls sie noch nicht installiert sind.
Flag Beschreibung
--only Optional. Begrenzen Sie, welche Emulatoren gestartet werden. Geben Sie eine durch Kommas getrennte Liste von Emulatornamen an, wobei mindestens einer der folgenden Werte angegeben werden muss: „auth“, „database“, „firestore“, „functions“, „hosting“ oder „pubsub“.
--inspect-functions debug_port Optional. Wird mit dem Cloud Functions-Emulator verwendet, um das Debugging von Funktionen mit Haltepunkten am angegebenen Port zu aktivieren (oder am 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 Funktionsprüfung, das Verhalten unterscheidet sich jedoch von der parallelen Ausführung von Funktionen in der Cloud.
--export-on-exit= Optional. Verwendung mit dem Authentication-, Cloud Firestore-, Realtime Database- oder Cloud Storage for Firebase-Emulator. Weisen Sie die Emulatoren an, beim Herunterfahren Daten in ein Verzeichnis zu exportieren, wie für den Befehl 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, z. B. 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. 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 Emulatorspeicher befinden, werden überschrieben.
emulators:exec scriptpath Führen Sie das Script unter scriptpath aus, nachdem Sie Emulatoren für die in firebase.json konfigurierten Firebase-Produkte gestartet haben. Emulatorprozesse werden automatisch beendet, wenn das Script beendet wurde.
Flag Beschreibung
--only Optional. Begrenzen Sie, welche Emulatoren gestartet werden. Geben Sie eine durch Kommas getrennte Liste von Emulatornamen an, wobei mindestens einer der folgenden Werte angegeben werden muss: „firestore“, „database“, „functions“, „hosting“ oder „pubsub“.
--inspect-functions debug_port Optional. Wird mit dem Cloud Functions-Emulator verwendet, um das Debugging von Funktionen mit Haltepunkten am angegebenen Port zu aktivieren (oder am 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. Verwendung mit dem Authentication-, Cloud Firestore-, Realtime Database- oder Cloud Storage for Firebase-Emulator. Weisen Sie die Emulatoren an, beim Herunterfahren Daten in ein Verzeichnis zu exportieren, wie für den Befehl 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, z. B. 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. 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 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.
--ui Optional. Führen Sie die Emulator-Benutzeroberfläche während der Ausführung aus.

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

Emulatordaten 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 Datensätze können wie oben beschrieben mit dem Flag --import importiert werden.

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-Emulatorinstanz exportieren Die angegebene export_directory wird erstellt, falls sie noch nicht vorhanden ist. Wenn das angegebene Verzeichnis vorhanden ist, werden Sie aufgefordert, zu bestätigen, dass die vorherigen Exportdaten überschrieben werden sollen. Sie können diese Aufforderung mit dem Flag --force überspringen. Das Exportverzeichnis enthält eine Datenmanifestdatei, firebase-export-metadata.json.

Sie können die Emulatoren mithilfe der oben beschriebenen --export-on-exit-Flags anweisen, Daten automatisch beim Herunterfahren zu exportieren.

In CI-System einbinden

Containerisierte Emulator Suite-Images ausführen

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

Beachten Sie dabei Folgendes:

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

    • Sie können diesen Pfad Ihrer CI-Cache-Konfiguration hinzufügen, um wiederholte Downloads zu vermeiden.
  • Wenn Sie keine firebase.json-Datei in Ihrem Repository haben, müssen Sie dem Befehl emulators:start oder emulators:exec ein Befehlszeilenargument hinzufügen, 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, müssen Sie sich mit einem Token anmelden, um firebase emulators:exec auszuführen. Bei den anderen Emulatoren ist keine Anmeldung erforderlich.

Führen Sie firebase login:ci in Ihrer lokalen Umgebung aus, um ein Token zu generieren. Dies sollte nicht über ein CI-System erfolgen. Folgen Sie der Anleitung zur Authentifizierung. Sie müssen 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 und muss geheim gehalten werden.

Wenn Sie in Ihrer CI-Umgebung Umgebungsvariablen angeben können, die in den Build-Scripts verwendet werden können, erstellen Sie einfach eine Umgebungsvariable namens FIREBASE_TOKEN mit dem Wert „access_token“. Die Firebase CLI übernimmt dann automatisch die Umgebungsvariable FIREBASE_TOKEN und die Emulatoren werden ordnungsgemäß gestartet.

Als letzte Möglichkeit können Sie das Token einfach in Ihr Build-Script einfügen. Achten Sie jedoch darauf, dass nicht vertrauenswürdige Dritte keinen Zugriff darauf haben. Bei diesem hartcodierten Ansatz können Sie dem Befehl firebase emulators:exec --token "YOUR_TOKEN_STRING_HERE" hinzufügen.

Emulator Hub REST API verwenden

Liste der laufenden Emulatoren

Wenn Sie eine Liste der derzeit ausgeführten Emulatoren aufrufen möchten, senden Sie eine GET-Anfrage an den /emulators-Endpunkt des Emulator-Hubs.

curl localhost:4400/emulators

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

{
  "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

In einigen Fällen müssen Sie lokale Funktionen und Trigger für Erweiterungen vorübergehend deaktivieren. Beispielsweise möchten Sie möglicherweise alle Daten im Cloud Firestore-Emulator löschen, ohne onDelete-Funktionen auszulösen, die im Cloud Functions- oder Extensions-Emulator ausgeführt werden.

Wenn Sie Trigger für lokale Funktionen vorübergehend deaktivieren möchten, 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 mit dem aktuellen Status.

{
  "enabled": false
}

Wenn Sie lokale Funktionstrigger wieder aktivieren möchten, nachdem sie deaktiviert wurden, senden Sie eine PUT-Anfrage an den /functions/enableBackgroundTriggers-Endpunkt des Emulator-Hubs.

curl -X PUT localhost:4400/functions/enableBackgroundTriggers

Das Ergebnis ist ein JSON-Objekt mit dem aktuellen Status.

{
  "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 Emulatorunterstützung geplant, aber noch nicht verfügbar ist.

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