将 Firebase Extensions 迁移到函数套件

本指南介绍了如何将扩展程序从已弃用的 Firebase Extensions 环境迁移到函数套件，以便您在自己的 Cloud Functions for Firebase（第 2 代）代码库中安装和部署。

Firebase Extensions 管理了创建、更新和移除扩展程序的各个方面。函数套件将扩展程序的功能打包为典型的第 2 代 Cloud Functions for Firebase。由于函数套件是标准 Cloud Functions，因此您可以使用 Firebase 项目中的 Firebase CLI 创建、更新、删除和排查这些套件。本指南可帮助您做好准备，以便现在管理函数，并在更新发布后及时采用。

在本指南中，Stream Cloud Firestore to BigQuery 扩展程序 (firestore-bigquery-export) 用作示例，向您展示迁移的每个步骤的命令和命令输出。

确定迁移路径

Firebase 鼓励所有 Firebase Extensions 发布商为其扩展程序创建替代方案，并将其作为函数套件发布在 npm 上。您可以通过以下几种不同的方式检查是否有可用的函数套件来替代您的扩展程序：

  • 前往项目的 Firebase 控制台的“Extensions”（扩展程序）页面。您安装的每个扩展程序都会指明是否有可用的函数套件替代项。

  • 在终端中，在 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 上的函数套件 迁移到自行创建的函数套件

迁移到 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（如果使用 Secret）
  • roles/serviceusage.serviceUsageAdmin（如果您需要启用新的 API）

我们建议您使用之前安装过扩展程序并部署过函数的账号，因为这些账号已经拥有大部分所需权限。如果您的迁移账号需要更多角色，请按照 Google Cloud IAM 说明进行添加。

选择 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_latest) 的数据将进行去重。因此，您无法通过 BigQuery 中是否存在任何行或重复行来验证该套件是否正常运行。

使用 firebase functions:logs 写入 Firestore 集合后不久，您就可以查看函数日志，并查找指示已成功处理写入的日志条目。对于此套件，默认实例 ID 为 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

如果您有大量日志，可以使用以下命令过滤到特定的 Kit 函数：

firebase functions:log --only <function name>

如需查找 Kit 实例的特定函数名称，您可以使用以下命令：

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 进行迁移

在开始之前，请确定并记下要迁移到套件的扩展程序的实例 ID，以及其替换套件的 npm 软件包名称。您可以使用 firebase ext:list 的输出来找到这两者。如需查看使用 ext:list 的示例，请参阅确定迁移路径。

1. 将扩展程序实例升级到最新版本

您必须将扩展程序更新到最新版本，以尽可能减少扩展程序实例与其替换套件之间的差异。如果您的扩展程序未升级，则扩展程序实例与其套件替代项之间可能会发生重大破坏性更改。由于不同版本之间的参数变化，导出的配置可能与套件预期的配置不一致。

根据扩展程序的安装位置，使用以下任一选项更新扩展程序：

  • 在 Firebase 控制台中
  • 通过 Firebase CLI 使用：
    • firebase ext:update <extension-instance-id> --project <project-id> firebase deploy --only extensions --project <project-id>

如果您跳过此步骤，并且您的扩展程序不是最新版本，则 CLI 会在导出配置时提示您升级。

2. 查看并安装替代函数套件实例

您可以使用以下 CLI 命令安装函数套件：

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

在安装期间为套件选择实例 ID 时，请务必将其记下，以便稍后在迁移说明中使用。

安装该套件后，系统会在您的 Firebase 项目中创建一个新目录，其位置类似于 function-kits/<kit-name>/source，其中包含一个 npm 软件包，该软件包包含替换扩展程序的套件，以及一个基本的 index.ts 文件，该文件会导出这些函数，以便 Firebase 部署和设置自定义配置。

查看该套件的 README，并按照其中列出的任何其他说明进行操作。

如果您在同一项目中有该套件的多个实例，则可以重复此命令来创建同一套件的新实例。您还可以将单个 Kit 实例部署到两个具有不同配置的不同 Firebase 项目（例如，预演项目和生产项目）。如需详细了解这些高级设置，请参阅高级迁移。

示例：

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

3. 以与扩展程序相同的方式配置函数套件实例

您需要使用与要替换的扩展程序相同的配置来自定义此套件实例。您可以将扩展程序实例配置导出到 .env 文件中，该文件会存储所有 Cloud Functions（包括套件）的参数、环境变量和 Secret 引用配置数据。如需将其直接导出到套件的配置文件中，请运行以下命令：

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. 部署并验证套件更换

现在，套件已安装并可作为一组函数使用，您可以部署套件替代项。函数套件的工作方式与标准函数类似，每个套件实例都充当一个单独的代码库，用于整理函数。您可以选择部署所有函数，也可以仅部署特定 Kit 实例。迁移单个扩展程序实例时，仅部署该 Kit 实例。

如果您的套件使用了您迁移的扩展程序实例中不存在的任何新参数，Firebase CLI 会在部署过程开始时提示您输入这些参数。在本示例中，由于使用的是最新版 firestore-bigquery-export 扩展程序，因此不会出现这种情况，但许多套件都会针对套件使用的任何事件触发器来源提示输入新参数。在此次迁移中，更新后的套件会使用第 2 代函数，而扩展程序之前使用的是第 1 代函数。在第 2 代中，函数位于其事件源附近，并作为附加参数添加。在未来的更新中，如果添加了新参数，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_latest) 的数据将进行去重。因此，您无法通过 BigQuery 中是否存在任何行或重复行来验证该套件是否正常运行。

使用 firebase functions:logs 写入 Firestore 集合后不久，您就可以查看函数日志，并查找指示已成功处理写入的日志条目。对于此套件，默认实例 ID 为 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

如果您有大量日志，可以使用以下命令过滤到特定的 Kit 函数：

firebase functions:log --only <function name>

如需查找 Kit 实例的特定函数名称，您可以使用以下命令：

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. 卸载扩展程序

验证已部署的函数套件后，您可以卸载扩展程序，以免套件和扩展程序重复执行相同的行为。如果您传递 --immediate 标志，则无论您如何安装扩展程序，都可以从 Firebase CLI 卸载所有扩展程序：

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 环境，每个环境都有一个您导出到 BigQuery 的 documents Cloud Firestore 实例，则您可能安装了两个 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 都会创建一个具有相应配置的套件实例。只要您在每次调用 ext:migrate 或 functions:kits:install 时传递 --project 标志，现有的 CLI 命令就会创建此设置。

示例：

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 项目中创建实例，并针对 production 项目中的同一软件包运行 functions:kits:install 命令，系统会提示您选择重复使用为 testing 配置的实例或安装第二个实例。