Testare le app web localmente con l'emulatore Firebase App Hosting

Puoi eseguire test locali della tua app prima del App Hosting deployment utilizzando l'App Hosting emulatore, che fa parte della Firebase Local Emulator Suite.

Prima di utilizzare l'emulatore App Hosting, assicurati di comprendere il flusso di lavoro generale di Firebase Local Emulator Suite e di installare e configurare Local Emulator Suite e di esaminare i relativi comandi CLI.

Questo argomento presuppone che tu abbia già familiarità con App Hosting. Se necessario, consulta l'App Hostingintroduzione e altro materiale per aiutarti a comprendere il funzionamentoApp Hosting.

Cosa posso fare con l'emulatore App Hosting?

L'emulatore App Hosting ti consente di testare e perfezionare le applicazioni web localmente. In questo modo puoi semplificare il processo di sviluppo e migliorare la qualità delle app web create utilizzando Firebase e sottoposte a deployment su App Hosting.

L'emulatore App Hosting:

  1. Ti consente di eseguire l'app web localmente, con le variabili di ambiente e i secret definiti nei file di configurazione apphosting.yaml.
  2. Può sostituire le variabili di ambiente e i secret da utilizzare nell'emulatore con il file apphosting.emulator.yaml.
  3. Può essere utilizzato insieme ad altri emulatori Firebase. Se utilizzi Firestore, Auth o qualsiasi altro emulatore, Local Emulator Suite garantisce che questi emulatori vengano avviati prima dell'emulatore App Hosting.

Configurare l'emulatore

Per iniziare, installa e inizializza il Local Emulator Suite come descritto in Installare, configurare e integrare Local Emulator Suite. Oltre a tutti gli altri emulatori Firebase che vuoi configurare, assicurati di selezionare App Hosting Emulator. La CLI ti chiede alcuni valori dell'emulatore App Hosting, tra cui:

  • La directory principale dell'app relativa al progetto. Questo è importante se utilizzi monorepo con App Hosting.
  • Se vuoi sostituire i valori per lo sviluppo locale.
  • Se vuoi concedere ai colleghi l'accesso ai secret per lo sviluppo locale.
firebase init emulators
=== Emulators Setup
? Which Firebase emulators do you want to set up? Press Space to select emulators, then Enter to confirm your choices. (Press
<space> to select, <a> to toggle all, <i> to invert selection, and <enter> to proceed)
❯◯ App Hosting Emulator
 ◯ Firestore Emulator
 ◯ Database Emulator
 ◯ Hosting Emulator
 ◯ Pub/Sub Emulator
 ◯ Storage Emulator
 ◯ Eventarc Emulator
(Move up and down to reveal more choices)

? Specify your app's root directory relative to your project (./)

? The App Hosting emulator uses a file called apphosting.emulator.yaml to
override values in apphosting.yaml for local testing. This codebase does not
have one, would you like to create it? (Y/n)

? Which environment variables would you like to override? (Press <space> to
select, <a> to toggle all, <i> to invert selection, and <enter> to proceed)
❯◯ MEMCACHE_ADDR
 ◯ API_KEY

? What new value would you like for plaintext MEMCACHE_ADDR?

? What would you like to name the secret reference for API_KEY? (test-api-key)

? What new value would you like for secret TESTKEY [input is hidden]? [input is hidden]

? Your config has secret values. Please provide a comma-separated list of users
or groups who should have access to secrets for local development:

✔  Successfully set IAM bindings on secret test-api-key.

Tutti i valori che fornisci in questo flusso di configurazione vengono utilizzati per aggiornare la configurazione dell' App Hosting emulatore in firebase.json. Puoi anche configurare l'emulatore di App Hosting aggiornando direttamente firebase.json. Lo schema per l'emulatore di App Hosting è il seguente:

{
  ...
  "emulators": {
    "apphosting": {
      "startCommand": <command> [optional]
      "rootDirectory": <path> [optional]
      }
    }
  }
  • startCommand viene generato e impostato automaticamente quando l'emulatore viene inizializzato. Se non viene fornito, l'emulatore rileva ed esegue il comando di sviluppo del gestore di pacchetti.
  • rootDirectory viene utilizzato per supportare le configurazioni dei progetti monorepo. Se l'app web si trova in una sottodirectory, devi fornire il percorso della directory relativa alla root (la posizione di firebase.json).

Gestire l'emulazione

L'inizializzazione dell'emulatore crea un file apphosting.emulator.yaml nella directory principale dell'app. Questo file di configurazione ha lo stesso schema del apphosting.yaml file utilizzato in produzione, ma è destinato esclusivamente allo sviluppo locale. Per impostazione predefinita, l'emulatore legge la configurazione dal file apphosting.yaml, ma se è presente un file apphosting.emulator.yaml, le configurazioni in questo file hanno la priorità.

Il file apphosting.emulator.yaml è progettato per essere sicuro da eseguire il commit e condividere con i colleghi. Per evitare di eseguire accidentalmente il commit di dati sensibili nei repository di origine, qualsiasi variabile di ambiente che sia un secret in apphosting.yaml deve essere anche un secret in apphosting.emulator.yaml. Se un secret non deve essere modificato tra la produzione e lo sviluppo locale (ad es. una chiave API Gemini), non è necessario aggiungerlo a apphosting.emulator.yaml; invece concedi al tuo team l'accesso al secret.

Se la tua applicazione utilizza molti secret (ad esempio, chiavi API per tre servizi diversi, con valori diversi per ogni ambiente di produzione, staging e sviluppo locale), potresti superare il livello senza costi di Cloud Secret Manager e pagare 0,06 $al mese per ogni secret aggiuntivo. Se preferisci gestire la configurazione locale al di fuori del controllo del codice sorgente per evitare questa tariffa, puoi utilizzare il file apphosting.local.yaml legacy. A differenza di apphosting.emulator.yaml, questo file può fornire valori di testo non crittografato per le variabili di ambiente che sono valori secret in apphosting.yaml.

Concedere l'accesso ai secret a utenti o gruppi

I secret archiviati in apphosting.emulator.yaml vengono letti all'avvio dell'emulatore. Ciò significa che il tuo team di sviluppo deve avere accesso al secret. Puoi utilizzare il comando apphosting:secrets:grantaccess per concedere l'accesso a un secret a un utente o a un gruppo tramite email.

firebase apphosting:secrets:grantaccess test-api-key --emails my-team@my-company.com

Se applicabile, valuta la possibilità di utilizzare chiavi solo di test in apphosting.emulator.yaml che non hanno accesso ai dati di produzione, non possono avere effetti collaterali globali (invio di email, addebito su carte di credito) e/o hanno quote inferiori. In questo modo, il codice non esaminato ha meno conseguenze nel mondo reale.

Valuta la possibilità di utilizzare Google Gruppi per gestire l'accesso ai secret anziché concedere l'accesso ai singoli utenti. In questo modo, l'onboarding di nuovi membri del team di sviluppo sarà più semplice, perché l'aggiunta al gruppo concederà loro l'accesso a tutti i secret di cui hanno bisogno. Potresti già avere un gruppo appropriato in cui gli sviluppatori comunicano tra loro. Il controllo dell'accesso tramite Google Gruppi contribuisce anche a garantire che gli sviluppatori che lasciano il team perdano l'accesso a tutti i secret quando vengono rimossi dal gruppo di indirizzi email. Tuttavia, se il secret ha accesso ai dati di produzione o a effetti collaterali nel mondo reale, potrebbe comunque essere appropriato ruotare la chiave e assegnarle un nuovo valore con firebase apphosting:secrets:set.

Eseguire l'emulatore

firebase emulators:start

Verranno avviati tutti gli emulatori definiti nel file firebase.json, incluso l'emulatore App Hosting.

Configurare il comando start per le app Angular

Se il comando start dell'emulatore va in timeout, è probabile che il server di sviluppo Angular stia pubblicando l'app su una porta diversa da quella prevista dall' App Hosting emulatore. Puoi risolvere questo problema aggiungendo una configurazione aggiuntiva in firebase.json:

  • Imposta emulators.apphosting.startCommand su ng serve.
  • Per utilizzare una porta non predefinita, impostala con emulators.apphosting.port (anziché aggiungere il flag --port a ng serve in emulators.apphosting.startCommand).

Ad esempio:

"emulators": {
    "apphosting": {
      "port": 5002,
      "rootDirectory": "./test-app",
      "startCommand": "ng serve"
    },
    "ui": {
      "enabled": true
    },
    ...
  }