Installa, configura e integra Local Emulator Suite

La suite Firebase Local Emulator può essere installata e configurata per diversi ambienti di prototipazione e test, da sessioni di prototipazione una tantum a flussi di lavoro di integrazione continua su scala di produzione.

Installa la suite dell'emulatore locale

Prima di installare Emulator Suite avrai bisogno di:

  • Node.js versione 16.0 o successiva.
  • Java JDK versione 11 o successiva.

Per installare l'Emulatore Suite:

  1. Installa la CLI Firebase . Se non hai già installato la CLI Firebase, installala ora . Avrai bisogno della versione CLI 8.14.0 o successiva per utilizzare Emulator Suite. Puoi verificare quale versione hai installato utilizzando il seguente comando:
    firebase --version
  2. Se non lo hai già fatto, inizializza la directory di lavoro corrente come progetto Firebase, seguendo le istruzioni visualizzate per specificare quali prodotti utilizzare:
    firebase init
  3. Configura la suite dell'emulatore. Questo comando avvia una procedura guidata di configurazione che consente di selezionare gli emulatori di interesse, scaricare i file binari dell'emulatore corrispondenti e impostare le porte dell'emulatore se le impostazioni predefinite non sono appropriate.
    firebase init emulators

Una volta installato un emulatore, non verranno eseguiti controlli di aggiornamento e non verranno eseguiti ulteriori download automatici finché non aggiornerai la versione della CLI di Firebase.

Configura Emulator Suite

Facoltativamente, puoi configurare le porte di rete degli emulatori e il percorso per le definizioni delle regole di sicurezza nel file firebase.json :

  • Modificare le porte dell'emulatore eseguendo firebase init emulators o modificando manualmente firebase.json .
  • Modificare il percorso delle definizioni delle regole di sicurezza modificando manualmente firebase.json .

Se non configuri queste impostazioni, gli emulatori resteranno in ascolto sulle rispettive porte predefinite e gli emulatori Cloud Firestore, Realtime Database e Cloud Storage for Firebase verranno eseguiti con la sicurezza dei dati aperti.

Comando Descrizione
emulatori init Avvia una procedura guidata di inizializzazione dell'emulatore. Identificare gli emulatori da installare e facoltativamente specificare le impostazioni della porta dell'emulatore. init emulators non sono distruttivi; accettare le impostazioni predefinite manterrà la configurazione corrente dell'emulatore.

Configurazione della porta

Ogni emulatore si collega a una porta diversa sul tuo computer con un valore predefinito preferito.

Emulatore Porta predefinita
Autenticazione 9099
Interfaccia utente della suite di emulazione 4000
Funzioni del cloud 5001
Eventarc 9299
Banca dati in tempo reale 9000
Cloud Fire Store 8080
Archiviazione nel cloud per Firebase 9199
Hosting Firebase 5000
Pub/Sub 8085

Configurazione dell'ID progetto

A seconda di come richiami gli emulatori, puoi eseguire più istanze di un emulatore utilizzando diversi ID di progetto Firebase o più istanze dell'emulatore per un determinato ID di progetto. In questi casi, le istanze dell'emulatore vengono eseguite in un ambiente separato.

In genere è una buona pratica impostare un ID progetto per tutte le chiamate dell'emulatore, in modo che l'interfaccia utente di Emulator Suite, i diversi emulatori del prodotto e tutte le istanze in esecuzione di un particolare emulatore possano comunicare correttamente in tutti i casi.

Local Emulator Suite emette avvisi quando rileva più ID di progetto nell'ambiente, sebbene sia possibile ignorare questo comportamento impostando la chiave singleProjectMode su false nel file firebase.json .

Puoi verificare la presenza di discrepanze nelle dichiarazioni dell'ID progetto in:

  • Il progetto predefinito nella riga di comando. Per impostazione predefinita, l'ID progetto verrà acquisito all'avvio dal progetto selezionato con firebase init o firebase use . Per visualizzare l'elenco dei progetti (e vedere quale è selezionato) utilizzare firebase projects:list .
  • Test unitari delle regole. L'ID progetto viene spesso specificato nelle chiamate ai metodi della libreria Rules Unit Testing initializeTestEnvironment o initializeTestApp .
  • La riga di comando --project flag. Il passaggio del flag --project della CLI Firebase sovrascrive il progetto predefinito. Dovrai assicurarti che il valore del flag corrisponda all'ID progetto negli unit test e nell'inizializzazione dell'app.

Controlla anche le configurazioni dell'ID progetto specifico della piattaforma che hai impostato durante la configurazione delle piattaforme Apple , Android e dei progetti web .

Configurazione delle regole di sicurezza

Gli emulatori prenderanno la configurazione delle regole di sicurezza dalle chiavi di configurazione del database , firestore e 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"
    }
  }
}

Specifica delle opzioni Java

L'emulatore Realtime Database, l'emulatore Cloud Firestore e parte dell'emulatore Cloud Storage for Firebase sono basati su Java, che può essere personalizzato con flag JVM tramite la variabile di ambiente JAVA_TOOL_OPTIONS .

Ad esempio, se si verificano errori relativi allo spazio heap Java, è possibile aumentare la dimensione massima dell'heap Java a 4 GB:

export JAVA_TOOL_OPTIONS="-Xmx4g"
firebase emulators:start

È possibile specificare più flag tra virgolette separate da spazi, come JAVA_TOOL_OPTIONS="-Xms2g -Xmx4g" . I flag influiscono solo sui componenti basati su Java degli emulatori e non hanno alcun effetto su altre parti della CLI Firebase, come l'interfaccia utente di Emulator Suite.

Avvia gli emulatori

È possibile avviare gli emulatori affinché vengano eseguiti finché non vengono terminati manualmente oppure per la durata di uno script di test designato e poi arrestati automaticamente.

Comando Descrizione
emulatori: start Avvia gli emulatori per i prodotti Firebase configurati in firebase.json . I processi dell'emulatore continueranno a essere eseguiti fino all'arresto esplicito. Chiamando emulators:start scaricherà gli emulatori in ~/.cache/firebase/emulators/ se non sono già installati.
Bandiera Descrizione
--only Opzionale. Limita quali emulatori avviare. Fornisci un elenco separato da virgole di nomi di emulatori, specificando uno o più tra "auth", "database", "firestore", "functions", "hosting" o "pubsub".
--inspect-functions debug_port Opzionale. Utilizzalo con l'emulatore Cloud Functions per abilitare il debug del punto di interruzione delle funzioni sulla porta specificata (o sulla porta predefinita 9229 se l'argomento viene omesso). Tieni presente che quando viene fornito questo flag, l'emulatore Cloud Functions passa a una speciale modalità di esecuzione serializzata in cui le funzioni vengono eseguite in un unico processo, in ordine sequenziale (FIFO); ciò semplifica il debug delle funzioni, sebbene il comportamento differisca dall'esecuzione parallela e multiprocesso delle funzioni nel cloud.
--export-on-exit= Opzionale. Utilizzare con l'emulatore Authentication, Cloud Firestore, Realtime Database o Cloud Storage for Firebase. Indicare agli emulatori di esportare i dati in una directory quando si verifica l'arresto, come descritto per il comando emulators:export . La directory di esportazione può essere specificata con questo flag: firebase emulators:start --export-on-exit=./saved-data . Se viene utilizzato --import , il percorso di esportazione predefinito è lo stesso; ad esempio: firebase emulators:start --import=./data-path --export-on-exit . Infine, se lo si desidera, passare percorsi di directory diversi ai flag --import e --export-on-exit .
--import= import_directory Opzionale. Utilizzare con l'emulatore Authentication, Cloud Firestore, Realtime Database o Cloud Storage for Firebase. Importa i dati salvati utilizzando l'opzione di avvio --export-on-exit o il comando emulators:export in un'istanza dell'emulatore Authentication, Cloud Firestore, Realtime Database o Cloud Storage for Firebase in esecuzione. Tutti i dati attualmente presenti nella memoria dell'emulatore verranno sovrascritti.
emulatori: exec scriptpath Esegui lo script in scriptpath dopo aver avviato gli emulatori per i prodotti Firebase configurati in firebase.json . I processi dell'emulatore si interromperanno automaticamente al termine dell'esecuzione dello script.
Bandiera Descrizione
--only Opzionale. Limita quali emulatori avviare. Fornisci un elenco separato da virgole di nomi di emulatori, specificando uno o più tra "firestore", "database", "funzioni", "hosting" o "pubsub".
--inspect-functions debug_port Opzionale. Utilizzalo con l'emulatore Cloud Functions per abilitare il debug del punto di interruzione delle funzioni sulla porta specificata (o sulla porta predefinita 9229 se l'argomento viene omesso). Tieni presente che quando viene fornito questo flag, l'emulatore Cloud Functions passa a una speciale modalità di esecuzione serializzata in cui le funzioni vengono eseguite in un unico processo, in ordine sequenziale (FIFO); ciò semplifica il debug delle funzioni, sebbene il comportamento differisca dall'esecuzione parallela e multiprocesso delle funzioni nel cloud.
--export-on-exit= Opzionale. Utilizzare con l'emulatore Authentication, Cloud Firestore, Realtime Database o Cloud Storage for Firebase. Indicare agli emulatori di esportare i dati in una directory quando si verifica l'arresto, come descritto per il comando emulators:export . La directory di esportazione può essere specificata con questo flag: firebase emulators:start --export-on-exit=./saved-data . Se viene utilizzato --import , il percorso di esportazione predefinito è lo stesso; ad esempio: firebase emulators:start --import=./data-path --export-on-exit . Infine, se lo si desidera, passare percorsi di directory diversi ai flag --import e --export-on-exit .
--import= import_directory Opzionale. Utilizzare con l'emulatore Authentication, Cloud Firestore, Realtime Database o Cloud Storage for Firebase. Importa i dati salvati utilizzando l'opzione di avvio --export-on-exit o il comando emulators:export in un'istanza dell'emulatore Authentication, Cloud Firestore, Realtime Database o Cloud Storage for Firebase in esecuzione. Tutti i dati attualmente presenti nella memoria dell'emulatore verranno sovrascritti.
--ui Opzionale. Esegui l'interfaccia utente dell'emulatore durante l'esecuzione.

Gli firebase emulators:exec è generalmente più appropriato per i flussi di lavoro di integrazione continua.

Esporta e importa i dati dell'emulatore

Puoi esportare i dati dagli emulatori Authentication, Cloud Firestore, Realtime Database e Cloud Storage for Firebase da utilizzare come set di dati di base comune e condivisibile. Questi set di dati possono essere importati utilizzando il flag --import , come descritto sopra.

emulatori:export export_directory

Autenticazione, Cloud Firestore, Realtime Database o Cloud Storage per l'emulatore Firebase . Esporta i dati da un'istanza dell'emulatore Cloud Firestore, Realtime Database o Cloud Storage for Firebase in esecuzione. La export_directory specificata verrà creata se non esiste già. Se la directory specificata esiste, ti verrà richiesto di confermare che i dati di esportazione precedenti devono essere sovrascritti. Puoi saltare questo messaggio utilizzando il flag --force . La directory di esportazione contiene un file manifest dei dati, firebase-export-metadata.json .

Puoi indicare agli emulatori di esportare automaticamente i dati quando si spengono utilizzando i flag --export-on-exit descritti sopra.

Integrazione con il tuo sistema CI

Esecuzione di immagini Emulator Suite containerizzate

L'installazione e la configurazione di Emulator Suite con contenitori in una tipica configurazione CI sono semplici.

Ci sono alcuni problemi da notare:

  • I file JAR vengono installati e memorizzati nella cache in ~/.cache/firebase/emulators/ .

    • Potresti voler aggiungere questo percorso alla configurazione della cache CI per evitare download ripetuti.
  • Se non hai un file firebase.json nel tuo repository, devi aggiungere un argomento della riga di comando al comando emulators:start o emulators:exec per specificare quali emulatori devono essere avviati. Per esempio,
    --only functions,firestore .

Genera un token di autenticazione (solo emulatore di hosting)

Se i tuoi flussi di lavoro di integrazione continua si basano su Firebase Hosting, dovrai accedere utilizzando un token per eseguire firebase emulators:exec . Gli altri emulatori non richiedono il login.

Per generare un token, esegui firebase login:ci nel tuo ambiente locale; questa operazione non deve essere eseguita da un sistema CI. Segui le istruzioni per autenticarti. Dovresti eseguire questo passaggio solo una volta per progetto, poiché il token sarà valido per tutte le build. Il token dovrebbe essere trattato come una password; assicurati che sia tenuto segreto.

Se l'ambiente CI ti consente di specificare variabili di ambiente che possono essere utilizzate negli script di build, crea semplicemente una variabile di ambiente denominata FIREBASE_TOKEN , con il valore che è la stringa del token di accesso. La CLI di Firebase rileverà automaticamente la variabile di ambiente FIREBASE_TOKEN e gli emulatori si avvieranno correttamente.

Come ultima risorsa, puoi semplicemente includere il token nello script di build, ma assicurati che le parti non attendibili non abbiano accesso. Per questo approccio hardcoded, puoi aggiungere --token "YOUR_TOKEN_STRING_HERE" al comando firebase emulators:exec .

Utilizza l'API REST dell'emulatore Hub

Elenca gli emulatori in esecuzione

Per elencare gli emulatori attualmente in esecuzione, inviare una richiesta GET all'endpoint /emulators dell'hub emulatore.

curl localhost:4400/emulators

Il risultato sarà un oggetto JSON che elenca tutti gli emulatori in esecuzione e la relativa configurazione host/porta, ad esempio:

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

Abilita/disabilita i trigger delle funzioni di sfondo

In alcune situazioni sarà necessario disabilitare temporaneamente le funzioni locali e i trigger di estensione. Ad esempio, potresti voler eliminare tutti i dati nell'emulatore Cloud Firestore senza attivare alcuna funzione onDelete in esecuzione negli emulatori Cloud Functions o Extensions.

Per disabilitare temporaneamente i trigger di funzioni locali, inviare una richiesta PUT all'endpoint /functions/disableBackgroundTriggers dell'hub emulatore.

curl -X PUT localhost:4400/functions/disableBackgroundTriggers

Il risultato sarà un oggetto JSON che descrive in dettaglio lo stato corrente.

{
  "enabled": false
}

Per abilitare i trigger di funzioni locali dopo che sono stati disabilitati, inviare una richiesta PUT all'endpoint /functions/enableBackgroundTriggers dell'hub emulatore.

curl -X PUT localhost:4400/functions/enableBackgroundTriggers

Il risultato sarà un oggetto JSON che descrive in dettaglio lo stato corrente.

{
  "enabled": true
}

Integrazioni SDK dell'emulatore

Le tabelle in questa sezione indicano quali emulatori sono supportati dal client e dagli SDK di amministrazione. Futuro significa che il supporto dell'emulatore è pianificato ma non ancora disponibile.

Disponibilità dell'SDK client

Androide Piattaforme Apple ragnatela Interfaccia utente di Firebase
Androide
Interfaccia utente di Firebase
iOS
Interfaccia utente di Firebase
ragnatela
Banca dati in tempo reale 19.4.0 7.2.0 8.0.0 6.4.0 Futuro N / A
Cloud Fire Store 21.6.0 7.2.0 8.0.0 6.4.0 Futuro N / A
Autenticazione 20.0.0 7.0.0 8.0.0 7.0.0 Futuro 4.7.2
Archiviazione nel cloud per Firebase 20.0.0 8.0.0 8.4.0 7.0.0 11.0.0 N / A
Funzioni del cloud 19.1.0 7.2.0 8.0.0 N / A N / A N / A
Ospitando N / A N / A N / A N / A N / A N / A
Estensioni N / A N / A N / A N / A N / A N / A

Disponibilità dell'SDK di amministrazione

Nodo Giava Pitone Andare
Banca dati in tempo reale 8.6.0 6.10.0 2.18.0 Futuro
Cloud Fire Store 8.0.0 6.10.0 3.0.0 1.0.0
Autenticazione 9.3.0 7.2.0 5.0.0 4.2.0
Archiviazione nel cloud per Firebase 9.8.0 Futuro Futuro Futuro
Funzioni del cloud N / A N / A N / A N / A
Ospitando N / A N / A N / A N / A
Estensioni N / A N / A N / A N / A