迁移后的最佳实践

从 Firebase Extensions 迁移到函数套件后，您可以在 Firebase 项目中将套件实例作为标准的第 2 代 Cloud Functions 进行管理。本指南介绍了如何直接从 npm 安装新功能套件（无需迁移现有扩展程序）、更新套件参数和全局选项、在发布者发布更新时升级 npm 软件包版本，以及在需要时回滚迁移。

使用 npm 软件包中的函数套件，无需迁移

如果您不是从扩展程序迁移，则使用函数套件包含两个部分：

安装套件

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

firebase functions:kits:install --package <npm-package-name>

示例：

firebase functions:kits:install --package @firebase-function-kits/firestore-bigquery-export --project my-project

✔ What would you like to name this kit? firestore-bigquery-export
✔ What would you like to name this instance? firestore-bigquery-export
i  function-kits/firestore-bigquery-export/source/package.json is unchanged
i  function-kits/firestore-bigquery-export/source/tsconfig.json is unchanged
i  function-kits/firestore-bigquery-export/source/.gitignore is unchanged
i  functions: Running npm install @firebase-function-kits/firestore-bigquery-export@next --save-prefix=^...
i  functions: Building TypeScript source...
✔  Wrote configuration info to firebase.json

i  functions: Loaded environment variables from function-kits/firestore-bigquery-export/config-firestore-bigquery-export/.env.my-project
Prompting for parameters for codebase firestore-bigquery-export:
✔ Enter a string value for FUNCTION_DEFAULT_REGION:
(Global default region where functions should be deployed. Can be overridden per-function.) us-east1

✔ Enter a string value for BigQuery Project ID:
(Override the default project for BigQuery instance. This can allow updates to be directed to a BigQuery
instance on another GCP project.) my-bigquery-project

✔ Enter a string value for Firestore Instance ID:
(The Firestore database to use. Use "(default)" for the default database. You can view your available
Firestore databases at https://console.cloud.google.com/firestore/databases.) eu-testing

# Omitting many more parameters for brevity

✔  Wrote configuration info to firebase.json
✔  functions: Function kit firestore-bigquery-export successfully installed.

i  functions: At the first deploy, the following functions will be created in your project:
- kit-firestore-bigquery-export-fsexportbigquery
- kit-firestore-bigquery-export-initBigQuerySync
- kit-firestore-bigquery-export-setupBigQuerySync
i  functions: At the first deploy, the following Task Queues will be created in your project:
- kit-firestore-bigquery-export-initBigQuerySync
- kit-firestore-bigquery-export-setupBigQuerySync
i  functions: At the first deploy, the following APIs will be enabled in your project:
- bigquery.googleapis.com
- cloudtasks.googleapis.com
i  functions: At the first deploy, the following roles will be granted to the kit service account:
- BigQuery Data Editor
- BigQuery User
- Cloud Datastore User
- Eventarc Event Receiver
- roles/run.invoker
⚠  functions: Please review the changes above. If you do not want them applied to your project, uninstall this kit before running firebase deploy.

更改默认全局选项

如需为套件实例配置全局选项，请修改位于 function-kits/<your-kit-id>/source/src/index.ts 的 index.ts 文件。

如果您希望默认值在所有套件实例之间共享，请直接在 index.ts 中设置。否则，请按照 index.ts 中记录的示例和说明，创建按实例设置的参数。

部署套件

如需部署函数套件，请运行以下命令：

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

示例：

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!

安装和部署该套件会执行以下操作：

  • 创建 function-kits/firestore-bigquery-export/source，其中包含 kit 源代码，包括一个基本的 index.ts 文件，该文件可导入和导出 kit 软件包，同时设置一个参数，让您可以为 kit 的每个实例选择不同的位置。
  • 创建 function-kits/firestore-bigquery-export/config-firestore-bigquery-export/.env.<project-id> 并使用为函数输入的配置数据填充该对象。如果未来的更新添加了新参数，系统会在下次部署时提示您。
  • 创建运行此套件所需的 Google Cloud 资源，包括具有特定 IAM 角色的服务账号、函数、Eventarc 触发器和 Cloud Tasks 队列。

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

卸载套件

如需移除套件及其所有实例，请运行以下命令：

firebase functions:kits:uninstall --kit <kit-id>

这会删除所有实例及其配置，并从磁盘中移除套件来源。

如需仅移除一个实例，请运行以下命令：

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

如果您只有一个套件实例，则此操作会卸载整个套件。

更新套件配置

在安装或首次部署期间，系统会提示您为媒体资源包配置所有参数（除非您从扩展程序迁移了配置）。这些参数存储在套件实例配置目录中的 .env 文件中。例如，如果您在项目 my-project 中有一个名为 firestore-bigquery-export 的套件实例，则 .env 文件位于 function-kits/firestore-bigquery-export/config-firestore-bigquery-export/.env.my-project。

如下所示：

DATASET_LOCATION=us
BIGQUERY_PROJECT_ID=my-project
DATABASE=eu-testing
DATABASE_REGION=eur3
COLLECTION_PATH=posts
WILDCARD_IDS=false
DATASET_ID=firestore_export
TABLE_ID=posts
TABLE_PARTITIONING=NONE
TIME_PARTITIONING_FIELD=
TIME_PARTITIONING_FIRESTORE_FIELD=
TIME_PARTITIONING_FIELD_TYPE=omit
CLUSTERING=
MAX_DISPATCHES_PER_SECOND=100
VIEW_TYPE=view
MAX_STALENESS=
REFRESH_INTERVAL_MINUTES=
BACKUP_COLLECTION=
TRANSFORM_FUNCTION=
USE_NEW_SNAPSHOT_QUERY_SYNTAX=no
EXCLUDE_OLD_DATA=no
KMS_KEY_NAME=
MAX_ENQUEUE_ATTEMPTS=3
LOG_LEVEL=info
FUNCTION_DEFAULT_REGION=us-west1

如果您知道要更改的配置值，可以直接在 .env 文件中修改。如果您希望使用安装和部署期间运行的交互式提示，请从 .env 文件中移除要更改的参数，然后重新部署套件实例。在部署期间，系统会提示您输入这些参数。

例如，如果您删除 COLLECTION_PATH=posts 行并进行部署，系统会在部署期间提示您输入该值：

i functions: Loaded environment variables from function-kits/firestore-bigquery-export/config-firestore-bigquery-export-d9cd/.env.ajp-testing
Prompting for parameters for codebase firestore-bigquery-export:

Collection path: What is the path of the collection that you would like to export? You may use {wildcard} notation to match a subcollection of all documents in a collection (for example: chatrooms/{chatid}/posts). Parent Firestore Document IDs from {wildcards} can be returned in path_params as a JSON formatted string.
? Enter a string value for Collection path: (posts)

维护和升级函数套件

发布者可能会随时更新其 npm 软件包，以修复 bug、添加功能、更新依赖项或解决安全漏洞。我们建议您及时了解这些版本，并安装更新，尤其是那些可解决安全漏洞的更新。

functions:kits:install 命令会创建一个代码库，该代码库会将套件安装为 npm 软件包，并为套件的每个实例导出其所有函数。如需升级套件，请更新软件包版本，然后重新部署套件的每个实例以应用更改。

确定套件是否有更新

前往 function-kits/<your-kit-id>/source 中套件的 source 目录。在此 source 目录下，运行以下命令以获取有关所有过时的 npm 软件包（包括函数套件和 Cloud Functions SDK）的报告：

npm outdated

如果您已使用某种工具来识别需要更新的依赖项（例如 GitHub 的 Dependabot），我们建议您将套件目录集成到该工作流中。

更新套装

如需将套件及其依赖项更新到最新的非破坏性版本（不包括可能包含破坏性更改的主要版本更新），请运行以下命令：

npm update --save

如果您只想更新函数套件软件包，而不更新其他软件包，请将软件包名称传递给 npm update：

npm update <package-name> --save

如需将软件包升级到最新的主要版本（可能会引入重大变更），请运行以下命令：

npm update --save <npm-package-name>@latest

查看软件包文档和版本说明，了解发生了哪些变化，以及是否需要在部署之前或之后采取任何额外步骤来防止重大更改。

部署更新后的实例

运行 npm update 只会更新本地源代码。如需更新云端正在运行的函数，请重新部署这些函数。您可以运行以下命令来重新部署项目中的所有函数，包括所有函数套件：

firebase deploy --only functions

撤消迁移

如需撤消迁移，请先重新安装扩展程序。您可以使用该套件的 .env 文件来查找安装期间所需的配置值。

部署扩展程序后，卸载套件实例（如果这是剩余的最后一个实例，则会卸载整个套件）：

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

保存扩展程序配置以供日后迁移

在 2027 年 3 月 31 日之后，您将无法提取现有的扩展程序配置。如果您无法在 2027 年 3 月 31 日之前完成迁移，我们强烈建议您保存扩展程序，以防您决定在此日期之后进行迁移。

  1. 获取扩展程序实例 ID 的列表：

    您可以使用 ext:list CLI 命令获取 Firebase 项目中所有扩展程序实例的列表：

    firebase ext:list --project <project-id>

    示例：

    firebase ext:list --project my-project

    » firebaselocal ext:list
i  extensions: ensuring required API firebaseextensions.googleapis.com is enabled...
i  extensions: list of extensions installed in ajp-testing:
┌────────────────────────────────────┬───────────┬────────────────────────────────┬────────┬─────────┬─────────────────────┬───────────────────────────────────────────────────┐
│ Extension                          │ Publisher │ Instance ID                    │ State  │ Version │ Your last update    │ Replacement Kit                                   │
├────────────────────────────────────┼───────────┼────────────────────────────────┼────────┼─────────┼─────────────────────┼───────────────────────────────────────────────────┤
│ firebase/firestore-bigquery-export │ firebase  │ firestore-bigquery-export-zbrp │ ACTIVE │ 0.3.3   │ 2026-09-06 22:31:04 │ @firebase-function-kits/firestore-bigquery-export │
├────────────────────────────────────┼───────────┼────────────────────────────────┼────────┼─────────┼─────────────────────┼───────────────────────────────────────────────────┤
│ firebase/firestore-bigquery-export │ firebase  │ firestore-bigquery-export      │ ACTIVE │ 0.3.2   │ 2026-06-03 17:41:24 │ @firebase-function-kits/firestore-bigquery-export │
└────────────────────────────────────┴───────────┴────────────────────────────────┴────────┴─────────┴─────────────────────┴───────────────────────────────────────────────────┘
⚠ Notice: Firebase Extensions will shut down on March 31, 2027. Learn more: https://firebase.google.com/docs/extensions/faq-and-troubleshooting

    ext:list 命令也具有 JSON 输出格式，如果您已安装实用程序 jq，则可以使用该实用程序获取项目的所有实例 ID 的列表：

    firebase ext:list --json --project <project-id> | jq -r '.result[].instanceId'

    示例：

    firebase ext:list --json --project my-project | jq -r '.result[].instanceId'

    输出：

    firestore-bigquery-export-zbrp
firestore-bigquery-export

  2. 导出每个实例的配置：

    对于每个实例，您都可以通过执行以下导出命令将其配置保存到磁盘：

    firebase ext:export --mode functions --project <project-id> --instance <your-instance-id>

    示例：

    firebase ext:export --mode functions --project my-project --instance firestore-bigquery-export

    输出：

    i  extensions: ensuring required API firebaseextensions.googleapis.com is enabled...
i  functions: Saving exported extensions config as a Function Kits .env file
i  functions: Created new local file firestore-bigquery-export/.env.testing to store param values. We suggest explicitly adding or excluding this file from version control.
i  functions: Loaded environment variables from firestore-bigquery-export/.env.testing
i  functions: Loaded environment variables from firestore-bigquery-export/.env.testing
i  functions: Writing new parameter values to disk: firestore-bigquery-export/.env.testing

    在磁盘上，您会在类似 <instance-id>/.env.<project-id> 的位置找到相应扩展程序实例的导出内容。在此示例中，该文件位于 firestore-bigquery-export/.env.my-project。

    您可以为每个实例重复此流程一次，此流程会创建一组 .env 文件，其中包含所有扩展程序实例配置，这些文件稍后可在迁移过程中重复使用。

  3. 将导出的 .env 文件移至更合适的位置：

    扩展程序导出的 .env 文件直接放置在您的 Firebase 项目中，但如果您尚未迁移到函数套件，则无需每天使用这些文件。您可以将它们从项目中移至任何其他合适的存储位置，直到将来需要使用它们或选择删除它们为止。