THE3RDTRAINER/Homepage

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

概述

将 Firebase Extension 迁移为以下两种目标之一：

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

利用原生 Cloud Functions 特性（声明式 IAM、参数化配置、SDK 生命周期钩子）并通过解构兼容性填充层（Destructuring Compatibility Shim）将第一代触发器升级为第二代。

---

目标迁移工作流

• 目标 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。
• 任务：使用 firebase-functions/v2/tasks 中的 onTaskDispatched。入队任务时移除 EXT_INSTANCE_ID。
• HTTP：使用 firebase-functions/v2/https 中的 onRequest。
• 在旧版第一代处理器期望 (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. 变更内容（扩展 vs 包）对比表。

提醒：切勿执行 npm publish。