将 Firebase Extensions 迁移到函数套件

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

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

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

警告： 本迁移指南中的步骤会提取您现有的扩展程序配置，以配置完全相同的替换功能套件。2027 年 3 月 31 日之后，您将无法再执行此操作。我们强烈建议您在 2027 年 3 月 31 日之前完成迁移。如果您不打算在此之前进行迁移，可以按照将函数套件实例配置为与扩展程序完全相同中的说明，提前导出扩展程序配置。

确定迁移路径

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 上迁移到函数套件部分中的说明进行迁移。

如果您找不到已发布的替代扩展程序，可以派生扩展程序代码并创建自己的替代扩展程序，因为所有扩展程序都是开源的。为此，请按照迁移到自行创建的函数套件指南操作。

注意： 其他开发者可以创建非官方的功能套件替代方案。Google 不会验证或宣传非官方替代方案，但如果您找到并自行验证了某个替代方案，可以使用这些迁移指南迁移到该方案。

选择迁移路径：

迁移到 npm 上的函数套件 迁移到自行创建的函数套件

迁移到 npm 上的函数套件

检查已知的迁移限制

在开始迁移扩展程序实例之前，请检查您的设置是否使用了以下任何需要变通方法或在功能套件中尚不受支持的功能：

• 自定义 Docker 代码库和 KMS 密钥需要手动解决 Cloud Functions for Firebase 不支持用于配置自定义 Docker 代码库或客户管理的加密密钥 (KMS 密钥) 的替换系统参数。如果您的扩展程序配置了这两个参数中的任一参数，请参阅常见问题解答中的解决方法。

准备工作

您需要设置 Firebase CLI 并初始化 Firebase 项目。使用 CLI 时，请确保您使用的是 firebase-tools 版本 >= 15.32.0，该版本包含新的迁移和函数套件命令。

注意： 本指南中的所有 CLI 命令都包含 --project <project-id> 标志，用于明确指定目标项目。如果您在 .firebaserc 中配置的默认项目中工作，则可以省略 --project 标志。

所需的账号权限和角色

根据 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>

警告： 如果您使用 --force 调用 ext:migrate，则系统会在部署替换项后立即删除扩展程序，而不会进行任何验证。即使迁移成功，也可能会出现短暂的停机时间，因为 Eventarc 需要几分钟时间才能完全预配，并且套件替换需要几分钟时间才能处理任何事件触发型扩展程序的事件。

验证功能套件部署

如需验证套件的 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 进行迁移

在开始之前，请确定并记下您要迁移到套件的扩展程序的实例 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，并按照其中列出的所有其他说明操作。

如果您在同一项目中有多个套件实例，可以重复执行此命令来创建同一套件的新实例。您还可以将单个套件实例部署到两个不同的 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 扩展程序的这个示例中，这种情况并不常见，但许多套件会针对套件使用的任何事件触发源提示输入新参数。在此迁移过程中，更新后的套件使用第 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!

注意： Eventarc 可能需要几分钟才能完成完全预配并开始接受事件。如果您的代码是事件触发型代码，我们建议您等待几分钟后再验证代码。如果您在未进行验证的情况下立即删除扩展程序，则在完成配置之前，您可能会遇到短暂的停机时间。

如需验证套件的 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 环境（每个环境都有一个导出到 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 配置的实例，还是安装第二个实例。