扩展到Functions代码库与npm包迁移

概述

本技能指导Agent将Firebase扩展仓库或实例迁移至以下两种目标之一：

独立的Cloud Functions for Firebase代码库（基于
```
firebase-functions
```
，用于终端用户应用集成），或
可发布的npm包/可共享开源包（供扩展发布者分发可复用的V2函数）。

它利用Cloud Functions for Firebase的正式版（GA）功能，在代码中原生处理权限、依赖项和生命周期钩子，并提供使用解构兼容垫片（Destructuring Compatibility Shim）将旧版V1触发器现代化升级到V2的说明。

触发条件

当用户提出以下需求时激活本技能：

将已安装的Firebase Extension迁移或转换为独立的Functions代码库。
将扩展仓库转换为可发布的npm包（可共享开源包）。
将扩展触发器从V1升级到V2。

目标迁移流程

开始前，与开发者确认目标迁移方向：

目标A：本地Functions代码库（终端用户应用集成）
- 输出：源代码放置在项目的
```
functions/src/
```
  目录下。
- 配置：通过
```
.env
```
  中的
```
defineString
```
  、
```
defineSecret
```
  等定义参数。
- 部署：直接通过
```
firebase deploy --only functions
```
  命令部署。
目标B：可发布的npm包/可共享开源包
- 输出：包含导出V2函数的可复用npm包。
- 配置：
```
package.json
```
  中包含
```
exports
```
  映射，且
```
firebase-functions
```
  声明在
```
dependencies
```
  （或
```
peerDependencies
```
  ）中。
- 使用方式：终端用户安装包（
```
npm i <package-name>
```
  ）并在其
```
index.ts
```
  中重新导出函数。

入门指南与Git安全规范

Git状态检查：开始前确认工作区的Git状态为干净状态。
原地复制：如果要将代码复制到同一仓库内的新子目录：
- 使用
```
git cp
```
  （或复制文件后提交）将扩展的源码目录复制到目标目录。
- 立即提交：
```
"Copying [extension-name] extension to [directory] in preparation for rewrite"
```

规则与约束

1. 零本地开销（Cloud Functions集成）

假设Cloud Functions for Firebase的工作负载身份、声明式安全和SDK生命周期钩子均已正式发布（GA）。

请勿输出指导用户手动执行
```
gcloud
```
IAM命令或创建服务账号的说明或脚本。
请勿编写代码注释指导用户在云控制台中手动启用Google API。
取而代之，使用SDK中的
```
requiresAPI
```
和
```
requiresRole
```
导入声明。

2. 全局参数访问限制

绝对不要在全局作用域调用参数的
.value()
方法。

如果全局变量或类实例需要使用参数值初始化，请在全局声明变量并在

onInit()

回调中完成初始化：

typescript

import { defineString } from "firebase-functions/params";
import { onInit } from "firebase-functions/v2";

const bqDataset = defineString("DATASET_ID");
let bqClient: BigQuery;

onInit(() => {
  bqClient = new BigQuery({ datasetId: bqDataset.value() });
});

3. V2触发器的并发与成本一致性

升级触发器到V2时：

默认情况下，V2函数启用并发（每个实例最多处理80个请求）。
如果希望保持V1的 fractional CPU定价（并禁用并发），请在函数的配置对象中设置
```
cpu: "gcf_gen1"
```
。

分步迁移执行流程

步骤1：盘点扩展内容

全面盘点扩展声明、交付和文档的所有内容，确保迁移过程中无内容丢失：

盘点
extension.yaml
：
- ```
params
```
  ：转换为Functions参数（
```
defineString
```
  、
```
defineSecret
```
  等）。
- ```
apis
```
  ：转换为
```
requiresAPI(...)
```
  声明。
- ```
roles
```
  ：转换为
```
requiresRole(...)
```
  声明。
- ```
lifecycleEvents
```
  （
```
onInstall
```
  、
```
onUpdate
```
  、
```
onConfigure
```
  ）：转换为
```
afterFirstDeploy
```
  和
```
afterRedeploy
```
  钩子。
- ```
resources
```
  ：记录所有需要从第一代（
```
firebase-functions/v1
```
  ）转换为第二代（
```
firebase-functions/v2
```
  ）的函数触发器，包括标准事件触发器、HTTP处理器和任务队列（
```
onTaskDispatched
```
  ）。
盘点文件与工具：
- ```
functions/
```
  ：源码、触发器、辅助工具和任务队列处理器。
- 文档：
```
README.md
```
  、
```
PREINSTALL.md
```
  和
```
POSTINSTALL.md
```
  。
- ```
scripts/
```
  ：记录扩展附带的任何回填、导入或辅助脚本。

步骤2：创建/更新

package.json

为迁移后的扩展代码创建npm包（位于项目根目录或专用工作区目录）：

设置可发布的包名（
```
name: "<package-name>"
```
）。
保留开发与测试依赖：保留旧版扩展（
```
functions/package.json
```
或根目录
```
package.json
```
）中所有现有的
```
devDependencies
```
、测试运行器（
```
jest
```
、
```
ts-jest
```
、
```
@types/jest
```
、
```
mocha
```
、
```
@types/mocha
```
）和测试脚本（
```
"test": "..."
```
）。请勿丢弃测试框架或类型定义。

在

dependencies

（如果创建轻量级中间件包且由根消费者管理运行时版本，则声明在

peerDependencies

）中声明

firebase-functions

（例如

^7.0.0

）：

json

{
  "name": "<package-name>",
  "version": "1.0.0",
  "main": "lib/index.js",
  "types": "lib/index.d.ts",
  "exports": {
    ".": {
      "types": "./lib/index.d.ts",
      "default": "./lib/index.js"
    }
  },
  "engines": {
    "node": ">=22"
  },
  "dependencies": {
    "firebase-admin": "^12.0.0",
    "firebase-functions": "^7.0.0"
  }
}

步骤3：迁移函数代码并暴露可部署函数

将扩展的函数源码迁移到包的

src/

保留常规Firebase触发器导出。包必须暴露可部署的函数，以便终端用户可以从其入口文件（
```
index.ts
```
）重新导出。
文档说明消费者必须通过重新导出的方式部署打包后的函数：
typescript
```
export * from "<package-name>";
// 或命名导出：
// export { syncV2, initBigQuerySync } from "<package-name>";
```
注意：仅导入（
```
import "<package-name>"
```
）是不够的。Firebase CLI仅部署从用户根入口文件导出的函数。

步骤4：将函数从第一代升级到第二代

将每个导出的第一代函数触发器（

onWrite

、

onRequest

、

tasks.taskQueue().onDispatch

）转换为对应的第二代触发器（来自

firebase-functions/v2/...

的

onDocumentWritten

、

onRequest

、

onTaskDispatched

）：

签名与解构垫片：使用解构兼容垫片（
```
{ shimmedKey, context }
```
）保留V1业务逻辑，无需重写函数体。请参阅signature-mapping.md和destructuring-shim.md。
身份验证触发器例外：如果扩展使用V1身份验证触发器（
```
auth.user().onCreate()
```
、
```
auth.user().onDelete()
```
），请指导Agent检查已安装的
```
firebase-functions
```
包或在线文档中是否存在第二代替代方案。如果这些事件的第二代Auth触发器尚未支持，请明确警告用户，并暂停或拒绝这些特定触发器的迁移，直到V2替代方案可用。

步骤5：将扩展参数替换为Functions参数

extension.yaml

中的每个参数都转换为参数化配置调用：

映射参数类型和属性：

类型

string

defineString("PARAM_NAME", { label: "...", description: "...", default: "..." })

类型
```
secret
```
->
```
defineSecret("PARAM_NAME")
```

类型

int

defineInt("PARAM_NAME", { label: "...", default: 123 })

类型

boolean

defineBoolean("PARAM_NAME", { default: true })

类型

select

multiSelect

-> 将

options

映射到

input

：

defineString("PARAM_NAME", { input: { select: { options: [{ value: "val", label: "Val" }] } } })

validationRegex

-> 映射到文本输入选项：

defineString("PARAM_NAME", { input: { text: { validationRegex: "^[a-z]+$" } } })

required: true

/ 非空验证 -> 将

nonEmpty: true

映射到输入选项：

defineString("PARAM_NAME", { input: { text: { nonEmpty: true } } })

在处理器内部使用
```
paramName.value()
```
读取参数值。
保留确切参数名称：永远不要更改参数名称（如
```
COLLECTION_PATH
```
、
```
DATASET_ID
```
等），以便现有值可以在
```
.env
```
中无缝迁移。

步骤6：迁移内部任务队列调用（

queue.enqueue(...)

）

如果扩展代码使用Admin SDK（

getFunctions().taskQueue(...)

）将任务加入自身队列：

在Extensions运行时中，Admin SDK通过函数名称加上
```
process.env.EXT_INSTANCE_ID
```
解析队列。

在npm包/常规代码库中：完全移除第二个参数（

EXT_INSTANCE_ID

）。Admin SDK会自动定位当前代码库：

typescript

// 之前（扩展运行时）：
// const queue = getFunctions().taskQueue(`locations/${region}/functions/syncBigQuery`, process.env.EXT_INSTANCE_ID);

// 之后（npm包）：
const queue = getFunctions().taskQueue(`locations/${region}/functions/syncBigQuery`);
await queue.enqueue(taskData);

步骤7：迁移密钥

对于声明为

type: secret

的参数：

显式声明密钥：

typescript

import { defineSecret } from "firebase-functions/params";
const apiKey = defineSecret("API_KEY");

在触发器配置中绑定密钥：

typescript

export const fn = onRequest({ secrets: [apiKey] }, handler);

保留确切的密钥名称不变，以便现有的Secret Manager绑定继续生效。

步骤8：声明所需API和IAM角色

将

extension.yaml

中的

apis

和

roles

替换为入口文件中的声明式代码：

typescript

import { requiresAPI, requiresRole } from "firebase-functions";

requiresAPI("bigquery.googleapis.com", "Needed to write changelog rows");
requiresRole("roles/bigquery.dataEditor");
requiresRole("roles/bigquery.user");

在部署时，Firebase CLI会自动将这些角色授予托管运行时服务账号，并启用所需的API。

步骤9：转换生命周期钩子（

afterFirstDeploy

afterRedeploy

）

将

lifecycleEvents

（

onInstall

、

onUpdate

、

onConfigure

）替换为SDK生命周期钩子：

将任务队列处理器（

initBigQuerySync

、

setupBigQuerySync

）转换为V2的

onTaskDispatched

（来自

firebase-functions/v2/tasks

），移除旧版的

getExtensions().runtime().setProcessingState(...)

调用。

在代码中注册生命周期钩子：

typescript

import { afterFirstDeploy, afterRedeploy } from "firebase-functions/v2";

// 替代onInstall：
afterFirstDeploy({
  task: {
    function: "runInitialSetup",
    body: {}
  }
});

// 替代onUpdate & onConfigure：
afterRedeploy({
  task: {
    function: "runInitialSetup",
    body: { reconcile: true }
  }
});

确保处理器是幂等的，并记录手动重新运行的命令：

bash

firebase functions:lifecycle:run afterFirstDeploy CODEBASE_NAME
firebase functions:lifecycle:run afterRedeploy CODEBASE_NAME

步骤10：为用户编写设置文档（

README.md

）

保留原始扩展已在

README.md

（以及

PREINSTALL.md

POSTINSTALL.md

）中记录的所有文档、密钥和设置说明，并按需更新：

更新配置引用：将引用旧版
```
extension.yaml
```
安装提示或
```
ext-*.env
```
文件的说明替换为与
```
defineString
```
参数匹配的标准
```
.env
```
参数化配置设置。
包含重新导出代码片段：确保展示基本的根重新导出代码片段（
```
export * from "<package-name>";
```
），以便用户知道如何在其根
```
index.ts
```
中暴露函数。
避免不必要的模板内容：如果设置在代码中自明或已在现有README章节中涵盖，请不要生成冗余的对比表格或通用安装步骤。

步骤11：构建与测试验证

验证源码编译：运行
```
npm run build
```
（
```
tsc
```
）确保
```
src/
```
目录中无TypeScript编译错误。
验证单元测试套件与类型定义：
- 如果扩展中存在现有单元测试（
```
__tests__/
```
  、
```
test/
```
  ）：
  - 确保
    @types/jest
    （或原始测试框架类型）存在于
    devDependencies
    中，以便测试文件可以干净地进行类型检查。
  - 更新升级后的V2触发器的测试调用，传递单个解构的事件对象（
    ({ change: mockChange, context: mockContext })
    而非位置参数
    (mockChange, mockContext)
    ）。
  - 运行
    npm test
    或对测试文件进行类型检查（
    npx tsc --noEmit
    ）以验证无回归问题。

参考资料与官方资源

官方Google迁移指南: Prepare Firebase Extensions for migration to Cloud Functions

发布者支持联系方式:

支持邮箱:

firebase-extensions-migrator-support-external@google.com

支持组订阅:

firebase-extensions-migrator-support-external+subscribe@google.com

解构垫片: 详情请参阅 destructuring-shim.md中的事件属性转换说明。
触发器映射: 详情请参阅 signature-mapping.md中的V1与V2触发器定义及垫片键。
配置与参数: 详情请参阅 configuration-migration.md中的
```
runWith
```
选项、参数和密钥绑定说明。

extension-to-functions-codebase

NPX安装

标签

SKILL.md 内容（中文）

扩展到Functions代码库与npm包迁移

概述

触发条件

目标迁移流程

入门指南与Git安全规范

规则与约束

1. 零本地开销（Cloud Functions集成）

2. 全局参数访问限制

3. V2触发器的并发与成本一致性

分步迁移执行流程

步骤1：盘点扩展内容

步骤2：创建/更新
`package.json`

步骤3：迁移函数代码并暴露可部署函数

步骤4：将函数从第一代升级到第二代

步骤5：将扩展参数替换为Functions参数

步骤6：迁移内部任务队列调用（
`queue.enqueue(...)`
）

步骤7：迁移密钥

步骤8：声明所需API和IAM角色

步骤9：转换生命周期钩子（
`afterFirstDeploy`
&
`afterRedeploy`
）

步骤10：为用户编写设置文档（
`README.md`
）

步骤11：构建与测试验证

参考资料与官方资源

extension-to-functions-codebase

NPX安装

标签

SKILL.md 内容（中文）

扩展到Functions代码库与npm包迁移

概述

触发条件

目标迁移流程

入门指南与Git安全规范

规则与约束

1. 零本地开销（Cloud Functions集成）

2. 全局参数访问限制

3. V2触发器的并发与成本一致性

分步迁移执行流程

步骤1：盘点扩展内容

步骤2：创建/更新package.json

步骤3：迁移函数代码并暴露可部署函数

步骤4：将函数从第一代升级到第二代

步骤5：将扩展参数替换为Functions参数

步骤6：迁移内部任务队列调用（queue.enqueue(...)）

步骤7：迁移密钥

步骤8：声明所需API和IAM角色

步骤9：转换生命周期钩子（afterFirstDeploy & afterRedeploy）

步骤10：为用户编写设置文档（README.md）

步骤11：构建与测试验证

参考资料与官方资源

步骤2：创建/更新
`package.json`

步骤6：迁移内部任务队列调用（
`queue.enqueue(...)`
）

步骤9：转换生命周期钩子（
`afterFirstDeploy`
&
`afterRedeploy`
）

步骤10：为用户编写设置文档（
`README.md`
）