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

Выберите способ переноса: Переход на наборы функций в 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.

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

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

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

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

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

Как создать форк расширения в локальный набор функций

Прежде чем начать преобразование расширения в набор локальных функций, убедитесь, что исходный код расширения находится в вашем проекте Firebase. Для этого клонируйте хранилище расширения из GitHub, создайте каталог в корневом каталоге проекта Firebase и скопируйте в него папку functions/ и файл extension.yaml расширения:

mkdir -p path/to/kit
cp -r /path/to/extension-source/functions/* path/to/kit/
cp /path/to/extension-source/extension.yaml path/to/kit/.

Выполните шаги 1–8 из руководства по переносу для издателей, чтобы перенести исходный код расширения в функцию второго поколения. Затем выполните следующие действия.

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

В локальном наборе функций интерфейс командной строки Firebase не генерирует файл index.ts для настройки пакета и его конфигурации, чтобы использовать перенесенные системные параметры. Чтобы использовать регион функции и расширенные параметры, настроенные для расширения, задайте в файле index.ts чтение формата, экспортированного firebase ext:export --mode functions, в файл переменной среды.

В файле index.ts верхнего уровня, который экспортирует ваши функции, определите параметр для FUNCTION_DEFAULT_REGION и вызовите setGlobalOptions с переменными среды в форме EXT_MIGRATED_SYSTEM_<GLOBAL_OPTION>, аналогично шаблону index-kit-migration.ts, используемому CLI:

import { setGlobalOptions } from "firebase-functions";
import { MemoryOption, VpcEgressSetting, IngressSetting } from "firebase-functions/v2/options";
import { defineString } from "firebase-functions/params";

export const regionParam = defineString("FUNCTION_DEFAULT_REGION", {
  input: { text: { nonEmpty: true } },
  description: "Global default region where functions should be deployed. Can be overridden per-function.",
});

setGlobalOptions({
  region: regionParam,
  memory: (process.env.EXT_MIGRATED_SYSTEM_MEMORY as MemoryOption) ?? undefined,
  timeoutSeconds: process.env.EXT_MIGRATED_SYSTEM_TIMEOUTSECONDS
    ? Number(process.env.EXT_MIGRATED_SYSTEM_TIMEOUTSECONDS)
    : undefined,
  vpcConnectorEgressSettings:
    process.env.EXT_MIGRATED_SYSTEM_VPCCONNECTOREGRESSSETTINGS &&
    process.env.EXT_MIGRATED_SYSTEM_VPCCONNECTOREGRESSSETTINGS !== "VPC_CONNECTOR_EGRESS_SETTINGS_UNSPECIFIED"
      ? (process.env.EXT_MIGRATED_SYSTEM_VPCCONNECTOREGRESSSETTINGS as VpcEgressSetting)
      : undefined,
  vpcConnector: process.env.EXT_MIGRATED_SYSTEM_VPCCONNECTOR ?? undefined,
  maxInstances: process.env.EXT_MIGRATED_SYSTEM_MAXINSTANCES
    ? Number(process.env.EXT_MIGRATED_SYSTEM_MAXINSTANCES)
    : undefined,
  minInstances: process.env.EXT_MIGRATED_SYSTEM_MININSTANCES
    ? Number(process.env.EXT_MIGRATED_SYSTEM_MININSTANCES)
    : undefined,
  ingressSettings: (process.env.EXT_MIGRATED_SYSTEM_INGRESSSETTINGS as IngressSetting) ?? undefined,
  // Parses a comma-separated string of key:value pairs into a key-value object
  // (for example, "key1:value1,key2:value2" -> { key1: "value1", key2: "value2" }).
  labels: process.env.EXT_MIGRATED_SYSTEM_LABELS
    ? process.env.EXT_MIGRATED_SYSTEM_LABELS.split(",").reduce<Record<string, string> | undefined>(
        (acc, curr) => {
          const [key, value] = curr.split(":");
          const trimmedKey = key?.trim();
          const trimmedValue = value?.trim();
          if (!trimmedKey || !trimmedValue) {
            return acc;
          }
          acc = acc ?? {};
          acc[trimmedKey] = trimmedValue;
          return acc;
        },
        undefined,
      )
    : undefined,
});

// Re-export all functions so the Firebase CLI can deploy them
export * from "./your-functions";

Протестируйте набор перед переносом

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

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

firebase functions:kits:install --directory <path-to-your-fork> --project <test-project-id>

Эта команда поможет вам выбрать идентификатор набора, идентификатор экземпляра и конфигурацию для первого тестового экземпляра. Затем он изменяет файл firebase.json, чтобы зарегистрировать локальный набор, указывающий на ваш разветвленный каталог, с конфигурациями для каждого экземпляра, хранящимися в файле .env в function-kits/<kit-id>/config-<instance-id>.

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

firebase deploy --only functions:<kit-instance-id> --project <test-project-id>

Пример. Поток Cloud Firestore в BigQuery (firestore-bigquery-export)

Проверьте сквозную синхронизацию между Cloud Firestore и BigQuery:

  1. На странице Cloud Firestore в консоли Firebase создайте коллекцию, которую вы указали в качестве COLLECTION_PATH (users), если она ещё не существует.
  2. Создайте документ с названием bigquery-mirror-test, содержащий любые поля с любыми значениями.

  3. На странице BigQuery в консоли Google Cloud выполните запрос к таблице необработанного журнала изменений. В нем должна быть одна строка, в которой регистрируется создание документа:

    SELECT * FROM `PROJECT_ID.analytics.users_raw_changelog`

  4. Запросите последнее представление, которое должно вернуть последнее событие изменения для единственного существующего документа (bigquery-mirror-test):

    SELECT * FROM `PROJECT_ID.analytics.users_raw_latest`

  5. Удалить документ "bigquery-mirror-test" в папке "Cloud Firestore". Оно исчезнет из представления последних изменений, а в таблицу журнала изменений будет добавлено событие DELETE.

    Вы можете посмотреть полную историю отдельного документа с помощью:

    SELECT *
   FROM `PROJECT_ID.analytics.users_raw_changelog`
   WHERE document_name = "bigquery-mirror-test"
   ORDER BY timestamp ASC

Отличия от тестирования расширения:

  • Триггер развертывается как kit-<kit-instance-id>-fsexportbigquery, а не ext-<instanceId>-fsexportbigquery. Найдите это название на панели управления и в журналах Cloud Functions.
  • Ваш код выполняется в Firebase Local Emulator Suite как стандартные функции. Вы можете задать значения параметров для использования в эмуляторе с помощью .env.local. Вы также можете провести модульное тестирование кода с помощью SDK firebase-functions-test, как описано в статье Модульное тестирование Cloud Functions.
  • Инициализация больше не управляется средой выполнения расширений. Если после развертывания таблица changelog отсутствует, повторно запустите задачу настройки вручную: firebase functions:lifecycle:run afterFirstDeploy <kit-instance-id>. Задача идемпотентна, поэтому повторный запуск согласовывает набор данных, таблицу и представления.
  • Значения параметров берутся из файла .env, а не из формы установки, поэтому повторные запуски firebase deploy после завершения .env не являются интерактивными.

Как удалить тестовые данные (необязательно)

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

firebase functions:kits:uninstall --instance <kit-instance-id> --project <test-project-id>

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

Переход с расширений на локальный набор инструментов

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

1. Установите экземпляр набора функций замены

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

firebase functions:kits:install --no-configure --directory <path-to-your-fork> --project <project-id>

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

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

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

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

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

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

После того как вы проверите развернутый набор функций, вы можете удалить расширение, чтобы не дублировать его поведение один раз для набора и один раз для расширения. Вы можете удалить все расширения из 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, или установить второй экземпляр.