Installa, configura e integra Local Emulator Suite

La Firebase Local Emulator Suite 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 di emulatori locali

Prima di installare l'Emulatore Suite avrai bisogno di:

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

Per installare l'Emulatore Suite:

  1. Installa l'interfaccia a riga di comando di Firebase . Se non hai già installato Firebase CLI, installalo ora . Avrai bisogno della versione CLI 8.14.0 o successiva per utilizzare Emulator Suite. Puoi controllare quale versione hai installato usando il seguente comando:
    firebase --version
  2. Se non l'hai già fatto, inizializza la directory di lavoro corrente come progetto Firebase, seguendo le istruzioni sullo schermo per specificare quali prodotti utilizzare:
    firebase init
  3. Configura la suite di emulatori. 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 vengono eseguiti controlli di aggiornamento e non verranno effettuati ulteriori download automatici finché non aggiorni la versione della CLI di Firebase.

Configura la suite di emulatori

È possibile configurare facoltativamente le porte di rete degli emulatori e il percorso delle definizioni delle regole di sicurezza nel file firebase.json :

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

Se non configuri queste impostazioni, gli emulatori ascolteranno sulle loro porte predefinite e gli emulatori Cloud Firestore, Realtime Database e Cloud Storage funzioneranno con la sicurezza dei dati aperti.

Comando Descrizione
emulatori init Avvia una procedura guidata di inizializzazione dell'emulatore. Identifica gli emulatori da installare e, facoltativamente, specifica le impostazioni della porta dell'emulatore. gli init emulators non sono distruttivi; l'accettazione delle impostazioni predefinite conserverà la configurazione corrente dell'emulatore.

Configurazione della porta

Ogni emulatore si collega a una porta diversa sulla tua macchina con un valore predefinito preferito.

Emulatore Porta predefinita
Autenticazione 9099
Interfaccia utente della suite di emulatori 4000
Funzioni cloud 5001
Database in tempo reale 9000
Cloud Firestore 8080
Archiviazione su cloud 9199
Hosting Firebase 5000
Pub/Sub 8085

Configurazione delle regole di sicurezza

Gli emulatori prenderanno la configurazione delle regole di sicurezza dal database , firestore e le chiavi di configurazione firebase.json storage

{
  // 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": {
    "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"
    }
  }
}

Specificare le opzioni Java

L'emulatore Realtime Database, l'emulatore Cloud Firestore e parte dell'emulatore Cloud Storage 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 interessano solo i componenti basati su Java degli emulatori e non hanno effetto su altre parti dell'interfaccia a riga di comando di Firebase, come l'interfaccia utente di Emulator Suite.

Avvia emulatori

È possibile avviare gli emulatori in modo che vengano eseguiti fino alla terminazione manuale o per l'esecuzione per la durata di uno script di test designato, quindi si spengono automaticamente.

Comando Descrizione
emulatori: inizio 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 iniziano. Fornisci un elenco di nomi di emulatori separati da virgole, specificando uno o più tra 'auth', 'database', 'firestore', 'functions', 'hosting' o 'pubsub'.
--inspect-functions debug_port Opzionale. Utilizzare con l'emulatore Cloud Functions per abilitare il debug del punto di interruzione delle funzioni sulla porta specificata (o la porta predefinita 9229 se l'argomento omesso). Si noti che quando viene fornito questo flag, l'emulatore di Cloud Functions passa a una speciale modalità di esecuzione serializzata in cui le funzioni vengono eseguite in un unico processo, in ordine sequenziale (FIFO); questo 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 di autenticazione, Cloud Firestore, database in tempo reale o Cloud Storage. 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 per impostazione predefinita è lo stesso; ad esempio: firebase emulators:start --import=./data-path --export-on-exit . Infine, se lo desideri, passa diversi percorsi di directory ai --import e --export-on-exit .
--import= import_directory Opzionale. Utilizzare con l'emulatore di autenticazione, Cloud Firestore, database in tempo reale o Cloud Storage. Importa i dati salvati utilizzando l'opzione di avvio --export-on-exit o il comando emulators:export in un'istanza dell'emulatore di autenticazione, Cloud Firestore, Realtime Database o Cloud Storage in esecuzione. Tutti i dati attualmente nella memoria dell'emulatore verranno sovrascritti.
emulatori: scriptpath exec 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 iniziano. Fornisci un elenco di nomi di emulatori separati da virgole, specificando uno o più tra "firestore", "database", "funzioni", "hosting" o "pubsub".
--inspect-functions debug_port Opzionale. Utilizzare con l'emulatore Cloud Functions per abilitare il debug del punto di interruzione delle funzioni sulla porta specificata (o la porta predefinita 9229 se l'argomento omesso). Si noti che quando viene fornito questo flag, l'emulatore di Cloud Functions passa a una speciale modalità di esecuzione serializzata in cui le funzioni vengono eseguite in un unico processo, in ordine sequenziale (FIFO); questo 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 di autenticazione, Cloud Firestore, database in tempo reale o Cloud Storage. 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 per impostazione predefinita è lo stesso; ad esempio: firebase emulators:start --import=./data-path --export-on-exit . Infine, se lo desideri, passa diversi percorsi di directory ai --import e --export-on-exit .
--import= import_directory Opzionale. Utilizzare con l'emulatore di autenticazione, Cloud Firestore, database in tempo reale o Cloud Storage. Importa i dati salvati utilizzando l'opzione di avvio --export-on-exit o il comando emulators:export in un'istanza dell'emulatore di autenticazione, Cloud Firestore, Realtime Database o Cloud Storage in esecuzione. Tutti i dati attualmente nella memoria dell'emulatore verranno sovrascritti.
--ui Opzionale. Esegui l'interfaccia utente dell'emulatore durante l'esecuzione.

Il 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 di autenticazione, Cloud Firestore, Realtime Database e Cloud Storage da utilizzare come set di dati di base condivisibile e comune. Questi set di dati possono essere importati usando il flag --import , come descritto sopra.

emulatori: esporta export_directory

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

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

Integra con il tuo sistema CI

Esecuzione di immagini containerizzate di Emulator Suite

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

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; questo non dovrebbe essere eseguito da un sistema CI. Segui le istruzioni per autenticarti. Dovresti eseguire questo passaggio solo una volta per progetto, poiché il token sarà valido tra le build. Il token dovrebbe essere trattato come una password; assicurati che sia tenuto segreto.

Se il tuo ambiente CI ti consente di specificare variabili di ambiente che possono essere utilizzate negli script di compilazione, crea semplicemente una variabile di ambiente chiamata 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 nel tuo 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 firebase emulators:exec .

Utilizzare l'API REST dell'hub emulatore

Elenca gli emulatori in esecuzione

Per elencare gli emulatori attualmente in esecuzione, invia 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 loro 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 in background

In alcune situazioni sarà necessario disabilitare temporaneamente la funzione locale 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 funzione 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 funzione 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 dell'SDK dell'emulatore

Le tabelle in questa sezione indicano quali emulatori sono supportati da client e Admin SDK. 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
Database in tempo reale 19.4.0 7.2.0 8.0.0 6.4.0 Futuro N / A
Cloud Firestore 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 Futuro
Archiviazione su cloud 20.0.0 8.0.0 8.4.0 N / A N / A N / A
Funzioni 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
Database in tempo reale 8.6.0 6.10.0 2.18.0 Futuro
Cloud Firestore 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 su cloud 9.8.0 Futuro Futuro Futuro
Funzioni 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