Firebase Stripe支付扩展Firestore模拟器未生成云函数问题

核心认知校准 #

• 直接从官方扩展源安装的扩展，不会在你自行维护的functions/index.ts中生成云函数代码：你参考的带index.ts的效果是扩展二次开发场景下的目录结构，普通安装场景下扩展的运行代码存放在项目.firebase/extensions缓存目录中，不会侵入你自己的业务代码目录。
• 不需要完成云端部署步骤即可在本地模拟器运行、测试扩展。

分步排查操作 #

• 检查firebase.json配置格式
  确认扩展配置写在根级extensions字段下，格式参考如下，注意版本号要和你安装的扩展版本一致：

  {
    "extensions": {
      "firestore-stripe-payments": "stripe/firestore-stripe-payments@<对应安装版本号>"
    }
  }
  

• 校验启动日志确认扩展加载状态
  执行firebase emulators:start启动模拟器时，重点查看extensions和functions两个模块的输出日志：
  • 正常加载时会打印Loaded extension: firestore-stripe-payments，随后列出该扩展注册的所有云函数（名称均以ext-firestore-stripe-payments-为前缀，包含创建支付会话、处理webhook、同步产品等方法）
  • 如果没有对应日志，优先检查扩展env文件的参数完整性
• 补全扩展必填环境变量
  打开扩展目录下的firestore-stripe-payments.env文件，以下必填参数不能留空，否则扩展会静默加载失败，无显性报错：
  • STRIPE_API_KEY：填写Stripe测试模式密钥（以sk_test_开头）
  • STRIPE_WEBHOOK_SECRET：本地测试可先填任意字符串占位，后续配置Stripe CLI转发时替换为实际签名值
  • PRODUCTS_COLLECTION、CUSTOMERS_COLLECTION：填写你计划用来存储客户、产品数据的集合路径，使用默认值products、customers即可
  • 若需要启动时自动同步Stripe控制台的产品到Firestore，需要把SYNC_STRIPE_PRODUCTS_ON_STARTUP参数值设为true（该参数默认关闭，这也是你看不到Stripe相关集合的核心原因之一）
• 修正产品同步逻辑认知
  扩展默认不会主动拉取Stripe控制台创建的产品写入Firestore：
  • 要么开启上述的启动同步参数，重启模拟器后会自动拉取产品数据生成对应集合
  • 要么按照扩展逻辑，主动在你配置的产品集合中写入带Stripe产品ID的文档，扩展会自动补全剩余元数据
• 本地测试的标准验证流程
  1. 安装并登录Stripe CLI，执行webhook转发命令，拿到返回的webhook签名密钥，替换env文件中STRIPE_WEBHOOK_SECRET的占位值
  2. 完全退出后重启Firebase模拟器，确认Functions日志中所有Stripe扩展前缀的云函数都处于监听状态
  3. 在Firestore模拟器中手动创建测试客户文档、支付会话文档，验证云函数是否正常触发、数据是否按预期流转

注意：本地测试时如果云函数触发报Stripe连接错误，检查你的本地网络是否能正常访问Stripe服务，必要时配置网络代理。

内容的提问来源于stack exchange，提问作者modi