使用 gcloud 直接部署 Firestore Gen2 触发函数会导致签名不匹配错误（如 “takes 1 positional argument but 2 were given”），根本原因在于 gcloud 缺少 Firebase 运行时所需的事件上下文注入机制；必须改用 Firebase CLI 部署，才能确保函数接收符合预期的 Event[DocumentSnapshot] 单参数签名。
使用 `gcloud` 直接部署 firestore gen2 触发函数会导致签名不匹配错误（如 “takes 1 positional argument but 2 were given”），根本原因在于 `gcloud` 缺少 firebase 运行时所需的事件上下文注入机制；必须改用 firebase cli 部署，才能确保函数接收符合预期的 `event[documentsnapshot]` 单参数签名。
Firebase Gen2 Cloud Functions 对 Firestore 触发器（如 @on_document_created）有严格的运行时契约：函数仅接收一个参数——即类型为 Event[DocumentSnapshot] 的事件对象。该对象已封装了文档快照、元数据及上下文信息（如 event.data 和 event.reference）。但当你使用 gcloud functions deploy 手动部署时，Google Cloud 基础设施会以通用 CloudEvents 格式传递原始事件，额外注入一个隐式的 context 参数（类似 Gen1 行为），导致 Python 解释器实际传入两个参数，从而触发 TypeError。
✅ 正确做法：始终使用 Firebase CLI 部署 Gen2 Firestore 函数：
# 确保已安装并登录 Firebase CLI npm install -g firebase-tools firebase login # 初始化函数（若尚未初始化） firebase init functions --project=test-project # 部署（自动识别 @on_document_created 并配置正确触发器） firebase deploy --only functions:example --region=europe-west3
此时 firebase deploy 会：
- 自动解析装饰器（如 @on_document_created(document="test/{testId}")）；
- 生成符合 Firebase Functions v2 规范的 cloudFunction 配置；
- 在底层调用 gcloud 时注入必要的 --trigger-location、--trigger-event-filters 及关键的 --trigger-service-account 和运行时适配逻辑；
- 确保执行环境只向你的函数传递 1 个标准化的 Event[T] 参数。
⚠️ 注意事项：
- 不要混合使用 gcloud 和 Firebase CLI 部署同一 Gen2 函数，可能导致触发器注册不一致；
- --trigger-event-filters-path-pattern=document='' 是无效的（且被 Firebase CLI 忽略），路径模式应由装饰器中的 document 参数声明（如 "test/{testId}"），而非命令行；
- 环境变量需通过 firebase.json 中的 functions[0].environmentVariables 或 .env 文件管理，而非 --env-vars-file（该参数不适用于 Firebase CLI 的 Gen2 部署流程）；
- 若需自定义内存或超时，应在 functions/index.py 同级的 functions/__init__.py 或 firebase.json 中配置，例如：
{ "functions": [{ "source": "functions", "codebase": "default", "ignore": ["node_modules"], "runtime": "python311", "memory": "512MiB", "timeoutSeconds": 60 }] }
总结：Firebase Gen2 函数不是纯 Google Cloud Functions，而是 Firebase 托管的增强型服务。其触发器绑定、类型安全和事件序列化均由 Firebase CLI 工具链保障。绕过该工具链将破坏类型契约——这不是代码错误，而是部署范式错误。坚持“Firebase CLI 部署 + 装饰器声明触发器”的组合，是避免此类问题的唯一可靠实践。
