將 Firebase Extensions 遷移至函式套件

本指南說明如何將擴充功能從已淘汰的 Firebase Extensions 環境遷移至函式套件，以便在 Firebase (第 2 代) 程式碼集中安裝及部署 Cloud Functions。

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控制台「擴充功能」頁面。已安裝的每個擴充功能都會指出是否有可用的函式套件替代項目。

  • 在終端機中執行 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 (如果使用密鑰)
  • 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>

如果在驗證期間決定要停止或復原這項遷移作業，可以按照「解除安裝擴充功能」一文中的說明解除安裝套件。

查看函式套件的 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 時，請務必記下該 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!

如要確認套件的 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. 解除安裝擴充功能

確認已部署函式套件後，即可解除安裝擴充功能，避免套件和擴充功能重複執行相同行為。無論擴充功能是透過何種方式安裝，只要傳遞 --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 設定的執行個體，或安裝第二個執行個體。