Flutter Firebase邮箱验证链接缺失API key致页面模式无效错误

问题现象 #

验证邮件可正常发送，但链接中apiKey参数为空（示例：https://fir-test-b41e2.firebaseapp.com/__/auth/action?mode=verifyEmail&oobCode=PGEydFP0x64TYJIYU9_1mv5wR6xxW6mfMlLWF3v3fXIAAAGNgpPsyA&apiKey=&lang=en），点击后跳转至「Error encountered The selected page mode is invalid」错误页面；手动填入firebase_options.dart中的API Key后可正常完成验证。

解决步骤 #

• 检查并修复Firebase邮箱验证模板

  1. 登录Firebase控制台，进入目标项目 → 「认证」模块 → 「模板」标签页
  2. 找到「邮箱验证」模板，查看模板中的验证链接格式
  3. 确保链接包含{{apiKey}}占位符，正确的链接模板示例：

     https://{{projectId}}.firebaseapp.com/__/auth/action?mode=verifyEmail&oobCode={{oobCode}}&apiKey={{apiKey}}&lang={{lang}}
     

  4. 如果apiKey部分为空或占位符错误，替换为{{apiKey}}后保存模板。

• 确认Flutter项目Firebase配置

  • 检查firebase_options.dart中的apiKey字段，确保与Firebase控制台「项目设置」→「Web API Key」完全一致
  • 若配置文件过时，重新执行flutterfire configure命令同步最新配置。

• 重新测试验证流程
  修改模板后，在App中重新触发邮箱验证邮件发送，检查新邮件中的链接是否已自动填充正确的apiKey参数。

原因说明 #

该问题本质是Firebase验证邮件模板缺失{{apiKey}}占位符，导致生成链接时无法注入API Key参数，进而使Auth服务无法识别请求合法性。手动补充API Key后验证正常，说明链接的其他核心参数（mode、oobCode）均为有效状态。

内容的提问来源于stack exchange，提问作者sm-sayedi