Перенесите Firebase Extensions в наборы функций

В этом руководстве рассказывается, как перенести расширения из устаревшей среды Firebase Extensions в набор функций, который можно установить и развернуть в собственной базе кода Cloud Functions для Firebase (второе поколение).

Firebase Extensions управлял всеми аспектами создания, обновления и удаления расширений. Наборы функций упаковывают возможности расширений как типичные Cloud Functions for Firebase второго поколения. Поскольку наборы функций – это стандартные Cloud Functions, вы можете создавать, обновлять, удалять и устранять неполадки в них с помощью интерфейса командной строки Firebase в проекте Firebase. Это руководство поможет вам управлять функциями и внедрять обновления по мере их появления.

В этом руководстве в качестве примера используется расширение Stream Cloud Firestore to BigQuery (firestore-bigquery-export). На его примере показаны команды и результаты выполнения команд для каждого шага переноса.

Определите способ переноса

Firebase рекомендует всем издателям Firebase Extensions создать замену для своих расширений в виде наборов функций, опубликованных в npm. Проверить, доступна ли замена набора функций для ваших расширений, можно несколькими способами:

• Перейдите на страницу расширений в консоли Firebase для вашего проекта. Для каждого установленного расширения указано, доступна ли для него замена набора функций.

• Чтобы узнать, для каких из установленных расширений есть официальные замены, в терминале проекта Firebase выполните команду firebase ext:list.

  firebase ext:list --project my-project
  

  i  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
  

Если для вашего расширения доступен официальный набор функций, вы можете перенести его, следуя инструкциям в разделе Переход на наборы функций в npm.

Если вы не можете найти опубликованную замену, вы можете создать ответвление кода расширения и создать собственную замену, поскольку все расширения являются ПО с открытым исходным кодом. Для этого следуйте инструкциям в руководстве Как перейти на собственный набор функций.

Переход на наборы функций в npm

Проверьте известные ограничения переноса

Прежде чем начать перенос экземпляра расширения, проверьте, использует ли ваша настройка какие-либо из следующих функций, которые требуют обходного пути или ещё не поддерживаются в наборах функций:

• Для пользовательских хранилищ Docker и ключей KMS требуется обходное решение Cloud Functions for Firebase не поддерживает замену системных параметров для настройки пользовательского хранилища Docker или ключа шифрования, управляемого клиентом (ключа KMS). Если ваше расширение настраивает один из этих параметров, ознакомьтесь с решением проблемы в разделе часто задаваемых вопросов.

Подготовка

Вам нужно настроить CLI Firebase и инициализировать проект Firebase. При использовании CLI убедитесь, что у вас установлена версия firebase-tools >= 15.32.0, в которой есть новые команды для переноса и набора функций.

Необходимые разрешения и роли в аккаунте

В зависимости от того, что нужно создать и настроить с помощью CLI Firebase во время переноса, аккаунт, который вы используете для аутентификации в Firebase и Google Cloud, должен иметь следующие роли:

• roles/firebaseextensions.editor
• roles/cloudbuild.builds.editor
• roles/artifactregistry.writer
• roles/run.developer
• roles/iam.serviceAccountUser
• roles/iam.serviceAccountCreator
• roles/cloudfunctions.admin (если вам нужно сделать setIamPermissions для общедоступных конечных точек)
• roles/secretmanager.admin (если используются секреты)
• roles/serviceusage.serviceUsageAdmin (если вам нужно включить новые API)

Рекомендуем использовать аккаунт, в котором уже устанавливались расширения и развертывались функции, поскольку в нем большинство разрешений уже предоставлено. Если аккаунту, который вы переносите, требуется больше ролей, добавьте их, следуя инструкциям по IAM для Google Cloud.

Выберите рабочий процесс CLI

Чтобы перейти от экземпляра расширения к набору функций, доступному в npm, выберите один из следующих вариантов:

• (Рекомендуется) Перенесите данные с помощью команды ext:migrate CLI. Эта команда развертывает замену набора функций перед удалением расширения, которое она заменяет.
• Выполните перенос с помощью команд CLI для наборов функций. Вы можете использовать отдельные команды, чтобы обновить расширение, установить набор функций, настроить его так же, как расширение, развернуть набор и удалить расширение. Это дает больше гибкости для изменения порядка команд или выполнения дополнительной работы между шагами.

Перенос с помощью ext:migrate

Для каждого экземпляра расширения запустите перенос, выполнив следующую команду:

firebase ext:migrate --project <project-id>

Эта команда позволяет:

1. Выбор расширения для переноса, у которого есть официальная замена в виде набора функций.
2. Выбор определенного экземпляра этого расширения.
3. При необходимости обновите расширение до последней версии.
4. Установка набора функций и настройка экземпляра так же, как настроен экземпляр расширения.
5. Развертывание набора функций.
6. Проверка успешности развертывания набора функций и выполнения всех хуков жизненного цикла (если они есть).
7. Удаление экземпляра расширения.

Если вы знаете, какое расширение или экземпляр расширения хотите перенести, укажите его с помощью следующих параметров командной строки:

firebase ext:migrate --extension firebase/firestore-bigquery-export --project <project-id>

# or

firebase ext:migrate --ext-instance firestore-bigquery-export-abcd --project <project-id>

Если вы знаете, на какой пакет хотите перейти, особенно если это не официальный пакет замены, указанный Google, укажите его с помощью флага --package:

firebase ext:migrate --ext-instance firestore-bigquery-export-abcd --package @firebase-function-kits/firestore-bigquery-export --project <project-id>

Как проверить развертывание набора функций

Чтобы убедиться, что firebase deploy набора прошло без ошибок, проверьте журналы развертывания и посмотрите, были ли активированы какие-либо перехватчики жизненного цикла. Популярные расширения, такие как Stream Cloud Firestore to BigQuery, используют хуки жизненного цикла. Ниже приведен пример того, как выглядит хук жизненного цикла при активации.

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

Эти сообщения в журнале подтверждают следующее:

• Обнаружен и выполнен хук жизненного цикла.
• Задача была поставлена в очередь задач, связанную с хуком жизненного цикла.
• Чтобы вы могли убедиться, что задача выполнена без ошибок, мы предоставили ссылку на Cloud Logging.

Перейдите по ссылке на журналы в консоль Google Cloud и убедитесь, что в журналах нет ошибок и событие очереди задач было успешно обработано. Если событие жизненного цикла не выполнено, вы можете запустить его повторно с помощью следующей команды:

firebase functions:lifecycle:run <hook-name> <codebase>

Если вы развертываете экземпляр набора функций впервые, выполните следующую команду:

firebase functions:lifecycle:run afterFirstDeploy <kit-instance-id>

Если во время проверки вы решите остановить или отменить перенос, удалите набор, следуя инструкциям в разделе Как удалить расширение.

Убедившись, что первоначальное развертывание набора функций завершено успешно, необходимо проверить, действительно ли функции работают должным образом. Поскольку расширение продолжает работать, вам нужно убедиться, что вы проверяете не только то, что одно из двух расширений работает, поскольку расширение работало и будет работать.

Если обработка не изменилась и вы не видите дублирующихся результатов от расширения и набора, лучше всего напрямую проверить журналы набора после активации его функций.

Пример. Поток Cloud Firestore в BigQuery

При использовании расширения Stream Cloud Firestore to BigQuery записи в таблицу Raw Changelog (*_raw_changelog) и таблицу последнего представления (*_raw_latest) будут дедуплицироваться, если одно и то же событие передается в набор и расширение. Поэтому вы не можете использовать наличие каких-либо строк или повторяющихся строк в BigQuery для проверки работы набора.

Вы можете посмотреть журналы функций вскоре после записи в коллекцию Firestore с помощью firebase functions:logs и найти запись в журнале, которая указывает, что запись успешно обработана. Для этого набора с идентификатором экземпляра по умолчанию firestore-bigquery-export это будет выглядеть так:

2026-09-25T19:52:46.328612Z I kit-firestore-bigquery-export-fsexportbigquery: Started execution of extension
2026-09-25T19:52:46.328644Z I kit-firestore-bigquery-export-fsexportbigquery: {"message":"Firestore event received by onDocumentWritten trigger","document_name":"projects/extensions-eventarc-testing/databases/(default)/documents/exported-messages/cmGP6XLyksqGdw2OgTOq","operation":0,"event_id":"9f59a2a4-1a5e-4c41-a32d-561e3c734502"}
2026-09-25T19:52:46.616064Z I kit-firestore-bigquery-export-fsexportbigquery: Completed execution of extension
2026-09-2

Если журналов много, вы можете отфильтровать их по определенной функции набора, используя следующую команду:

firebase functions:log --only <function name>

Чтобы найти названия функций для экземпляра набора, используйте следующую команду:

firebase functions:list | grep kit-<kit instance id>

В этом примере:

firebase functions:list | grep kit-firestore-bigquery-export
│ kit-firestore-bigquery-export-fsexportbigquery  │ v2      │ google.cloud.firestore.document.v1.written                    │
│ kit-firestore-bigquery-export-initBigQuerySync  │ v2      │ taskQueue                                                     │
│ kit-firestore-bigquery-export-setupBigQuerySync │ v2      │ taskQueue                                                     │
│ kit-firestore-bigquery-export-syncBigQuery      │ v2      │ taskQueue                                                     │

Ознакомьтесь с файлом README для набора функций

Для некоторых наборов может потребоваться дополнительная работа, помимо той, которая выполняется автоматически наборами функций. Ознакомьтесь с README для устанавливаемого комплекта и следуйте дополнительным инструкциям.

Как выполнить перенос с помощью CLI наборов функций

Прежде чем начать, определите и запишите идентификатор экземпляра расширения, которое вы хотите перенести в набор, и имя пакета npm его набора замены. Оба этих значения можно найти в выходных данных firebase ext:list. Пример использования ext:list приведен в разделе Как определить способ переноса.

1. Обновите экземпляр расширения до последней версии

Вы должны обновить расширение до последней версии, чтобы минимизировать разницу между экземпляром расширения и его заменой. Если расширение не обновить, между его экземпляром и заменяющим его набором могут возникнуть значительные критические изменения. Экспортированная конфигурация может не соответствовать ожидаемой из-за изменений параметров в разных версиях.

Обновите расширение одним из следующих способов в зависимости от того, где оно было установлено:

• В консоли Firebase
• В интерфейсе командной строки Firebase с помощью:
  • firebase ext:update <extension-instance-id> --project <project-id> firebase deploy --only extensions --project <project-id>

Если вы пропустите этот шаг, интерфейс командной строки предложит вам выполнить обновление при экспорте конфигурации, если у вас не установлена последняя версия расширения.

2. Проверьте и установите экземпляр набора функций для замены

Вы можете установить набор функций, используя следующую команду CLI:

firebase functions:kits:install --template migration --no-configure --package <npm-package-name> --project <project-id>

Когда вы будете выбирать идентификатор экземпляра для своего набора во время установки, обязательно запишите его, чтобы использовать позже в инструкциях по переносу.

После установки набора в проекте Firebase создается новый каталог, например function-kits/<kit-name>/source, который содержит пакет npm с набором, заменяющим ваше расширение, и базовый файл index.ts, который экспортирует эти функции для развертывания Firebase и настройки пользовательской конфигурации.

Ознакомьтесь с файлом README для набора и следуйте инструкциям в нем.

Если в одном проекте у вас несколько экземпляров набора, вы можете повторить эту команду, чтобы создать новые экземпляры того же набора. Вы также можете развернуть один экземпляр набора в двух разных проектах Firebase с разными конфигурациями (например, в тестовом и рабочем проектах). Подробнее о расширенных настройках переноса…

Пример:

firebase functions:kits:install --template migration --no-configure --package @firebase-function-kits/firestore-bigquery-export --project my-project

3. Настройте экземпляр набора функций так же, как расширение.

Вам нужно настроить этот экземпляр набора так же, как и расширение, которое он заменяет. Вы можете экспортировать конфигурацию экземпляра расширения в файл .env, в котором хранятся данные конфигурации параметров, переменных среды и секретных ссылок для всех Cloud Functions, включая наборы. Чтобы экспортировать его непосредственно в файл конфигурации набора, выполните следующую команду:

firebase ext:export --mode functions --instance <extension-instance-id> --kit-instance <kit-instance-id> --project <project-id>

В конце этого шага информация о конфигурации этого экземпляра сохраняется в файле .env, относящемся к проекту, в каталоге конфигурации экземпляра, например: function-kits/<kit-name>/config-<instance-id>/.env.<project-id>

4. Развертывание и проверка замены комплекта

Теперь, когда набор установлен и доступен в виде набора функций, вы можете развернуть замену набора. Наборы функций работают как стандартные функции, где каждый экземпляр набора действует как отдельная база кода для организации ваших функций. Вы можете развернуть все функции или только определенный экземпляр набора. При переносе одного экземпляра расширения разверните только этот экземпляр набора.

Если в вашем наборе используются новые параметры, которых не было в экземпляре расширения, из которого вы выполнили миграцию, CLI Firebase запросит их в начале процесса развертывания. В нашем примере с обновленным расширением firestore-bigquery-export этого не произойдет, но многие наборы запрашивают новый параметр для любого источника триггера события, используемого набором. В рамках этого перехода обновленные наборы используют функции второго поколения, тогда как расширения ранее использовали функции первого поколения. В функциях второго поколения функции расположены рядом с источниками событий и добавлены в качестве дополнительного параметра. Если в будущих обновлениях будут добавлены новые параметры, CLI предложит вам указать их при следующем развертывании.

Пример:

firebase deploy --only functions:firestore-bigquery-export --project my-project

Выходные данные:

=== 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!

Чтобы убедиться, что firebase deploy набора прошло без ошибок, проверьте журналы развертывания и посмотрите, были ли активированы какие-либо хуки жизненного цикла. Популярные расширения, такие как Stream Cloud Firestore to BigQuery, используют хуки жизненного цикла. Ниже приведен пример того, как выглядит хук жизненного цикла при активации.

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

Эти сообщения в журнале подтверждают следующее:

• Обнаружен и выполнен хук жизненного цикла.
• Задача была поставлена в очередь задач, связанную с хуком жизненного цикла.
• Чтобы вы могли убедиться, что задача выполнена без ошибок, мы предоставили ссылку на Cloud Logging.

Перейдите по ссылке на журналы в консоль Google Cloud и убедитесь, что в журналах нет ошибок и событие очереди задач было успешно обработано. Если событие жизненного цикла не выполнено, вы можете запустить его повторно с помощью следующей команды:

firebase functions:lifecycle:run <hook-name> <codebase>

Если вы развертываете экземпляр набора функций впервые, выполните следующую команду:

firebase functions:lifecycle:run afterFirstDeploy <kit-instance-id>

Если во время проверки вы решите остановить или отменить перенос, удалите набор, следуя инструкциям в разделе Как удалить расширение.

Убедившись, что первоначальное развертывание набора функций завершено успешно, необходимо проверить, действительно ли функции работают должным образом. Поскольку расширение продолжает работать, вам нужно убедиться, что вы проверяете не только то, что одно из двух расширений работает, поскольку расширение работало и будет работать.

Если обработка не изменилась и вы не видите дублирующихся результатов от расширения и набора, лучше всего напрямую проверить журналы набора после активации его функций.

Пример. Поток Cloud Firestore в BigQuery

При использовании расширения Stream Cloud Firestore to BigQuery записи в таблицу Raw Changelog (*_raw_changelog) и таблицу последнего представления (*_raw_latest) будут дедуплицироваться, если одно и то же событие передается в набор и расширение. Поэтому вы не можете использовать наличие каких-либо строк или повторяющихся строк в BigQuery для проверки работы набора.

Вы можете посмотреть журналы функций вскоре после записи в коллекцию Firestore с помощью firebase functions:logs и найти запись в журнале, которая указывает, что запись успешно обработана. Для этого набора с идентификатором экземпляра по умолчанию firestore-bigquery-export это будет выглядеть так:

2026-09-25T19:52:46.328612Z I kit-firestore-bigquery-export-fsexportbigquery: Started execution of extension
2026-09-25T19:52:46.328644Z I kit-firestore-bigquery-export-fsexportbigquery: {"message":"Firestore event received by onDocumentWritten trigger","document_name":"projects/extensions-eventarc-testing/databases/(default)/documents/exported-messages/cmGP6XLyksqGdw2OgTOq","operation":0,"event_id":"9f59a2a4-1a5e-4c41-a32d-561e3c734502"}
2026-09-25T19:52:46.616064Z I kit-firestore-bigquery-export-fsexportbigquery: Completed execution of extension
2026-09-2

Если журналов много, вы можете отфильтровать их по определенной функции набора, используя следующую команду:

firebase functions:log --only <function name>

Чтобы найти названия функций для экземпляра набора, используйте следующую команду:

firebase functions:list | grep kit-<kit instance id>

В этом примере:

firebase functions:list | grep kit-firestore-bigquery-export
│ kit-firestore-bigquery-export-fsexportbigquery  │ v2      │ google.cloud.firestore.document.v1.written                    │
│ kit-firestore-bigquery-export-initBigQuerySync  │ v2      │ taskQueue                                                     │
│ kit-firestore-bigquery-export-setupBigQuerySync │ v2      │ taskQueue                                                     │
│ kit-firestore-bigquery-export-syncBigQuery      │ v2      │ taskQueue                                                     │

5. Удалите расширение

После того как вы проверите развернутый набор функций, вы можете удалить расширение, чтобы не дублировать его поведение один раз для набора и один раз для расширения. Вы можете удалить все расширения из CLI Firebase независимо от того, как вы их установили, если передадите флаг --immediate:

firebase ext:uninstall <extension-instance-id> --project <project-id> --immediate

Пример:

firebase ext:uninstall firestore-bigquery-export --project my-project --immediate

Выходные данные:

i  extensions: uninstalling firestore-bigquery-export...
i  extensions: deleting extension instance resources in project my-project...
✔  extensions: successfully uninstalled firestore-bigquery-export

Расширенный перенос

У вас могут быть расширения в нескольких проектах Firebase, которыми вы хотите управлять с помощью одной базы кода. Например, если вы развертываете одну и ту же инфраструктуру в средах testing и production, в каждой из которых есть экземпляр documents Cloud Firestore, экспортируемый в BigQuery, у вас может быть установлено два экземпляра расширения firestore-bigquery-export:

• export-documents-testing
• export-documents-production

Если вы перенесли эти два экземпляра расширения в два экземпляра набора функций в одной базе кода при работе с CLI Firebase и развернули их с помощью firebase deploy --project testing и firebase deploy --project production, то при каждом развертывании будут создаваться два экземпляра в средах testing и production.

Вместо этого замените два экземпляра расширения одним экземпляром набора функций firestore-bigquery-export, развернутым в нескольких проектах, каждый из которых имеет собственную конфигурацию. Каталог конфигурации для экземпляра должен выглядеть следующим образом:

• config-export-documents/
  • .env.testing
  • .env.production

При каждом развертывании в testing и production создается один экземпляр набора с соответствующей конфигурацией. Существующие команды CLI создают эту настройку, если вы передаете флаг --project в каждом вызове ext:migrate или functions:kits:install.

Пример:

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

Теперь у вас есть один экземпляр набора, настроенный для развертывания в проектах testing и production с соответствующими конфигурациями. Если вы создадите экземпляр в проекте testing и выполните команду functions:kits:install для того же пакета в проекте production, вам будет предложено использовать экземпляр, настроенный для testing, или установить второй экземпляр.