Перенесите расширения Firebase на самостоятельно созданный набор функций.

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

We recommend using an account that has installed extensions and deployed functions before, since most of these permissions will already have been granted. If your migrating account needs more roles, follow the Google Cloud IAM instructions to add them.

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

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

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

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

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

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

Before you start converting an extension to a local function kit, make sure that the extension source code is inside your Firebase project. To do this, clone the extension repository from GitHub, create a directory inside your Firebase project root, and copy the extension's functions/ folder and extension.yaml into it:

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

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

In a local function kit, the Firebase CLI doesn't generate an index.ts file to set up the package and configure it to use migrated system parameters. To use function region and advanced parameters that were configured for your extension, set up your index.ts file to read the format exported by firebase ext:export --mode functions into an environment variable file.

Specifically, in the top-level index.ts file that exports your functions, define a parameter for FUNCTION_DEFAULT_REGION and call setGlobalOptions with environment variables of the form EXT_MIGRATED_SYSTEM_<GLOBAL_OPTION> , similar to the index-kit-migration.ts template used by the 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";

Проверьте свой комплект оборудования перед миграцией.

You now have a local function kit that, when deployed, behaves identically to a new installation of your extension. The next step is to verify and fix any issues accidentally introduced along the way before migrating your production extension instances to it.

First, add your fork as a local kit, configure it, and deploy it to a test project. Local function kits must live inside your Firebase project, so if the cloned extension repository is outside your Firebase project, move it inside the project directory. Then run the following kit installation command to install it as a local kit:

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

This command guides you through picking a kit ID, an instance ID, and a configuration for your first test instance. It then modifies your firebase.json file to register a local kit pointing to your forked directory, with configurations for each instance stored in a .env file at 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 выполните запрос к исходной таблице changelog. Она должна содержать одну строку, регистрирующую создание документа:

    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 .
  • Your code runs in the Firebase Local Emulator Suite as standard functions. You can set parameter values to use in the emulator with .env.local . You can also unit test your code using the firebase-functions-test SDK as described in Unit testing of Cloud Functions .
  • Provisioning is no longer driven by the Extensions runtime. If the changelog table is missing after deploy, rerun the setup task manually: firebase functions:lifecycle:run afterFirstDeploy <kit-instance-id> . The task is idempotent, so rerunning it reconciles the dataset, table, and views.
  • Значения параметров берутся из .env , а не из формы установки, поэтому повторный запуск команды firebase deploy становится неинтерактивным после завершения обработки файла .env .

(Необязательно) Очистка после тестирования

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

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

This deletes all cloud resources created by deploying the kit and removes its instance configuration. If you only have one instance of the kit, this also removes the kit entry from firebase.json . It does not delete your local source code directory. When you install the kit for your production migration, you can pick a kit ID again.

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

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

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

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

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

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

Once you've verified that the initial deployment of your function kit has completed successfully, you need to validate that the functionality of the kit is actually working as expected. Because the extension itself is still running, you need to be careful that what you're checking is not just that one of the two has worked, since the extension has been and will continue to work.

In the case where the processing isn't changed and you don't see duplicate results from the extension and kit, the best option is to directly examine the logs for the kit after triggering the kit's functionality.

Пример работы: потоковая передача данных из Cloud Firestore в BigQuery

With the Stream Cloud Firestore to BigQuery Extension writes to both the Raw Changelog Table ( *_raw_changelog ) and latest view table ( *_raw_latest ) will deduplicate if the same event is delivered to the kit and the extension. So you can't use the presence of any rows or duplicate rows in BigQuery to validate the kit is working.

You can view functions logs shortly after writing to your Firestore collection using firebase functions:logs and look for a log entry that indicates it successfully processed a write. For this kit with the default instance ID of firestore-bigquery-export would look like: 

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. Удалите расширение.

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