Перенос расширений Firebase в функциональные наборы.

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

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

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

Определите свой путь миграции.

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

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

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

    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 Переход на самостоятельно созданный набор функций

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

Проверьте наличие известных ограничений миграции.

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

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

Прежде чем начать

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

Необходимые права доступа и роли учетной записи

В зависимости от того, что необходимо создать и настроить с помощью Firebase CLI во время миграции, учетная запись, используемая для аутентификации в 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)

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

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

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

  • (Рекомендуется) Выполните миграцию с помощью команды CLI ext:migrate . Эта команда развернет заменяющее вас расширение из набора функций, а затем удалит заменяемое им расширение.
  • Миграцию можно выполнить с помощью команд 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>

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

Ознакомьтесь с файлом 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>

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

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

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

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. Развернуть и проверить замену комплекта.

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

Если ваш комплект использует какие-либо новые параметры, которых не было в экземпляре расширения, с которого вы перешли, Firebase CLI запросит их в начале процесса развертывания. В этом примере с обновленным расширением 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>

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

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

После проверки развернутого набора функций вы можете удалить расширение, чтобы избежать дублирования его поведения для набора функций и для расширения. Вы можете удалить все расширения из Firebase CLI независимо от способа их установки, если передадите флаг --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 средах, в каждой из которых есть экземпляр Cloud Firestore для documents , экспортируемый в BigQuery , у вас может быть установлено два экземпляра расширения firestore-bigquery-export :

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

Если вы перенесли эти два экземпляра расширений в два экземпляра функционального набора в рамках одной кодовой базы при работе с Firebase CLI и развернули их с помощью 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 , либо установить второй экземпляр.