Questa guida mostra come eseguire la migrazione delle estensioni dall'ambiente Firebase Extensions ritirato a un kit di funzioni che puoi installare ed eseguire il deployment nel tuo Cloud Functions per la base di codice Firebase (2ª gen.).
Firebase Extensions gestiva tutti gli aspetti della creazione, dell'aggiornamento e della rimozione delle estensioni. I kit di funzioni raggruppano le funzionalità delle estensioni come tipiche Cloud Functions for Firebase di 2ª gen. Poiché i kit di funzioni sono Cloud Functions standard, puoi crearli, aggiornarli, eliminarli e risolvere i problemi utilizzando l'interfaccia a riga di comando Firebase all'interno del progetto Firebase. Questa guida ti prepara a gestire le tue funzioni ora e ad adottare gli aggiornamenti non appena diventano disponibili.
In questa guida, l'estensione Stream Cloud Firestore to BigQuery (firestore-bigquery-export) viene utilizzata come esempio che mostra i
comandi e l'output dei comandi per ogni passaggio della migrazione.
Determinare il percorso di migrazione
Firebase incoraggia tutti i publisher di Firebase Extensions a creare sostituzioni per le loro estensioni come kit di funzioni pubblicati su npm. Puoi controllare se è disponibile una sostituzione del kit di funzioni per le tue estensioni in diversi modi:
- Vai alla pagina Estensioni della console Firebase per il tuo progetto. Ogni estensione installata indica se è disponibile una sostituzione del kit di funzionalità.
Esegui
firebase ext:listall'interno del tuo progetto Firebase in un terminale per mostrare quali delle estensioni installate hanno sostituzioni ufficiali:firebase ext:list --project my-projecti extensions: ensuring required API firebaseextensions.googleapis.com is enabled... ✔ extensions: required API firebaseextensions.googleapis.com is enabled i extensions: list of extensions installed in my-project: ┌────────────────────────────────────┬───────────┬────────────────────────────────┬────────┬─────────┬─────────────────────┬───────────────────────────────────────────────────┐ │ Extension │ Publisher │ Instance ID │ State │ Version │ Your last update │ Replacement Kit │ ├────────────────────────────────────┼───────────┼────────────────────────────────┼────────┼─────────┼─────────────────────┼───────────────────────────────────────────────────┤ │ firebase/firestore-bigquery-export │ firebase │ firestore-bigquery-export-zbrp │ ACTIVE │ 0.3.2 │ 2026-06-10 18:35:03 │ @firebase-function-kits/firestore-bigquery-export │ ├────────────────────────────────────┼───────────┼────────────────────────────────┼────────┼─────────┼─────────────────────┼───────────────────────────────────────────────────┤ │ firebase/storage-resize-images │ firebase │ storage-resize-images │ ACTIVE │ 0.3.6 │ 2026-06-03 17:41:24 │ │ └────────────────────────────────────┴───────────┴────────────────────────────────┴────────┴─────────┴─────────────────────┴───────────────────────────────────────────────────┘ ⚠ Notice: Firebase Extensions will shut down on March 31, 2027. Learn more: https://firebase.google.com/docs/extensions/faq-and-troubleshooting
Se è disponibile una sostituzione ufficiale del kit di funzioni per la tua estensione, puoi eseguirne la migrazione utilizzando la sezione Eseguire la migrazione ai kit di funzioni su npm.
Se non riesci a trovare una sostituzione pubblicata, puoi eseguire il fork del codice dell'estensione e creare la tua sostituzione perché tutte le estensioni sono open source. Per farlo, segui la guida Eseguire la migrazione a un kit di funzioni creato autonomamente.
| Seleziona il percorso di migrazione: | Esegui la migrazione ai kit di funzioni su npm Esegui la migrazione a un kit di funzioni creato autonomamente |
Eseguire la migrazione ai kit di funzioni su npm
Controllare le limitazioni note della migrazione
Prima di iniziare la migrazione di un'istanza di estensione, verifica se la tua configurazione utilizza una delle seguenti funzionalità che richiedono una soluzione alternativa o non sono ancora supportate nei kit di funzioni:
- I repository Docker personalizzati e le chiavi KMS richiedono una soluzione alternativa manuale Cloud Functions for Firebase non supporta i parametri di sistema di sostituzione per configurare un repository Docker personalizzato o una chiave di crittografia gestita dal cliente (chiave KMS). Se la tua estensione configura uno di questi parametri, consulta la soluzione alternativa riportata nelle domande frequenti.
Prima di iniziare
Devi configurare la CLI Firebase e
inizializzare un progetto Firebase. Quando utilizzi la CLI, assicurati
di utilizzare la versione firebase-tools >= 15.32.0, che include i nuovi comandi di migrazione
e del kit di funzioni.
Ruoli e autorizzazioni dell'account richiesti
A seconda di ciò che deve essere creato e configurato dalla CLI Firebase durante la migrazione, l'account che utilizzi per l'autenticazione con Firebase e Google Cloud deve disporre dei seguenti ruoli:
roles/firebaseextensions.editorroles/cloudbuild.builds.editorroles/artifactregistry.writerroles/run.developerroles/iam.serviceAccountUserroles/iam.serviceAccountCreatorroles/cloudfunctions.admin(se devi eseguiresetIamPermissionsper gli endpoint pubblici)roles/secretmanager.admin(se utilizzi i secret)roles/serviceusage.serviceUsageAdmin(se devi abilitare nuove API)
Ti consigliamo di utilizzare un account in cui sono state installate estensioni e sono state implementate funzioni in precedenza, poiché la maggior parte di queste autorizzazioni sarà già stata concessa. Se l'account di migrazione ha bisogno di altri ruoli, segui le istruzioni IAM Google Cloud per aggiungerli.
Scegliere un workflow della CLI
Per eseguire la migrazione da un'istanza di estensione a un kit di funzioni disponibile su npm, scegli una delle seguenti opzioni:
- (Consigliato) Esegui la migrazione utilizzando il comando CLI
ext:migrate. Questo comando esegue il deployment della sostituzione del kit di funzioni prima di disinstallare l'estensione che sostituisce. - Esegui la migrazione utilizzando i comandi CLI dei kit di funzioni. Puoi utilizzare comandi separati per aggiornare l'estensione, installare un kit di funzioni, configurarlo come l'estensione, eseguire il deployment del kit e disinstallare l'estensione. In questo modo, hai più flessibilità per riordinare i comandi o eseguire operazioni aggiuntive tra i passaggi.
Esegui la migrazione utilizzando ext:migrate
Avvia una migrazione una volta per istanza di estensione eseguendo:
firebase ext:migrate --project <project-id>
Questo comando ti guida attraverso:
- Selezionando un'estensione di cui eseguire la migrazione che ha una sostituzione ufficiale del kit di funzioni disponibile.
- Selezionando un'istanza specifica dell'estensione.
- Aggiornamento dell'estensione all'ultima versione, se necessario.
- Installazione del kit di funzioni, configurazione di un'istanza identica a quella dell'istanza dell'estensione.
- Deployment del kit di funzioni.
- Verifica che il kit di funzioni sia stato implementato correttamente e che tutti gli hook del ciclo di vita, se presenti, siano stati eseguiti.
- Disinstallazione dell'istanza dell'estensione.
Se conosci l'estensione o l'istanza di estensione specifica che vuoi migrare, specificala utilizzando i seguenti flag della riga di comando:
firebase ext:migrate --extension firebase/firestore-bigquery-export --project <project-id>
# or
firebase ext:migrate --ext-instance firestore-bigquery-export-abcd --project <project-id>
Se conosci il pacchetto specifico a cui vuoi eseguire la migrazione, soprattutto se non si tratta di un pacchetto di sostituzione ufficiale elencato da Google, specificalo utilizzando il flag --package:
firebase ext:migrate --ext-instance firestore-bigquery-export-abcd --package @firebase-function-kits/firestore-bigquery-export --project <project-id>
Verificare il deployment di un kit di funzioni
Per verificare che l'firebase deploy del kit non abbia generato errori, controlla i log di deployment per vedere se sono stati attivati hook del ciclo di vita. Le estensioni più diffuse, come Stream Cloud Firestore to BigQuery, utilizzano hook del ciclo di vita. Di seguito è riportato un esempio di come appare un hook del ciclo di vita quando viene attivato:
i functions: Executing afterFirstDeploy lifecycle hook targeting: kit-firestore-bigquery-export-initBigQuerySync...
✔ functions: Successfully queued task for lifecycle hook kit-firestore-bigquery-export-initBigQuerySync in queue projects/my-project/locations/europe-west1/queues/kit-firestore-bigquery-export-initBigQuerySync.
i functions: View logs for afterFirstDeploy at: https://console.cloud.google.com/logs/query;query=resource.type%3D%22cloud_run_revision%22%0Aresource.labels.service_name%3D%22kit-firestore-bigquery-export--initbigquerysync%22%0Aresource.labels.location%3D%22europe-west1%22;project=my-project
Questi messaggi di log confermano quanto segue:
- È stato trovato ed eseguito un hook del ciclo di vita.
- Un'attività è stata inserita nella coda di attività associata all'hook del ciclo di vita.
- È stato fornito un link a Cloud Logging per consentirti di verificare che l'attività sia stata completata senza errori.
Segui il link ai log nella console Google Cloud per verificare che non siano presenti errori nei log e che l'evento della coda di attività sia stato elaborato correttamente. Se l'evento del ciclo di vita non è stato eseguito correttamente, puoi riattivarlo eseguendo:
firebase functions:lifecycle:run <hook-name> <codebase>
Se stai eseguendo il deployment di un'istanza di Function Kit per la prima volta, esegui:
firebase functions:lifecycle:run afterFirstDeploy <kit-instance-id>
Se in qualsiasi momento durante la convalida decidi di interrompere o annullare questa migrazione, puoi disinstallare il kit seguendo le istruzioni riportate in Disinstallare l'estensione.
Esamina il file README del kit di funzioni
Alcuni kit potrebbero richiedere un lavoro aggiuntivo rispetto a quello gestito automaticamente dai kit di funzioni. Consulta le README per il kit che stai installando e segui le istruzioni aggiuntive.
Esegui la migrazione utilizzando la CLI dei kit di funzioni
Prima di iniziare, identifica e annota l'ID istanza dell'estensione che vuoi migrare a un kit e il nome del pacchetto npm del kit sostitutivo. Puoi trovare entrambi utilizzando l'output di firebase ext:list. Consulta
Determinare il percorso di migrazione per un esempio di utilizzo di
ext:list.
1. Esegui l'upgrade dell'istanza dell'estensione all'ultima versione
Devi aggiornare l'estensione all'ultima versione per ridurre al minimo la differenza tra l'istanza dell'estensione e il relativo kit di sostituzione. Se l'estensione non viene aggiornata, potrebbero esserci modifiche significative e incompatibili tra l'istanza dell'estensione e la sostituzione del kit. La configurazione esportata potrebbe non corrispondere a quella prevista dal kit a causa delle modifiche dei parametri nelle varie versioni.
Utilizza una delle seguenti opzioni per aggiornare l'estensione, a seconda di dove è stata installata:
- Dalla console Firebase
- Da Firebase CLI utilizzando:
firebase ext:update <extension-instance-id> --project <project-id> firebase deploy --only extensions --project <project-id>
Se salti questo passaggio, la CLI ti chiede di eseguire l'upgrade durante l'esportazione della configurazione se l'estensione non è nell'ultima versione.
2. Esamina e installa l'istanza del kit di funzioni sostitutivo
Puoi installare il kit di funzioni utilizzando il seguente comando CLI:
firebase functions:kits:install --template migration --no-configure --package <npm-package-name> --project <project-id>
Quando scegli un ID istanza per il tuo kit durante l'installazione, assicurati di annotarlo per utilizzarlo in un secondo momento nelle istruzioni di migrazione.
Una volta installato il kit, viene creata una nuova directory all'interno del progetto Firebase con un percorso come function-kits/<kit-name>/source che contiene il pacchetto npm con il kit che sostituisce l'estensione e un file index.ts di base che esporta queste funzioni per consentire a Firebase di eseguire il deployment e impostare la configurazione personalizzata.
Leggi il file README del kit e segui le istruzioni aggiuntive elencate.
Se hai più istanze del kit nello stesso progetto, puoi ripetere questo comando per creare nuove istanze dello stesso kit. Puoi anche eseguire il deployment di una singola istanza del kit in due progetti Firebase diversi con configurazioni diverse (ad esempio, un progetto di staging e un progetto di produzione). Per scoprire di più su queste configurazioni avanzate, consulta Migrazioni avanzate.
Esempio elaborato:
firebase functions:kits:install --template migration --no-configure --package @firebase-function-kits/firestore-bigquery-export --project my-project
3. Configura l'istanza del kit di funzioni in modo identico all'estensione
Devi personalizzare questa istanza del kit con una configurazione identica all'estensione che sta sostituendo. Puoi esportare la configurazione dell'istanza dell'estensione
in un file .env, che memorizza i dati di configurazione di parametri, variabili di ambiente e riferimenti ai secret
per tutti i Cloud Functions, inclusi i kit. Per
esportarlo direttamente nel file di configurazione del kit, esegui:
firebase ext:export --mode functions --instance <extension-instance-id> --kit-instance <kit-instance-id> --project <project-id>
Al termine di questo passaggio, le informazioni di configurazione per questa istanza vengono
memorizzate in un file .env specifico del progetto nella directory di configurazione dell'istanza, ad esempio:
function-kits/<kit-name>/config-<instance-id>/.env.<project-id>
4. Esegui il deployment e verifica la sostituzione del kit
Ora che il kit è installato e disponibile come insieme di funzioni, puoi eseguire il deployment della sostituzione del kit. I kit di funzioni funzionano come le funzioni standard, in cui ogni istanza del kit funge da base di codice separata per organizzare le funzioni. Puoi scegliere di eseguire il deployment di tutte le funzioni o solo di un'istanza specifica del kit. Durante la migrazione di una singola istanza di estensione, esegui il deployment solo di questa istanza del kit.
Se il tuo kit utilizza nuovi parametri non presenti nell'istanza dell'estensione da cui hai eseguito la migrazione, la CLI Firebase ti chiede di inserirli all'inizio della procedura di deployment. Questo non è previsto in questo esempio pratico
di un'estensione firestore-bigquery-export aggiornata, ma molti kit richiedono
un nuovo parametro per qualsiasi origine trigger evento utilizzata dal kit. Nell'ambito di questa migrazione, i kit aggiornati utilizzano le funzioni di 2ª gen. in cui le estensioni utilizzavano in precedenza le funzioni di 1ª gen. Nella 2ª gen., le funzioni si trovano vicino alle origini eventi e vengono aggiunte come parametro aggiuntivo. Negli aggiornamenti futuri, se vengono aggiunti nuovi
parametri, la CLI ti chiederà di inserirli nella prossima implementazione.
Esempio elaborato:
firebase deploy --only functions:firestore-bigquery-export --project my-project
Output:
=== Deploying to 'my-project'...
i deploying functions
i functions: Loaded environment variables from function-kits/firestore-bigquery-export/config-firestore-bigquery-export/.env.my-project
i functions: ensuring required API bigquery.googleapis.com is enabled...
i functions: ensuring required API cloudtasks.googleapis.com is enabled...
✔ functions: required APIs are enabled
i functions: granting declarative IAM roles to managed service account:
- BigQuery Data Editor
- BigQuery User
- Cloud Datastore User
- Eventarc Event Receiver
- roles/run.invoker
✔ functions: successfully granted IAM roles
i functions: creating Node.js 22 (2nd Gen) function kit-firestore-bigquery-export-fsexportbigquery(us-central1)...
i functions: creating Node.js 22 (2nd Gen) function kit-firestore-bigquery-export-initBigQuerySync(us-central1)...
i functions: creating Node.js 22 (2nd Gen) function kit-firestore-bigquery-export-setupBigQuerySync(us-central1)...
✔ functions[kit-firestore-bigquery-export-fsexportbigquery(us-central1)] Successful create operation.
✔ functions[kit-firestore-bigquery-export-initBigQuerySync(us-central1)] Successful create operation.
✔ functions[kit-firestore-bigquery-export-setupBigQuerySync(us-central1)] Successful create operation.
i functions: Executing afterFirstDeploy lifecycle hook targeting: kit-firestore-bigquery-export-initBigQuerySync...
✔ functions: Successfully queued task for lifecycle hook kit-firestore-bigquery-export-initBigQuerySync in queue projects/my-project/locations/us-central1/queues/kit-firestore-bigquery-export-initBigQuerySync.
✔ Deploy complete!
Per verificare che l'firebase deploy del kit non abbia generato errori, controlla i log di deployment per vedere se sono stati attivati hook del ciclo di vita. Le estensioni più diffuse, come Stream Cloud Firestore to BigQuery, utilizzano hook del ciclo di vita. Di seguito è riportato un esempio di come appare un hook del ciclo di vita quando viene attivato:
i functions: Executing afterFirstDeploy lifecycle hook targeting: kit-firestore-bigquery-export-initBigQuerySync...
✔ functions: Successfully queued task for lifecycle hook kit-firestore-bigquery-export-initBigQuerySync in queue projects/my-project/locations/europe-west1/queues/kit-firestore-bigquery-export-initBigQuerySync.
i functions: View logs for afterFirstDeploy at: https://console.cloud.google.com/logs/query;query=resource.type%3D%22cloud_run_revision%22%0Aresource.labels.service_name%3D%22kit-firestore-bigquery-export--initbigquerysync%22%0Aresource.labels.location%3D%22europe-west1%22;project=my-project
Questi messaggi di log confermano quanto segue:
- È stato trovato ed eseguito un hook del ciclo di vita.
- Un'attività è stata inserita nella coda di attività associata all'hook del ciclo di vita.
- È stato fornito un link a Cloud Logging per consentirti di verificare che l'attività sia stata completata senza errori.
Segui il link ai log nella console Google Cloud per verificare che non siano presenti errori nei log e che l'evento della coda di attività sia stato elaborato correttamente. Se l'evento del ciclo di vita non è stato eseguito correttamente, puoi riattivarlo eseguendo:
firebase functions:lifecycle:run <hook-name> <codebase>
Se stai eseguendo il deployment di un'istanza di Function Kit per la prima volta, esegui:
firebase functions:lifecycle:run afterFirstDeploy <kit-instance-id>
Se in qualsiasi momento durante la convalida decidi di interrompere o annullare questa migrazione, puoi disinstallare il kit seguendo le istruzioni riportate in Disinstallare l'estensione.
5. Disinstallare l'estensione
Dopo aver verificato il kit di funzioni di cui è stato eseguito il deployment, puoi disinstallare l'estensione in modo da non duplicare il suo comportamento una volta per il kit e una volta per l'estensione. Puoi disinstallare tutte le estensioni dalla CLI Firebase
indipendentemente da come le hai installate se passi il flag --immediate:
firebase ext:uninstall <extension-instance-id> --project <project-id> --immediate
Esempio elaborato:
firebase ext:uninstall firestore-bigquery-export --project my-project --immediate
Output:
i extensions: uninstalling firestore-bigquery-export...
i extensions: deleting extension instance resources in project my-project...
✔ extensions: successfully uninstalled firestore-bigquery-export
Migrazioni avanzate
Puoi avere estensioni in più progetti Firebase che vuoi
gestire con un unico codebase. Ad esempio, se esegui il deployment della stessa infrastruttura in un ambiente testing e in un ambiente production, ognuno dei quali ha un'istanza documents Cloud Firestore che esporti in BigQuery, potresti avere due istanze dell'estensione firestore-bigquery-export installate:
export-documents-testingexport-documents-production
Se hai eseguito la migrazione di queste due istanze di estensione a due istanze del kit di funzioni in un unico codebase quando utilizzi la CLI Firebase ed esegui il deployment utilizzando firebase deploy --project testing e firebase deploy --project production, ogni deployment creerebbe due istanze negli ambienti testing e production.
Sostituisci invece le due istanze dell'estensione con un'istanza del kit di funzioni di
firestore-bigquery-export di cui è stato eseguito il deployment in più progetti, dove ogni progetto
ha una propria configurazione. La directory di configurazione per l'istanza dovrebbe
essere simile alla seguente:
config-export-documents/.env.testing.env.production
Ogni deployment in testing e production crea un'istanza del kit
con la configurazione corrispondente. I comandi CLI esistenti creano questa
configurazione a condizione che tu trasmetta il flag --project in ogni chiamata di
ext:migrate o functions:kits:install.
Esempio elaborato:
firebase functions:kits:install --package @firebase-function-kits/firestore-bigquery-export --project testing --no-configure --template migration
✔ What would you like to name this kit? firestore-bigquery-export
✔ What would you like to name this instance? export-documents
✔ Wrote function-kits/firestore-bigquery-export/source/package.json
✔ Wrote function-kits/firestore-bigquery-export/source/tsconfig.json
✔ Wrote function-kits/firestore-bigquery-export/source/.gitignore
✔ Wrote function-kits/firestore-bigquery-export/source/src/index.ts
i functions: Running npm install
✔ Wrote configuration info to firebase.json
✔ functions: Function kit firestore-bigquery-export successfully installed.
# This creates the export-documents instance with an empty .env.testing file
# for the testing project. Now populate it via export:
firebase ext:export --mode functions --instance export-documents-testing \
--kit-instance export-documents --project testing
# Repeat the export for production into the same kit instance to create
# .env.production from the export-documents-prod instance:
firebase ext:export --mode functions --instance export-documents-prod \
--kit-instance export-documents --project production
Ora hai una singola istanza del kit configurata per il deployment nei progetti testing e
production con le rispettive configurazioni. Se crei un'istanza nel progetto testing ed esegui il comando functions:kits:install per lo stesso pacchetto nel progetto production, ti viene chiesto se vuoi riutilizzare l'istanza configurata per testing o installare una seconda istanza.