Firebase is back at Google I/O on May 10! Register now

Installieren, konfigurieren und integrieren Sie die Local Emulator Suite

Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

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.

Installieren Sie die Local Emulator Suite

Vor der Installation der Emulator Suite benötigen Sie:

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

So installieren Sie die Emulator-Suite:

  1. Installieren Sie die Firebase-CLI . Wenn Sie die Firebase-Befehlszeilenschnittstelle noch nicht installiert haben, installieren Sie sie jetzt . Sie benötigen CLI-Version 8.14.0 oder höher, um die Emulator Suite zu verwenden. Welche Version Sie installiert haben, können Sie mit folgendem Befehl prüfen:
    firebase --version
  2. Falls Sie dies noch nicht getan haben, initialisieren Sie das aktuelle Arbeitsverzeichnis als Firebase-Projekt und befolgen Sie die Anweisungen auf dem Bildschirm, um anzugeben, welche Produkte verwendet werden sollen:
    firebase init
  3. Richten Sie die Emulator-Suite ein. Dieser Befehl startet einen Konfigurationsassistenten, mit dem Sie die gewünschten Emulatoren auswählen, die entsprechenden Emulator-Binärdateien herunterladen und Emulator-Ports festlegen können, wenn die Standardwerte nicht geeignet sind.
    firebase init emulators

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

Konfigurieren Sie die Emulator-Suite

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 firebase init emulators oder firebase.json manuell bearbeiten.
  • Ändern Sie den Pfad zu den Sicherheitsregeldefinitionen, indem Sie firebase.json manuell bearbeiten.

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

Befehl Beschreibung
init-Emulatoren Starten Sie einen Emulator-Initialisierungsassistenten. Identifizieren Sie die zu installierenden Emulatoren und geben Sie optional die Porteinstellungen für die Emulatoren an. init emulators sind nicht destruktiv; Durch das Akzeptieren der Standardeinstellungen wird die aktuelle Emulatorkonfiguration beibehalten.

Portkonfiguration

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

Emulator Standardport
Authentifizierung 9099
Benutzeroberfläche der Emulator Suite 4000
Cloud-Funktionen 5001
Eventarc 9299
Echtzeit-Datenbank 9000
Cloud-Firestore 8080
Cloud-Speicher für Firebase 9199
Firebase-Hosting 5000
Pub/Sub 8085

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.

Es empfiehlt sich im Allgemeinen, eine Projekt-ID für alle Emulatoraufrufe festzulegen, damit die Benutzeroberfläche der Emulator Suite, verschiedene Produktemulatoren und alle ausgeführten Instanzen eines bestimmten Emulators in allen Fällen korrekt kommunizieren können.

Die Local Emulator Suite gibt Warnungen aus, wenn sie mehrere Projekt-IDs in der Umgebung erkennt, obwohl Sie dieses Verhalten überschreiben können, indem Sie den Schlüssel singleProjectMode in Ihrer firebase.json auf false setzen.

Sie können die Projekt-ID-Erklärung(en) auf Diskrepanzen überprüfen in:

  • Das Standardprojekt in der Befehlszeile. Standardmäßig wird die Projekt-ID beim Start aus dem mit firebase init oder firebase use ausgewählten Projekt übernommen. Um die Liste der Projekte anzuzeigen (und zu sehen, welches ausgewählt ist), verwenden Sie firebase projects:list .
  • Unit-Tests für Regeln. Die Projekt-ID wird häufig in Aufrufen der Methoden initializeTestEnvironment oder initializeTestApp der Rules Unit Testing-Bibliothek angegeben.
  • Das Befehlszeilen-- --project -Flag. Durch das Übergeben des Firebase-CLI --project wird das Standardprojekt überschrieben. Sie müssen sicherstellen, dass der Wert des Flags bei Komponententests und App-Initialisierung mit der Projekt-ID übereinstimmt.

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

Konfiguration der Sicherheitsregeln

Die Emulatoren übernehmen die Konfiguration der Sicherheitsregeln aus den 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"
    }
  }
}

Festlegen von Java-Optionen

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 Java-Heap-Speicherplatz 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 durch Leerzeichen getrennten Anführungszeichen angegeben werden, wie 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-Befehlszeilenschnittstelle, wie z. B. die Benutzeroberfläche der Emulator Suite.

Emulatoren starten

Sie können Emulatoren so starten, dass sie bis zur manuellen Beendigung ausgeführt werden, oder dass sie für die Dauer eines festgelegten Testskripts ausgeführt und dann automatisch heruntergefahren werden.

Befehl Beschreibung
Emulatoren: starten Starten Sie Emulatoren für die in firebase.json konfigurierten firebase.json -Produkte. Emulatorprozesse werden weiter ausgeführt, bis sie explizit gestoppt werden. Beim Aufrufen von emulators emulators:start werden die Emulatoren nach ~/.cache/firebase/emulators/ heruntergeladen, falls sie noch nicht installiert sind.
Flagge Beschreibung
--only Optional. Beschränken Sie, welche Emulatoren starten. Geben Sie eine durch Kommas getrennte Liste von Emulatornamen an, die einen oder mehrere von „auth“, „database“, „firestore“, „functions“, „hosting“ oder „pubsub“ angeben.
--inspect-functions debug_port Optional. Mit dem Cloud Functions-Emulator verwenden, um das Breakpoint-Debugging von Funktionen am angegebenen Port (oder dem Standardport 9229, wenn das Argument weggelassen wird) zu aktivieren. Beachten Sie, dass der Cloud Functions-Emulator bei Angabe dieses Flags in einen speziellen serialisierten Ausführungsmodus wechselt, in dem Funktionen in einem einzigen Prozess in sequentieller Reihenfolge (FIFO) ausgeführt werden. Dies vereinfacht das Debuggen von Funktionen, obwohl sich das Verhalten von der parallelen Ausführung von Funktionen in der Cloud mit mehreren Prozessen unterscheidet.
--export-on-exit= Optional. Verwendung mit dem Authentifizierungs-, Cloud Firestore-, Realtime Database- oder Cloud Storage for Firebase-Emulator. Weisen Sie den/die Emulator(en) an, Daten in ein Verzeichnis zu exportieren, wenn das Herunterfahren erfolgt, 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 gleich; Beispiel: firebase emulators:start --import=./data-path --export-on-exit . Übergeben Sie schließlich, falls gewünscht, unterschiedliche Verzeichnispfade an die --import und --export-on-exit .
--import= import_directory Optional. Verwendung mit dem Authentifizierungs-, Cloud Firestore-, Realtime Database- oder Cloud Storage for Firebase-Emulator. Importieren Sie Daten, die mit der --export-on-exit oder dem Befehl emulators emulators:export gespeichert wurden, in eine laufende Authentifizierungs-, Cloud Firestore-, Realtime Database- oder Cloud Storage for Firebase-Emulatorinstanz. Alle Daten, die sich derzeit im Emulatorspeicher befinden, werden überschrieben.
Emulatoren:exec scriptpath Führen Sie das Skript unter scriptpath aus, nachdem Sie Emulatoren für die in firebase.json konfigurierten firebase.json -Produkte gestartet haben. Emulatorprozesse werden automatisch beendet, wenn das Skript ausgeführt wurde.
Flagge Beschreibung
--only Optional. Beschränken Sie, welche Emulatoren starten. Geben Sie eine durch Kommas getrennte Liste von Emulatornamen an, die einen oder mehrere von „firestore“, „database“, „functions“, „hosting“ oder „pubsub“ angeben.
--inspect-functions debug_port Optional. Mit dem Cloud Functions-Emulator verwenden, um das Breakpoint-Debugging von Funktionen am angegebenen Port (oder dem Standardport 9229, wenn das Argument weggelassen wird) zu aktivieren. Beachten Sie, dass der Cloud Functions-Emulator bei Angabe dieses Flags in einen speziellen serialisierten Ausführungsmodus wechselt, in dem Funktionen in einem einzigen Prozess in sequentieller Reihenfolge (FIFO) ausgeführt werden. Dies vereinfacht das Debuggen von Funktionen, obwohl sich das Verhalten von der parallelen Ausführung von Funktionen in der Cloud mit mehreren Prozessen unterscheidet.
--export-on-exit= Optional. Verwendung mit dem Authentifizierungs-, Cloud Firestore-, Realtime Database- oder Cloud Storage for Firebase-Emulator. Weisen Sie den/die Emulator(en) an, Daten in ein Verzeichnis zu exportieren, wenn das Herunterfahren erfolgt, 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 gleich; Beispiel: firebase emulators:start --import=./data-path --export-on-exit . Übergeben Sie schließlich, falls gewünscht, unterschiedliche Verzeichnispfade an die --import und --export-on-exit .
--import= import_directory Optional. Verwendung mit dem Authentifizierungs-, Cloud Firestore-, Realtime Database- oder Cloud Storage for Firebase-Emulator. Importieren Sie Daten, die mit der --export-on-exit oder dem Befehl emulators emulators:export gespeichert wurden, in eine laufende Authentifizierungs-, 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-UI während der Ausführung aus.

Die firebase emulators:exec Methode ist im Allgemeinen besser für kontinuierliche Integrationsworkflows 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 gemeinsam nutzbaren, gemeinsamen Basisdatensatz zu verwenden. Diese Datensätze können wie oben beschrieben mit dem Flag --import importiert werden.

Emulatoren: export export_directory

Authentifizierung, Cloud Firestore, Realtime Database oder Cloud Storage für Firebase-Emulator . Exportieren Sie Daten aus einer laufenden Cloud Firestore-, Realtime Database- oder Cloud Storage for Firebase-Emulatorinstanz. Das angegebene export_directory wird erstellt, falls es noch nicht existiert. Wenn das angegebene Verzeichnis existiert, werden Sie aufgefordert, zu bestätigen, dass die vorherigen Exportdaten überschrieben werden sollen. Sie können diese Eingabeaufforderung mit dem Flag --force überspringen. Das Exportverzeichnis enthält eine Datenmanifestdatei, firebase-export-metadata.json .

Sie können die Emulatoren anweisen, Daten automatisch zu exportieren, wenn sie heruntergefahren werden, indem Sie die oben beschriebenen Flags --export-on-exit verwenden.

Integration in Ihr CI-System

Containerisierte Emulator Suite-Images ausführen

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

Es gibt ein paar Probleme zu beachten:

  • JAR-Dateien werden unter ~/.cache/firebase/emulators/ installiert und zwischengespeichert.

    • Möglicherweise möchten Sie diesen Pfad zu 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. Zum Beispiel,
    --only functions,firestore .

Generieren Sie ein Authentifizierungstoken (nur Hosting-Emulator)

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

Um ein Token zu generieren, führen Sie firebase login:ci in Ihrer lokalen Umgebung aus; Dies sollte nicht von einem CI-System aus durchgeführt werden. Befolgen Sie die Anweisungen zur Authentifizierung. Sie sollten diesen Schritt nur einmal pro Projekt ausführen müssen, da das Token für alle Builds gültig ist. Das Token sollte wie ein Passwort behandelt werden; stellen Sie sicher, dass es geheim gehalten wird.

Wenn Ihre CI-Umgebung die Angabe von Umgebungsvariablen zulässt, die in den Build-Skripts verwendet werden können, erstellen Sie einfach eine Umgebungsvariable namens FIREBASE_TOKEN , deren Wert die Zeichenfolge des Zugriffstokens ist. Die Firebase-CLI übernimmt automatisch die Umgebungsvariable FIREBASE_TOKEN und die Emulatoren werden ordnungsgemäß gestartet.

Als letzten Ausweg können Sie das Token einfach in Ihr Build-Skript aufnehmen, aber sicherstellen, dass nicht vertrauenswürdige Parteien keinen Zugriff haben. Für diesen fest codierten Ansatz können Sie --token "YOUR_TOKEN_STRING_HERE" zum Befehl firebase emulators firebase emulators:exec hinzufügen.

Verwenden Sie die Emulator Hub-REST-API

Laufende Emulatoren auflisten

Um die derzeit ausgeführten Emulatoren aufzulisten, 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-/Port-Konfiguration auflistet, zum Beispiel:

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

Hintergrundfunktionsauslöser aktivieren/deaktivieren

In einigen Situationen müssen Sie lokale Funktions- und Erweiterungsauslöser vorübergehend deaktivieren. Beispielsweise möchten Sie möglicherweise alle Daten im Cloud Firestore-Emulator löschen, ohne onDelete Funktionen auszulösen, die in den Cloud Functions- oder Extensions-Emulatoren ausgeführt werden.

Um lokale Funktionsauslöser vorübergehend zu deaktivieren, senden Sie eine PUT -Anforderung 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 angibt.

{
  "enabled": false
}

Um lokale Funktionsauslöser zu aktivieren, nachdem sie deaktiviert wurden, senden Sie eine PUT -Anforderung 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 angibt.

{
  "enabled": true
}

Emulator-SDK-Integrationen

Die Tabellen in diesem Abschnitt geben an, welche Emulatoren von Client- und Admin-SDKs unterstützt werden. Zukunft bedeutet Emulatorunterstützung ist geplant, aber noch nicht verfügbar.

Verfügbarkeit des Client-SDK

Android Apple-Plattformen Netz Firebase-Benutzeroberfläche
Android
Firebase-Benutzeroberfläche
iOS
Firebase-Benutzeroberfläche
Netz
Echtzeit-Datenbank 19.4.0 7.2.0 8.0.0 6.4.0 Zukunft N / A
Cloud-Firestore 21.6.0 7.2.0 8.0.0 6.4.0 Zukunft N / A
Authentifizierung 20.0.0 7.0.0 8.0.0 7.0.0 Zukunft 4.7.2
Cloud-Speicher für Firebase 20.0.0 8.0.0 8.4.0 7.0.0 11.0.0 N / A
Cloud-Funktionen 19.1.0 7.2.0 8.0.0 N / A N / A N / A
Gastgeber N / A N / A N / A N / A N / A N / A
Erweiterungen N / A N / A N / A N / A N / A N / A

Verfügbarkeit des Admin-SDK

Knoten Java Python gehen
Echtzeit-Datenbank 8.6.0 6.10.0 2.18.0 Zukunft
Cloud-Firestore 8.0.0 6.10.0 3.0.0 1.0.0
Authentifizierung 9.3.0 7.2.0 5.0.0 4.2.0
Cloud-Speicher für Firebase 9.8.0 Zukunft Zukunft Zukunft
Cloud-Funktionen N / A N / A N / A N / A
Gastgeber N / A N / A N / A N / A
Erweiterungen N / A N / A N / A N / A