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 der Sicherheitsregeln. Bearbeiten Sie dazu firebase.json manuell.

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.

Portkonfiguration

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

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 Aufrufe des Emulators 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.
• 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 Flag --project in der Befehlszeile Wenn Sie das Flag --project an die Firebase CLI übergeben, wird das Standardprojekt überschrieben. Achten Sie darauf, dass der Wert des Flags mit der Projekt-ID in den Unit-Tests und bei der App-Initialisierung übereinstimmt.

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-Bereich 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 bis zur manuellen Beendigung oder für die Dauer eines bestimmten Testscripts laufen und dann automatisch heruntergefahren werden.

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

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.

In 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.

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-Skripts verwendet werden können, erstellen Sie einfach eine Umgebungsvariable namens FIREBASE_TOKEN, wobei der Wert der Zugriffstokenstring ist. 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 aufnehmen. 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 ausgeführten Emulatoren und ihre Host-/Portkonfiguration auflistet, zum 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

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.

Senden Sie eine PUT-Anfrage an den /functions/disableBackgroundTriggers-Endpunkt des Emulator-Hubs, um lokale Funktionstrigger vorübergehend zu deaktivieren.

curl -X PUT localhost:4400/functions/disableBackgroundTriggers

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

{
  "enabled": false
}

Wenn Sie lokale Funktions-Trigger nach dem Deaktivieren aktivieren möchten, 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

Verfügbarkeit des Admin SDK