遷移後最佳做法

從 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，其中包含套件來源，包括匯入及匯出套件的基本 index.ts 檔案，同時設定參數，讓您為套件的每個例項選擇不同的位置。
  • 建立 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.my-project
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 套件，以修正錯誤、新增功能、更新依附元件或解決安全漏洞。建議您隨時掌握這些版本的最新資訊，並安裝更新，尤其是解決安全漏洞的更新。

functions:kits:install 指令會建立程式碼集，將套件安裝為 npm 套件，並為套件的每個執行個體匯出所有函式。如要升級套件，請更新套件版本，然後重新部署套件的每個執行個體，以套用變更。

判斷套件是否有更新

前往套件的 source 目錄，路徑為 function-kits/<your-kit-id>/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

    » firebase ext:list
i  extensions: ensuring 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.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 專案，但如果尚未遷移至函式套件，則不需要每天使用。您可以將這些資料從專案移至其他適當的儲存位置，等到日後需要時再使用，或選擇刪除。