將 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 控制台「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 (如果使用密鑰)
  • roles/serviceusage.serviceUsageAdmin (如需啟用新的 API)

建議使用先前安裝過擴充功能和部署過函式的帳戶，因為這類帳戶大多已具備這些權限。如果遷移帳戶需要更多角色，請按照 Google CloudIAM 操作說明新增。

選擇 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

如果記錄很多，可以使用下列指令篩選出特定套件函式：

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                                                     │

查看函式套件 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>

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

確認函式套件的初始部署作業已成功完成後，您需要驗證套件的功能是否確實正常運作。由於擴充功能本身仍在執行，因此您必須小心，不要只檢查兩者之一是否有效，因為擴充功能已經且將繼續運作。

如果處理方式未變更，且您未看到擴充功能和套件的重複結果，最好的做法是在觸發套件功能後，直接檢查套件的記錄。

實際範例：將 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

如果記錄很多，可以使用下列指令篩選出特定套件函式：

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. 解除安裝擴充功能

驗證已部署的函式套件後，您可以解除安裝擴充功能，以免套件和擴充功能重複執行相同行為。無論安裝方式為何，只要傳遞 --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 環境，且每個環境都有一個 documents Cloud Firestore 執行個體，並匯出至 BigQuery，則您可能會安裝兩個 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 設定的執行個體，或安裝第二個執行個體。