Local Emulator Suite installieren, konfigurieren und einbinden

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

Bevor Sie die Emulator Suite installieren, 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 CLI-Version 8.14.0 oder höher, um die Emulator Suite zu verwenden. Mit dem folgenden Befehl können Sie prüfen, welche Version Sie installiert haben:

   firebase --version

2. Falls noch nicht geschehen, initialisieren Sie das aktuelle Arbeitsverzeichnis als Firebase-Projekt. Folgen Sie dazu den Anweisungen 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 die gewünschten Emulatoren auswählen, die entsprechenden Binärdateien herunterladen und die Emulatorports festlegen können, wenn die Standardeinstellungen nicht geeignet sind.

   firebase init emulators

Nach der Installation eines Emulators werden keine Updateprüfungen durchgeführt und keine zusätzlichen automatischen Downloads ausgeführt, bis Sie Ihre Firebase CLI-Version aktualisieren.

Emulator Suite konfigurieren

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

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

Wenn Sie diese Einstellungen nicht konfigurieren, warten die Emulatoren an ihren Standardports und die Emulatoren Cloud Firestore, Realtime Database und Cloud Storage for Firebase werden mit offener Datensicherheit ausgeführt.

Portkonfiguration

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

Projekt-ID-Konfiguration

Je nachdem, wie Sie Emulatoren aufrufen, können Sie mehrere Instanzen eines Emulators mit unterschiedlichen 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.

Im Allgemeinen empfiehlt es sich, für alle Emulatoraufrufe eine Projekt-ID festzulegen, damit die Emulator Suite UI, verschiedene Produktemulatoren und alle laufenden Instanzen eines bestimmten Emulators in allen Fällen korrekt 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 Ihrer firebase.json auf false setzen.

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

• Das Standardprojekt in der Befehlszeile. Standardmäßig wird die Projekt-ID beim Start 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 Projekt ausgewählt ist.
• Unittests für Regeln. Die Projekt-ID wird häufig in Aufrufen der Methoden initializeTestEnvironment oder initializeTestApp der Rules Unit Testing-Bibliothek angegeben.
• Das Befehlszeilen-Flag --project. Wenn Sie das --project-Flag der Firebase-Befehlszeile übergeben, wird das Standardprojekt überschrieben. Achten Sie darauf, dass der Wert des Flags mit der Projekt-ID in Unit-Tests und der App-Initialisierung übereinstimmt.

Prüfen Sie auch die plattformspezifischen Projekt-ID-Konfigurationen, die Sie bei der Konfiguration 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 mit JVM-Flags über die Umgebungsvariable JAVA_TOOL_OPTIONS 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 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 des Firebase CLI, z. B. Emulator Suite UI.

Emulatoren starten

Sie können Emulatoren so starten, dass sie ausgeführt werden, bis sie manuell beendet werden, oder dass sie für die Dauer eines bestimmten Testskripts ausgeführt und dann automatisch heruntergefahren werden.

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

Emulatordaten exportieren und importieren

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

In CI-System einbinden

Containerisierte Emulator Suite-Images ausführen

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

Es gibt einige Probleme, die Sie beachten sollten:

• 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. Für die 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, um sich zu authentifizieren. 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. Achten Sie darauf, dass es geheim bleibt.

Wenn Sie in Ihrer CI-Umgebung Umgebungsvariablen angeben können, die in den Build-Skripts verwendet werden können, erstellen Sie einfach eine Umgebungsvariable mit dem Namen FIREBASE_TOKEN, wobei der Wert der Zugriffstoken-String ist. Die Firebase CLI übernimmt automatisch die Umgebungsvariable FIREBASE_TOKEN und die Emulatoren werden ordnungsgemäß gestartet.

Als letzte Möglichkeit können Sie das Token einfach in Ihr Build-Skript einfügen. Achten Sie aber darauf, dass nicht vertrauenswürdige Parteien keinen Zugriff darauf haben. Für diesen hartcodierten Ansatz können Sie dem Befehl firebase emulators:exec das Flag --token "YOUR_TOKEN_STRING_HERE" hinzufügen.

Emulator Hub REST API verwenden

Ausgeführte Emulatoren auflisten

Wenn Sie die aktuell ausgeführten Emulatoren auflisten möchten, senden Sie eine GET-Anfrage an den /emulators-Endpunkt des Emulator Hubs.

curl localhost:4400/emulators

Das Ergebnis ist ein JSON-Objekt, in dem alle laufenden Emulatoren und ihre Host-/Portkonfiguration aufgeführt sind, 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 Situationen müssen Sie lokale Funktions- und Erweiterungstrigger vorübergehend deaktivieren. Beispielsweise möchten Sie möglicherweise alle Daten im Cloud Firestore-Emulator löschen, ohne dass onDelete-Funktionen ausgelöst werden, die in den Cloud Functions- oder Extensions-Emulatoren ausgeführt werden.

Wenn Sie lokale Funktions-Trigger 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, das den aktuellen Status beschreibt.

{
  "enabled": false
}

Wenn Sie lokale Funktionstrigger 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, das den aktuellen Status beschreibt.

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