Firebase Extensions 淘汰常見問題

我們為何要淘汰 Firebase Extensions？

由於底層Google Cloud基礎架構即將進行變更和淘汰作業，我們將停止提供代管Firebase Extensions服務。

2027 年 3 月 31 日後，現有已部署的擴充功能是否會停止運作？

不會。已部署的擴充功能會直接在標準 Google Cloud 基礎架構 (例如 Cloud Functions、Eventarc、Cloud Run 和 Cloud Tasks) 上執行，並無限期繼續執行。

不過，2027 年 3 月 31 日之後，您將無法再透過 Firebase 控制台或 CLI 更新、重新設定或解除安裝這些擴充功能。您也無法再下載現有的擴充功能設定，以利遷移至函式套件。強烈建議您在 2027 年 3 月 31 日前遷移或匯出擴充功能設定。

如果使用者不採取任何行動，會發生什麼情況？

如果使用者不採取任何行動，現有已部署的函式會繼續以標準資產的形式執行。不過，2027 年 3 月 31 日後：

1. 無法變更設定參數或更新環境變數。
2. 無法套用錯誤修正、安全性修補程式或升級依附元件。
3. 他們無法下載擴充功能設定，以協助設定替代函式套件。
4. 目前大多數擴充功能都是以舊版 Cloud Functions v1 SDK 建構而成，因此與舊版 Node.js 執行階段相關聯。Google Cloud 完全淘汰這些舊版執行階段後，函式可能會停止執行或遭到停用。請參閱「執行階段支援」。

Firebase Extensions 停止運作後，是否有其他替代方案？

我們在 Cloud Functions 中新增了許多功能，讓它們能夠取代擴充功能。最值得一提的是函式套件，這類套件可透過 npm 發布，讓您部署多個函式例項，類似於在單一專案中多次安裝擴充功能。

不過，是否要在 npm 上發布正式的函式套件替代項目，則由各擴充功能發布者自行決定。由於擴充功能是開放原始碼，如果發布者不想製作官方替代版本，任何開發人員都可以分叉擴充功能，使用 Node SDK 中的第 2 代 API 製作非官方替代版本。Cloud Functions

如要進行替換，發布者請按照發布者遷移指南中的說明操作。

如要使用官方提供的替代套件或自行建立替代套件，請按照使用者遷移指南中的操作說明進行。

擴充功能使用者應採取哪些行動？

如果您是擴充功能使用者，且不再使用已安裝的擴充功能，請在 2027 年 3 月 31 日前解除安裝。

停用後，Firebase 控制台中的「解除安裝」按鈕和對應的 CLI 指令將會移除。您必須使用 Google Cloud 控制台，手動刪除所有相關聯的 Google Cloud 資源，包括個別的 Cloud Functions、Secret Manager 密鑰、Cloud Tasks 佇列和自訂 IAM 服務帳戶。

不過，如果您經常使用已安裝的擴充功能，強烈建議遷移至函式套件。如要改用函式套件，請按照使用者遷移指南中的操作說明進行。

您可以選擇不遷移至函式套件，但強烈建議您更新所有擴充功能至最新版本，並持續更新，以及匯出現有擴充功能設定，以防日後想遷移。

擴充功能發布者應採取哪些行動？

建議您將已發布的擴充功能遷移至 NPM 上發布的函式套件。您可以先將擴充功能遷移至第 2 代函式，這是建立函式套件的先決條件。這包括使用 Cloud Functions 第 2 版 SDK 封裝擴充功能邏輯。我們已更新 Cloud Functions v2 SDK，支援宣告式安全性和生命週期事件等功能。您現在可以將現有的擴充功能程式碼遷移至第 2 代函式，同時盡可能減少核心業務邏輯的變動。您可以使用 npm 套件發布這些函式。詳情請參閱發布商遷移指南。

如有其他問題，該怎麼辦？

如有任何問題，請參閱使用者遷移指南。如果使用本指南後仍有疑問，請洽詢 Firebase 支援團隊。

如對遷移作業有任何疑問，發布商可參閱發布商遷移指南。Firebase Extensions本指南提供相關操作說明，協助您掌握最新消息，並取得替代已發布擴充功能的相關協助。

有哪些主要的遷移路徑？

2026 年 9 月起，Firebase將正式支援兩種主要遷移路徑：

1. 遷移至 NPM 共用函式 (「函式套件」)：建議將 Firestore 串流至 BigQuery，以及任何在 NPM 上提供的其他函式套件。核心邏輯會使用 Cloud Functions 第 2 版 SDK，封裝為標準 NPM 程式庫。使用者初始化標準 Cloud Functions 程式碼集、安裝套件、重新匯出函式，並使用 CLI 獨立部署函式。
2. 分叉並自行管理：建議所有在 npm 上沒有可用函式套件的擴充功能採用此方法。使用者複製或分叉開放原始碼擴充功能原始碼，使用盡力而為的 AI 遷移技能或手動指南，將觸發條件重構為標準 Firebase v2 函式，並完全擁有程式碼集及其持續維護作業。

哪些擴充功能會遷移至函式套件？

「將 Firestore 資料串流至 BigQuery」擴充功能已遷移至函式套件，可做為 npm 套件 @firebase-function-kits/firestore-bigquery-export 使用。

為什麼遷移作業需要從 Cloud Functions 第 1 版升級至第 2 版？

Cloud Functions v1 標準支援服務將於 Node.js 22 執行階段結束。為避免開發人員「重複遷移」，也就是先遷移離開 Firebase Extensions，但舊版執行階段淘汰後，又被迫進行第二次手動重構，Firebase 強烈建議您在遷移期間，立即將所有遷移的函式升級至 v2 SDK，函式套件則必須升級。

擴充功能使用者也可以按照使用者遷移指南，自行建立函式套件。

遷移至自助式管理的 Cloud Functions 後，客戶的帳單會受到影響嗎？

一般來說，不需要。已部署的擴充功能會向客戶收取所用基礎資源的費用，例如Google Cloud叫用次數、Cloud FunctionsCloud Storage或BigQuery儲存空間和查詢。不過，在遷移期間，如果客戶同時執行舊版 Firebase Extensions 和新部署的替代功能，確保安全轉換，可能會產生少許額外費用。

如何處理 Mandiant 或其他專屬企業帳戶的帳單？

這項淘汰作業是平台層級的變更，會影響所有 Firebase 和 Google Cloud 專案。標準帳單和訂閱方案不受影響。如果客戶因淘汰作業導致服務中斷而要求 SLA 抵免額，或遇到複雜的帳單例外狀況，請透過一般帳單支援管道直接提報案件。

遷移期間是否可能遺失資料或發生服務中斷？

將代管資源轉換為自行管理的程式碼集，可能會導致服務中斷或遺失事件，但風險不高。

• 觸發條件中斷：如果先刪除舊觸發條件，再啟用新觸發條件，就會產生空檔，導致系統錯過事件 (例如Cloud Firestore文件寫入)，且這些事件會永久遺失。建議您先部署替代套件並驗證，再移除擴充功能，以免遺失資料。
• 權限缺口：如果新部署的程式碼集缺少必要的 IAM 權限，作業 (例如寫入 BigQuery) 會在執行階段無聲無息地失敗或當機。我們已為函式新增宣告式安全性，因此，如果帳戶可以查詢及設定角色，並產生服務帳戶，那麼該帳戶首次部署套件時，應可緩解這個問題。

如何避免重要 Cloud Firestore 至 BigQuery 匯出擴充功能發生資料遺失？

為確保安全移轉且不會遺失資料，支援團隊必須建議使用者採用重疊式轉換，而非間隔式轉換。這是遷移至套件時的預設行為：

1. 在擴充功能仍處於安裝及執行狀態時，部署替代函式套件。請稍候幾分鐘，等待 Eventarc 完整佈建。
2. 將測試文件寫入監控的 Cloud Firestore 集合，並確認新的自行管理函式是否成功將對應的資料列寫入 BigQuery 變更記錄表 (攜帶新的事件 ID)。
3. 確認新部署作業正常運作後，請立即解除安裝或停用舊版擴充功能，終止重複寫入行為。
4. 請盡量縮短重疊時間範圍，盡量減少原始 BigQuery 變更記錄中的重複資料列。

5. 在遷移期間進行雙重寫入，會導致原始變更記錄資料表 (*_raw_changelog) 中出現兩列，且具有相同的檔案資料和 Cloud Firestore 提交時間戳記。不過，資料表的最新檢視畫面 (*_raw_latest) 會正確無誤。

如要進一步瞭解如何遷移這個擴充功能，以及如何復原任何資料遺失，請參閱套件的 README.md。

如果生命週期佈建步驟失敗，該怎麼辦？

在代管服務下，設定工作 (例如建立資料集、資料表和檢視區塊) 會自動處理。BigQuery 在自行管理的 NPM 模型下，這些事件會使用生命週期工作佇列函式觸發，例如在 firestore-bigquery-export 中，這項函式稱為 initBigQuerySync。

如果這個步驟失敗或未自動執行，請按照下列步驟操作：

1. 確認已為 Cloud Functions 執行階段服務帳戶授予必要的 IAM 角色。舉例來說，對於 firestore-bigquery-export，這包括：

   • 如要建立資源並插入資料列，請按照下列步驟操作：roles/bigquery.dataEditor
   • 如要執行工作及建立檢視區塊，請按照下列步驟操作：roles/bigquery.user
   • 如要將佈建工作加入佇列，請執行 roles/cloudtasks.enqueuer：

2. 確認呼叫者具備 roles/cloudtasks.enqueuer 權限。

3. 使用 CLI 手動重新執行生命週期初始化指令：

   firebase functions:lifecycle:run afterInstall KIT_INSTANCE_ID
   

4. 檢查觸發函式和工作佇列執行的 Cloud Logging 記錄，診斷任何權限或設定錯誤。

Secret Manager憑證的遷移方式為何？

在受管理模型中，Secret Manager 資源會自動繫結至擴充功能例項。使用 ext:migrate 或 ext:export --mode functions 指令將擴充功能設定匯出至函式套件時，系統會停止讓擴充功能管理這些密鑰，因此即使解除安裝擴充功能，密鑰仍會保留在專案中。如要移除這些密鑰，請在 Google Cloud 控制台中手動操作。

如果使用者想執行多個已遷移的擴充功能執行個體，該怎麼辦？

我們推出函式套件，支援函式的多個執行個體，類似於擴充功能的多個版本。每個套件都會取得專屬的套件例項 ID，類似於程式碼集，可在 CLI 指令中與程式碼集互換使用。部署時，套件例項中的所有函式都會加上 kit-<instance-id>- 前置字串，確保每個函式都有專屬名稱，類似於擴充功能的 ext-<extension-instance-id>- 前置字串。如要進一步瞭解如何使用函式套件進行遷移，請參閱使用者遷移指南。

Kit 安裝作業會使用 npm，如果我想使用 Yarn 或其他 Node 相容的套件管理工具，該怎麼做？

我們目前沒有支援 Yarn 或其他套件管理工具的計畫。在首次安裝時設定套件原始碼時，套件安裝作業會直接執行 npm 指令。

或者，您也可以建立來源目錄、自行安裝套件 npm，並使用適當的建構和匯出項目進行設定。請參閱 中的 TypeScript index-kit 範本 firebase-tools ，或查看 npm 安裝的套件做為範例。完成這項操作後，您可以使用 --directory (而非 --package) 安裝，就像安裝本機套件一樣。日後您需要依目錄或 ID 識別套件，但可以使用套件指令新增及移除執行個體。

我的擴充功能使用 Docker 存放區或 KMS 金鑰進階系統參數，該如何在函式套件中設定？

目前，我們不支援在 Cloud Functions 中為 Firebase 設定 Docker 存放區或 KMS 金鑰。如果您要從已設定這些系統參數的擴充功能遷移，並想保留這項功能，可以使用 gcloud CLI 將參數套用至新套件的函式。

必要條件

1. 請先按照遷移指南部署函式套件，確保函式存在於 Google Cloud 中。

2. 在終端機中定義環境變數：

   export PROJECT_ID="YOUR_PROJECT_ID"
   export FUNCTION_REGION="YOUR_REGION"          # e.g. us-east1
   export KIT_NAME="YOUR_KIT_NAME"                # e.g. firestore-bigquery-export
   export SOURCE_DIR="YOUR_KIT_SOURCE_DIR"       # e.g. "./function-kits/${KIT_NAME}/source"
   export REPO_NAME="YOUR_DOCKER_REPO_NAME"
   export KEY_RING="YOUR_KMS_KEY_RING"
   export KEY_NAME="YOUR_KMS_KEY_NAME"
   
   # Retrieve Project Number automatically
   export PROJECT_NUMBER=$(gcloud projects describe "$PROJECT_ID" --format="value(projectNumber)")
   

3. 在套件的來源根目錄中預先建立 .gcloudignore，以免 .gitignore 忽略編譯的建構檔案：

   cat << 'EOF' > "${SOURCE_DIR}/.gcloudignore"
   .gcloudignore
   .git
   .gitignore
   
   node_modules
   #!include:.gitignore
   !lib/**
   EOF
   

4. 授予必要的 IAM 權限：

   • KMS 金鑰 (授予服務代理解密存取權)：

     for SERVICE_ACCOUNT in \
       "service-${PROJECT_NUMBER}@serverless-robot-prod.iam.gserviceaccount.com" \
       "service-${PROJECT_NUMBER}@gcf-admin-robot.iam.gserviceaccount.com" \
       "service-${PROJECT_NUMBER}@gcp-sa-artifactregistry.iam.gserviceaccount.com"
     do
       gcloud kms keys add-iam-policy-binding "$KEY_NAME" \
         --keyring="$KEY_RING" \
         --location="$FUNCTION_REGION" \
         --project="$PROJECT_ID" \
         --member="serviceAccount:${SERVICE_ACCOUNT}" \
         --role="roles/cloudkms.cryptoKeyEncrypterDecrypter"
     done
     

   • 適用於 Artifact Registry (授予 Cloud Build 的寫入權限，以及 Cloud Run 的讀取權限)：

     # Grant the Cloud Build / Compute Service Account permission to write images to the repository
     gcloud artifacts repositories add-iam-policy-binding "$REPO_NAME" \
       --location="$FUNCTION_REGION" \
       --project="$PROJECT_ID" \
       --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
       --role="roles/artifactregistry.writer"
     
     # Grant Cloud Run permission to pull images from the repository
     gcloud artifacts repositories add-iam-policy-binding "$REPO_NAME" \
       --location="$FUNCTION_REGION" \
       --project="$PROJECT_ID" \
       --member="serviceAccount:service-${PROJECT_NUMBER}@serverless-robot-prod.iam.gserviceaccount.com" \
       --role="roles/artifactregistry.reader"
     

使用 gcloud CLI 套用設定

針對套件中的每個函式執行 gcloud functions deploy：

gcloud functions deploy FUNCTION_NAME \
  --project="$PROJECT_ID" \
  --region="$FUNCTION_REGION" \
  --source="./function-kits/${KIT_NAME}/source" \
  --docker-repository="projects/${PROJECT_ID}/locations/${FUNCTION_REGION}/repositories/${REPO_NAME}" \
  --kms-key="projects/${PROJECT_ID}/locations/${FUNCTION_REGION}/keyRings/${KEY_RING}/cryptoKeys/${KEY_NAME}"

請注意，在下列情況下，這個解決方法會失效：

1. 新的套件執行個體：在 firebase.json 中新增執行個體會建立新的 Cloud Functions v2 資源，預設使用 Google 管理的金鑰和 gcf-artifacts。您必須為每個新例項執行 gcloud。
2. 重新建立函式：變更觸發類型 (例如從 HTTPS 改為 Cloud Firestore 觸發程序)、變更進入點或重新命名，都會導致 Firebase CLI 刪除舊函式並建立新函式。在您再次執行 gcloud 之前，新函式會失去這些設定。
3. 設定漂移：Firebase CLI 不會在 firebase functions:list 或差異記錄中顯示 KMS 或 Docker 存放區狀態，因此難以稽核基礎架構。

驗證成功

如要確認存放區和加密金鑰是否已套用，請執行下列指令：

gcloud functions describe FUNCTION_NAME \
  --region="$FUNCTION_REGION" \
  --project="$PROJECT_ID" \
  --format="yaml(state, buildConfig.dockerRepository, kmsKeyName)"