解决React-Email、Resend与Firebase Cloud Functions部署报错问题

常见问题及对应解决步骤 #

1. 依赖配置错误 #

• React-Email相关依赖（@react-email/components、react-email）必须放在functions/package.json的dependencies中，不能放在devDependencies——云函数运行时需要这些依赖才能正常执行。
• 如果使用ES模块语法，需在functions/package.json中添加"type": "module"，同时确保所有导入导出语法符合ES规范。

2. 模板路径引用问题 #

• 你当前用相对路径../../react-email/emails/EmailVerification导入模板，需确认目录结构是否匹配。若打包时无法解析该路径，可尝试：
  • 将React-Email模板文件复制到functions目录下，改用本地相对路径导入；
  • 借助process.cwd()拼接绝对路径，比如：

    import path from 'path';
    import EmailVerificationTemplate from path.join(process.cwd(), 'react-email/emails/EmailVerification');
    

3. 环境变量未配置 #

• 代码中直接使用的RESEND_API_KEY未在Firebase环境中配置，需执行以下命令添加：

  firebase functions:config:set resend.api_key="你的Resend API密钥"
  

• 然后在代码中通过Firebase配置获取密钥：

  import * as functions from "firebase-functions";
  // ...
  const resend = new Resend(functions.config().resend.api_key);
  

4. Node.js版本与渲染兼容性 #

• 确保functions/package.json中指定的Node.js版本在Firebase支持范围内（比如18或20），添加如下配置：

  "engines": {
    "node": "18"
  }
  

• 检查邮件模板是否包含浏览器特定API（如window），这类API在Node.js环境中无法运行，需移除或替换为Node.js兼容代码。

5. 打包与部署配置问题 #

• 在firebase.json中确认functions.source指向正确的函数目录，确保打包时包含所有必要文件；
• 先在functions目录下执行npm run build，排查本地编译错误，再执行部署命令。

6. 权限与配额问题 #

• 检查Resend API密钥是否有效、发送额度是否充足；
• 确保云服务账号拥有Firestore读取权限（函数需要读取emailVerifications集合的文档数据）；
• 查看Firebase项目的Functions配额是否满足部署需求。

通用排查流程 #

1. 本地测试：执行firebase emulators:start --only functions，手动触发Firestore文档创建事件，查看控制台输出的错误信息；
2. 查看详细日志：执行firebase deploy --only functions --debug，通过debug日志定位具体报错点。

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