從 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.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 套件，以修正錯誤、新增功能、更新依附元件或解決安全漏洞。建議您隨時掌握這些版本資訊並安裝更新，尤其是修正安全漏洞的更新。
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 日前完成遷移，強烈建議您儲存擴充功能，以防日後決定遷移。
取得擴充功能執行個體 ID 清單：
您可以使用
ext:listCLI 指令，取得 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-troubleshootingext: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匯出每個執行個體的設定：
您可以執行下列匯出指令，將每個執行個體的設定儲存到磁碟：
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檔案，其中包含所有擴充功能執行個體設定，日後可做為遷移作業的一部分重複使用。將匯出的
.env檔案移到更合適的位置：擴充功能匯出的
.env檔案會直接放入 Firebase 專案，但如果您尚未遷移至函式套件，這些檔案在日常使用中並不需要。您可以將這些檔案從專案移至任何其他適當的儲存位置，留待日後使用或選擇刪除。