以用户身份将扩展程序迁移到 Cloud Functions（续11）

以用户身份将扩展程序迁移到 Cloud Functions（续11）

以用户身份将扩展程序迁移到 Cloud Functions（续11）

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!

如需验证套件的 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 的流

如果向套件和扩展程序传送了同一事件，则使用“将数据流式传输到 Cloud Firestore 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

如果您有大量日志，可以使用以下命令过滤到特定的套件功能：

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                                                     │

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 配置的实例，还是安装第二个实例。