extension-to-functions-codebase

将扩展迁移到 Functions 代码库和 npm 软件包

概述

将 Firebase 扩展迁移到以下任一目标：

1. 本地 Cloud Functions 代码库（用于应用集成的 functions/src/）。
2. 可发布的 npm 软件包（可复用的开源软件包，导出 V2 函数）。

利用 Cloud Functions 原生功能（声明式 IAM、参数化配置、SDK 生命周期钩子），并使用解构兼容性垫片将第 1 代触发器升级到第 2 代。

---

目标迁移工作流

• 目标 A：本地 Functions 代码库（终端用户应用集成）

  • 输出：functions/src/ 下的代码。配置位于 .env。
  • 部署：firebase deploy --only functions。

• 目标 B：可发布的 npm 软件包／可共享软件包

  • 输出：导出 V2 函数的可复用 npm 软件包。
  • 配置：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() 中初始化全局 SDK 实例，或使用惰性 getter：

  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 步：清点扩展资源

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。
• 任务：使用来自 firebase-functions/v2/tasks 的 onTaskDispatched。移除 排入任务时使用的 EXT_INSTANCE_ID。
• HTTP：使用来自 firebase-functions/v2/https 的 onRequest。
• 对于旧版第 1 代处理程序所期望的 (change, context)，应用解构兼容性垫片 （{ change, context }、{ snapshot, context }）。

第 4 步：转换生命周期事件

在 src/index.ts 中将扩展生命周期事件映射到 SDK 生命周期钩子：

• 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. 变更内容（扩展与软件包）对比表。

提醒：绝不可执行 npm publish。