Z tego przewodnika dowiesz się, jak przenieść rozszerzenia z wycofanego środowiska Firebase Extensions do pakietu funkcji, który możesz zainstalować i wdrożyć we własnym środowisku Cloud Functions w przypadku kodu Firebase (2 generacji).
Firebase Extensions zarządzać wszystkimi aspektami tworzenia, aktualizowania i usuwania rozszerzeń; Zestawy funkcji zawierają możliwości rozszerzeń w postaci typowych funkcji 2 generacjiCloud Functions for Firebase. Zestawy funkcji są standardoweCloud Functions, więc możesz je tworzyć, aktualizować, usuwać i rozwiązywać problemy z nimi za pomocą interfejsu CLIFirebase w projekcieFirebase. Z tego przewodnika dowiesz się, jak zarządzać funkcjami i wdrażać aktualizacje, gdy będą dostępne.
W tym przewodniku jako przykładu używamy rozszerzenia Stream Cloud Firestore to BigQuery (firestore-bigquery-export), które pokazuje polecenia i wyniki poleceń na każdym etapie migracji.
Określanie ścieżki migracji
Firebase zachęca wszystkich wydawców Firebase Extensions do tworzenia zamienników rozszerzeń w postaci pakietów funkcji publikowanych w npm. Możesz sprawdzić, czy dla Twoich rozszerzeń dostępny jest zamiennik zestawu funkcji, na kilka sposobów:
- Otwórz stronę Rozszerzenia w Firebasekonsoli projektu. Każde zainstalowane rozszerzenie wskazuje, czy ma dostępny zamiennik zestawu funkcji.
Uruchom
firebase ext:listw projekcie Firebase w terminalu, aby sprawdzić, które z zainstalowanych rozszerzeń mają oficjalne zamienniki: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
Jeśli dla Twojego rozszerzenia dostępny jest oficjalny zestaw funkcji, możesz go zmigrować, korzystając z sekcji Migracja do zestawów funkcji w npm.
Jeśli nie możesz znaleźć opublikowanego zamiennika, możesz rozwidlić kod rozszerzenia i utworzyć własny zamiennik, ponieważ wszystkie rozszerzenia są dostępne na licencji open source. Aby to zrobić, postępuj zgodnie z instrukcjami w przewodniku Migracja do samodzielnie utworzonego zestawu funkcji.
| Wybierz ścieżkę migracji: | Przejście na pakiety funkcji w npm Przejście na samodzielnie utworzony pakiet funkcji |
Przenoszenie do pakietów funkcji w npm
Sprawdzanie znanych ograniczeń migracji
Zanim rozpoczniesz migrację instancji rozszerzenia, sprawdź, czy Twoja konfiguracja korzysta z którejś z tych funkcji, które wymagają obejścia lub nie są jeszcze obsługiwane w zestawach funkcji:
- Niestandardowe repozytoria Dockera i klucze KMS wymagają ręcznego obejścia Cloud Functions for Firebase nie obsługuje parametrów systemu zastępczego do konfigurowania niestandardowego repozytorium Dockera ani klucza szyfrowania zarządzanego przez klienta (klucza KMS). Jeśli rozszerzenie konfiguruje którykolwiek z tych parametrów, zapoznaj się z obejściem problemu w sekcji z najczęstszymi pytaniami.
Zanim zaczniesz
Musisz skonfigurować interfejs wiersza poleceń Firebase i zainicjować projekt Firebase. Jeśli używasz interfejsu wiersza poleceń, upewnij się, że korzystasz z firebase-tools wersji >= 15.32.0, która zawiera nowe polecenia migracji i zestawu funkcji.
Wymagane uprawnienia i role konta
W zależności od tego, co musi zostać utworzone i skonfigurowane przez Firebase CLI podczas migracji, konto, którego używasz do uwierzytelniania w Firebase i Google Cloud, musi mieć te role:
roles/firebaseextensions.editorroles/cloudbuild.builds.editorroles/artifactregistry.writerroles/run.developerroles/iam.serviceAccountUserroles/iam.serviceAccountCreatorroles/cloudfunctions.admin(jeśli musisz to zrobićsetIamPermissionsw przypadku publicznych punktów końcowych)roles/secretmanager.admin(jeśli używasz obiektów tajnych)roles/serviceusage.serviceUsageAdmin(jeśli musisz włączyć nowe interfejsy API)
Zalecamy używanie konta, na którym zainstalowano już rozszerzenia i wdrożono funkcje, ponieważ większość tych uprawnień będzie już przyznana. Jeśli przenoszone konto potrzebuje więcej ról, postępuj zgodnie z Google Cloudinstrukcjami dotyczącymi uprawnień, aby je dodać.
Wybierz przepływ pracy interfejsu CLI
Aby przeprowadzić migrację z instancji rozszerzenia do pakietu funkcji dostępnego w npm, wybierz jedną z tych opcji:
- (Zalecane) Migracja za pomocą polecenia interfejsu wiersza poleceń
ext:migrate. To polecenie wdraża zamiennik zestawu funkcji przed odinstalowaniem rozszerzenia, które zastępuje. - Przenieś dane za pomocą poleceń interfejsu wiersza poleceń pakietów funkcji. Możesz użyć osobnych poleceń, aby zaktualizować rozszerzenie, zainstalować zestaw funkcji, skonfigurować go tak jak rozszerzenie, wdrożyć zestaw i odinstalować rozszerzenie. Zapewnia to większą elastyczność w zakresie zmiany kolejności poleceń lub wykonywania dodatkowych działań między poszczególnymi krokami.
Migracja za pomocą ext:migrate
Rozpocznij migrację, uruchamiając to polecenie raz na instancję rozszerzenia:
firebase ext:migrate --project <project-id>
To polecenie przeprowadzi Cię przez:
- Wybieranie rozszerzenia do migracji, które ma dostępny oficjalny zestaw funkcji zastępujących.
- wybranie konkretnej instancji tego rozszerzenia.
- w razie potrzeby zaktualizować rozszerzenie do najnowszej wersji;
- Zainstaluj pakiet funkcji i skonfiguruj instancję w taki sam sposób jak instancję rozszerzenia.
- Wdrażanie pakietu funkcji.
- Sprawdź, czy zestaw funkcji został wdrożony i czy wszystkie wywołania zwrotne cyklu życia (jeśli takie istnieją) zostały uruchomione.
- Odinstalowywanie instancji rozszerzenia.
Jeśli znasz konkretne rozszerzenie lub instancję rozszerzenia, które chcesz przenieść, określ je za pomocą tych flag wiersza poleceń:
firebase ext:migrate --extension firebase/firestore-bigquery-export --project <project-id>
# or
firebase ext:migrate --ext-instance firestore-bigquery-export-abcd --project <project-id>
Jeśli znasz konkretny pakiet, na który chcesz przejść, zwłaszcza jeśli nie jest to oficjalny pakiet zastępczy wymieniony przez Google, określ go za pomocą flagi --package:
firebase ext:migrate --ext-instance firestore-bigquery-export-abcd --package @firebase-function-kits/firestore-bigquery-export --project <project-id>
Sprawdzanie wdrożenia zestawu funkcji
Aby sprawdzić, czy firebase deploy zestawu nie zawierał błędów, przejrzyj dzienniki wdrażania i sprawdź, czy zostały wywołane jakieś punkty zaczepienia cyklu życia. Popularne rozszerzenia, takie jak Stream Cloud Firestore to BigQuery, korzystają z haków cyklu życia. Poniżej znajdziesz przykład wywołania haka cyklu życia:
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
Te wiadomości w dzienniku potwierdzają:
- Wykryto i wykonano funkcję cyklu życia.
- Zadanie zostało umieszczone w kolejce zadań powiązanej z punktem zaczepienia cyklu życia.
- Podano link do Cloud Logging, aby można było sprawdzić, czy zadanie zostało wykonane bez błędów.
Kliknij link do dzienników w konsoli Google Cloud, aby sprawdzić, czy w dziennikach nie ma błędów i czy zdarzenie kolejki zadań zostało przetworzone. Jeśli zdarzenie cyklu życia nie zostało wykonane prawidłowo, możesz je ponownie wywołać, uruchamiając to polecenie:
firebase functions:lifecycle:run <hook-name> <codebase>
Jeśli wdrażasz instancję pakietu funkcji po raz pierwszy, uruchom to polecenie:
firebase functions:lifecycle:run afterFirstDeploy <kit-instance-id>
Jeśli w dowolnym momencie w trakcie weryfikacji zdecydujesz, że chcesz przerwać lub cofnąć tę migrację, możesz odinstalować zestaw, postępując zgodnie z instrukcjami w sekcji Odinstalowywanie rozszerzenia.
Zapoznaj się z plikiem README zestawu funkcji
Niektóre zestawy mogą wymagać dodatkowych działań poza tymi, które są obsługiwane automatycznie przez zestawy funkcji. Zapoznaj się z README dla instalowanego zestawu i postępuj zgodnie z dodatkowymi instrukcjami.
Migracja za pomocą interfejsu wiersza poleceń pakietów funkcji
Zanim zaczniesz, znajdź i zapisz identyfikator instancji rozszerzenia, które chcesz przenieść do zestawu, oraz nazwę pakietu npm zastępującego go zestawu. Oba te elementy znajdziesz w danych wyjściowych polecenia firebase ext:list. Przykład użycia funkcji ext:list znajdziesz w artykule Określanie ścieżki migracji.
1. Uaktualnianie instancji rozszerzenia do najnowszej wersji
Aby zminimalizować różnicę między instancją rozszerzenia a zestawem zastępczym, musisz zaktualizować rozszerzenie do najnowszej wersji. Jeśli rozszerzenie nie zostanie uaktualnione, między jego instancją a zestawem zastępczym mogą wystąpić istotne zmiany powodujące błędy. Wyeksportowana konfiguracja może nie pasować do oczekiwań zestawu z powodu zmian parametrów w różnych wersjach.
Aby zaktualizować rozszerzenie, skorzystaj z jednej z tych opcji w zależności od tego, gdzie zostało ono zainstalowane:
- W Firebasekonsoli
- Z interfejsu wiersza poleceń Firebase za pomocą tego polecenia:
firebase ext:update <extension-instance-id> --project <project-id> firebase deploy --only extensions --project <project-id>
Jeśli pominiesz ten krok, interfejs wiersza poleceń wyświetli prośbę o uaktualnienie podczas eksportowania konfiguracji, jeśli rozszerzenie nie jest w najnowszej wersji.
2. Sprawdź i zainstaluj instancję zestawu funkcji zastępczych
Zestaw funkcji możesz zainstalować za pomocą tego polecenia interfejsu wiersza poleceń:
firebase functions:kits:install --template migration --no-configure --package <npm-package-name> --project <project-id>
Gdy podczas instalacji wybierzesz identyfikator instancji zestawu, zapisz go, aby użyć go później w instrukcjach migracji.
Po zainstalowaniu zestawu w projekcie Firebase zostanie utworzony nowy katalog, np. function-kits/<kit-name>/source, który zawiera pakiet npm z zestawem zastępującym rozszerzenie oraz podstawowy plik index.ts eksportujący te funkcje, aby Firebase mógł wdrożyć i skonfigurować niestandardowe ustawienia.
Zapoznaj się z dokumentem README dołączonym do zestawu i postępuj zgodnie z dodatkowymi instrukcjami.
Jeśli w tym samym projekcie masz kilka instancji zestawu, możesz powtórzyć to polecenie, aby utworzyć nowe instancje tego samego zestawu. Możesz też wdrożyć 1 instancję zestawu w 2 różnych projektachFirebase o różnych konfiguracjach (np. w projekcie testowym i produkcyjnym). Więcej informacji o tych zaawansowanych konfiguracjach znajdziesz w sekcji Zaawansowane migracje.
Przykład:
firebase functions:kits:install --template migration --no-configure --package @firebase-function-kits/firestore-bigquery-export --project my-project
3. Skonfiguruj instancję pakietu funkcji identycznie jak rozszerzenie.
Musisz dostosować tę instancję zestawu za pomocą konfiguracji identycznej z zastępowanym rozszerzeniem. Możesz wyeksportować konfigurację instancji rozszerzenia do pliku .env, który przechowuje dane konfiguracji parametrów, zmiennych środowiskowych i odwołań do kluczy tajnych dla wszystkich Cloud Functions, w tym zestawów. Aby wyeksportować go bezpośrednio do pliku konfiguracji zestawu, uruchom:
firebase ext:export --mode functions --instance <extension-instance-id> --kit-instance <kit-instance-id> --project <project-id>
Po wykonaniu tego kroku informacje o konfiguracji tej instancji zostaną zapisane w pliku .env w katalogu konfiguracji instancji, np.:function-kits/<kit-name>/config-<instance-id>/.env.<project-id>
4. Wdrażanie i weryfikowanie wymiany zestawu
Po zainstalowaniu zestawu i udostępnieniu go jako zestawu funkcji możesz wdrożyć zamiennik zestawu. Zestawy funkcji działają jak standardowe funkcje, przy czym każda instancja zestawu pełni funkcję osobnej bazy kodu do organizowania funkcji. Możesz wdrożyć wszystkie funkcje lub tylko konkretną instancję zestawu. Podczas migracji pojedynczej instancji rozszerzenia wdróż tylko tę instancję pakietu.
Jeśli zestaw korzysta z nowych parametrów, których nie było w instancji rozszerzenia, z której przeprowadzono migrację, interfejs wiersza poleceń Firebase poprosi o ich podanie na początku procesu wdrażania. W tym przykładzie nie jest to oczekiwane w przypadku aktualnego rozszerzenia firestore-bigquery-export, ale wiele zestawów SDK wyświetla prośbę o podanie nowego parametru dla każdego źródła wyzwalającego zdarzenie używanego przez zestaw SDK. W ramach tej migracji zaktualizowane zestawy korzystają z funkcji 2 generacji, podczas gdy rozszerzenia wcześniej używały funkcji 1 generacji. W przypadku funkcji 2 generacji znajdują się one w pobliżu źródeł zdarzeń i są dodawane jako dodatkowy parametr. W przyszłych aktualizacjach, jeśli zostaną dodane nowe parametry, interfejs CLI wyświetli prośbę o ich podanie podczas następnego wdrażania.
Przykład:
firebase deploy --only functions:firestore-bigquery-export --project my-project
Dane wyjściowe:
=== 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!
Aby sprawdzić, czy firebase deploy zestawu nie zawierał błędów, przejrzyj dzienniki wdrażania i sprawdź, czy zostały wywołane jakieś punkty zaczepienia cyklu życia. Popularne rozszerzenia, takie jak Stream Cloud Firestore to BigQuery, korzystają z haków cyklu życia. Poniżej znajdziesz przykład wywołania haka cyklu życia:
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
Te wiadomości w dzienniku potwierdzają:
- Wykryto i wykonano funkcję cyklu życia.
- Zadanie zostało umieszczone w kolejce zadań powiązanej z punktem zaczepienia cyklu życia.
- Podano link do Cloud Logging, aby można było sprawdzić, czy zadanie zostało wykonane bez błędów.
Kliknij link do dzienników w konsoli Google Cloud, aby sprawdzić, czy w dziennikach nie ma błędów i czy zdarzenie kolejki zadań zostało przetworzone. Jeśli zdarzenie cyklu życia nie zostało wykonane prawidłowo, możesz je ponownie wywołać, uruchamiając to polecenie:
firebase functions:lifecycle:run <hook-name> <codebase>
Jeśli wdrażasz instancję pakietu funkcji po raz pierwszy, uruchom to polecenie:
firebase functions:lifecycle:run afterFirstDeploy <kit-instance-id>
Jeśli w dowolnym momencie w trakcie weryfikacji zdecydujesz, że chcesz przerwać lub cofnąć tę migrację, możesz odinstalować zestaw, postępując zgodnie z instrukcjami w sekcji Odinstalowywanie rozszerzenia.
5. Odinstalowywanie rozszerzenia
Gdy sprawdzisz wdrożony zestaw funkcji, możesz odinstalować rozszerzenie, aby nie powielać jego działania – raz w przypadku zestawu i raz w przypadku rozszerzenia. Możesz odinstalować wszystkie rozszerzenia z Firebase CLI
niezależnie od tego, jak zostały zainstalowane, jeśli przekażesz flagę --immediate:
firebase ext:uninstall <extension-instance-id> --project <project-id> --immediate
Przykład:
firebase ext:uninstall firestore-bigquery-export --project my-project --immediate
Dane wyjściowe:
i extensions: uninstalling firestore-bigquery-export...
i extensions: deleting extension instance resources in project my-project...
✔ extensions: successfully uninstalled firestore-bigquery-export
Zaawansowane migracje
Możesz mieć rozszerzenia w wielu projektach Firebase, którymi chcesz zarządzać za pomocą jednej bazy kodu. Jeśli na przykład wdrożysz tę samą infrastrukturę w środowiskach testing i production, z których każde ma instancję documents Cloud Firestore wyeksportowaną do BigQuery, możesz mieć zainstalowane 2 instancje rozszerzenia firestore-bigquery-export:
export-documents-testingexport-documents-production
Jeśli podczas pracy z interfejsem wiersza poleceń Firebase przeniesiesz te 2 instancje rozszerzeń do 2 instancji zestawu funkcji w jednej bazie kodu i wdrożysz je za pomocą poleceń firebase deploy --project testing i firebase deploy --project production, każde wdrożenie utworzy 2 instancje w środowiskach testing i production.
Zamiast tego zastąp 2 instancje rozszerzenia 1 instancją zestawu funkcjifirestore-bigquery-export wdrożoną w wielu projektach, z których każdy ma własną konfigurację. Katalog konfiguracji instancji powinien wyglądać tak:
config-export-documents/.env.testing.env.production
Każde wdrożenie w usługach testing i production tworzy 1 instancję zestawu z odpowiednią konfiguracją. Obecne polecenia interfejsu CLI tworzą tę konfigurację, o ile w każdym wywołaniu poleceń
ext:migrate lub functions:kits:install podasz flagę --project.
Przykład:
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
Masz teraz jedną instancję zestawu skonfigurowaną do wdrażania w projektach testing i production z odpowiednimi konfiguracjami. Jeśli utworzysz instancję w projekcie testing i uruchomisz polecenie functions:kits:install dla tego samego pakietu w projekcie production, pojawi się prośba o ponowne użycie instancji skonfigurowanej dla projektu testing lub zainstalowanie drugiej instancji.