THE3RDTRAINER/Homepage

擴充功能轉換為 Functions 程式碼庫與 npm 套件遷移

概述

將 Firebase Extension 遷移為以下兩種形式之一：

1. 本地 Cloud Functions 程式碼庫（functions/src/，供應用程式整合）。
2. 可發佈的 npm 套件（可重複使用的開源套件，匯出第 2 代函式）。

運用原生 Cloud Functions 功能（宣告式 IAM、參數化設定、SDK 生命週期鉤子），並使用解構相容墊片（Destructuring Compatibility Shim）將第 1 代觸發器現代化升級為第 2 代。

---

目標遷移工作流程

• 目標 A：本地 Functions 程式碼庫（最終端應用整合）

  • 輸出：functions/src/ 下的程式碼。.env 中的設定。
  • 部署：firebase deploy --only functions。

• 目標 B：可發佈的 npm 套件／可分享套件

  • 輸出：可重複使用的 npm 套件，匯出第 2 代函式。
  • 設定：package.json 指定 exports 映射、engines: { "node": ">=22" } 以及 peerDependencies: { "firebase-functions": ">=6.0.0" }。
  • 使用方式：使用者安裝套件後，在 index.ts 中重新匯出函式（export * from "<package-name>"）。

---

核心規則與限制

1. 宣告式 IAM 與 API（零本地開銷）

使用原生 SDK 宣告，取代手動的 gcloud 指令或主控台操作說明：

• 使用 requiresRole("roles/...") 設定所需的 GCP IAM 權限。
• 使用 requiresAPI("service.googleapis.com", "Description") 設定所需的 Google API。

2. 全域參數存取限制

• 嚴禁在模組頂層載入作用域中呼叫 .value()。
• 在 onInit() 內部或惰性 getter 中初始化全域 SDK 實例：

  import { defineString } from "firebase-functions/params";
  import { onInit } from "firebase-functions/v2";
  
  const dataset = defineString("DATASET_ID");
  let client: BigQuery;
  
  onInit(() => {
    client = new BigQuery({ datasetId: dataset.value() });
  });
  

3. V2 並發與成本控制

V2 啟用並發（最多 80 個請求）。若要維持 V1 的單一並發計價方式，請設定 cpu: "gcf_gen1"。

---

逐步遷移執行步驟

步驟 1：盤點 Extension 資源

1. extension.yaml：
   • params → defineString、defineInt、defineBoolean、defineSecret。
   • apis → requiresAPI(...)。
   • roles → requiresRole(...)。
   • lifecycleEvents → afterFirstDeploy 與 afterRedeploy。
   • resources → 將第 1 代觸發器升級為第 2 代（onDocumentWritten、onTaskDispatched、onRequest）。
2. 檔案與指令碼：保留 devDependencies、測試框架（jest）及測試指令碼。

步驟 2：設定 package.json

• 設定 name: "<package-name>"、engines: { "node": ">=22" }。
• 設定 peerDependencies：

  "peerDependencies": {
    "firebase-admin": "^11.0.0 || ^12.0.0",
    "firebase-functions": ">=6.0.0"
  }
  

• 設定 exports 映射，指向 ESM/CommonJS 與 TypeScript 宣告檔（lib/index.js、lib/index.d.ts）。

步驟 3：將觸發器從 V1 升級至 V2

• Firestore：使用來自 firebase-functions/v2/firestore 的 onDocumentWritten。
• Tasks：使用來自 firebase-functions/v2/tasks 的 onTaskDispatched。排入任務時移除 EXT_INSTANCE_ID。
• HTTP：使用來自 firebase-functions/v2/https 的 onRequest。
• 在舊有第 1 代處理器預期接收 (change, context) 之處，套用解構相容墊片（{ change, context }、{ snapshot, context }）。

步驟 4：轉換生命週期事件

將 Extension 生命週期事件對應至 SDK 生命週期鉤子（位於 src/index.ts）：

• onInstall → afterFirstDeploy({ task: { function: "initTask" } })
• onUpdate / onConfigure → afterRedeploy({ task: { function: "setupTask" } })

步驟 5：套件 README 與匯出說明

產生 README.md，包含：

1. 安裝說明（npm install）。
2. 重新匯出程式碼片段（export * from "<package-name>"）。
3. 參數化設定 .env 參考對照表。
4. 變更內容（Extension 與套件）比較表。

提醒：絕對不要執行 npm publish。