扩展转函数代码库与npm包迁移

扩展转函数代码库与 npm 包迁移

概述

将 Firebase 扩展迁移为以下两种形式之一：

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

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

---

目标迁移工作流

• 目标 A：本地函数代码库（最终用户应用集成）

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

• 目标 B：可发布的 npm 包 / 可共享包

  • 输出：可复用的 npm 包，导出 V2 函数。
  • 配置：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：盘点扩展资源

1. extension.yaml：
   • params → defineString、defineInt、defineBoolean、defineSecret。
   • apis → requiresAPI(...)。
   • roles → requiresRole(...)。
   • lifecycleEvents → afterFirstDeploy 和 afterRedeploy。
   • resources → 将第一代触发器升级为第二代（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。
• 在需要兼容旧版第一代处理器的位置应用解构兼容性垫片（{ change, context }、{ snapshot, context }）。

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

将扩展生命周期事件映射为 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. 变更对比表（扩展 vs 包）。

提醒：切勿执行 npm publish。