FlutterFire iOS 端 Firebase 手机验证码登录问题分析与解决方案

问题背景

在使用 FlutterFire 插件进行 Firebase 手机验证码登录功能时，部分开发者反馈在 iOS 平台升级到 firebase_auth 5.2.0 版本后出现了验证失败的问题。具体表现为调用 verifyPhoneNumber 方法时抛出 FirebaseAuthException 异常，错误信息为 "Token mismatch"。

问题表现

当开发者尝试使用以下代码进行手机验证时：

FirebaseAuth.instance.verifyPhoneNumber(
  phoneNumber: phoneNumber,
  codeSent: (verificationId, forceResendToken) {
    print('code sent');
    codeSent(verificationId, forceResendToken);
  },
  verificationCompleted: verificationCompleted,
  timeout: const Duration(seconds: 30),
  verificationFailed: (e) => verificationFailed(e),
  codeAutoRetrievalTimeout: (verificationId) =>
      codeAutoRetrievalTimeout(verificationId));

在 iOS 设备上会收到 "Token mismatch" 错误，而同样的代码在 Android 设备上工作正常。值得注意的是，这个问题在模拟器上可以正常工作，但在真机上会出现问题。

技术分析

根本原因

这个问题主要与 Firebase Auth 在 iOS 平台上处理推送通知认证的方式有关。Firebase Auth 使用静默推送通知来验证设备，当这个机制出现问题时，系统应该回退到 reCAPTCHA 验证流程。但在 5.2.0 版本中，这个回退机制似乎没有正确触发。

版本对比

• 正常工作版本：

  • firebase_auth: 5.1.4
  • firebase_core: 3.3.0

• 出现问题版本：

  • firebase_auth: 5.2.0
  • firebase_core: 3.4.0

解决方案

临时解决方案

1. 降级版本：暂时回退到已知可用的版本组合

   firebase_auth: 5.1.4
   firebase_core: 3.3.0
   

2. 配置检查：确保以下配置正确

   • 在 Xcode 中添加 Push notification 和 Background modes 能力
   • 在 Apple Developer 页面生成 APNs 认证密钥并上传到 Firebase
   • 检查 Runner.entitlements 文件中的 aps-environment 设置

完整修复方案

1. AppDelegate 配置：确保正确处理推送通知

   import UIKit
   import Flutter
   import FirebaseCore
   import FirebaseMessaging
   
   @UIApplicationMain
   class AppDelegate: FlutterAppDelegate {
     override func application(_ application: UIApplication, 
       didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
       Messaging.messaging().setAPNSToken(deviceToken, type: .unknown)
     }
   
     override func application(
       _ application: UIApplication,
       didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
     ) -> Bool {
       FirebaseApp.configure()
       GeneratedPluginRegistrant.register(with: self)
       return super.application(application, didFinishLaunchingWithOptions: launchOptions)
     }
   }
   

2. Entitlements 文件检查：确保 aps-environment 设置正确

   <key>aps-environment</key>
   <string>unknown</string>
   

最佳实践建议

1. 测试环境验证：在开发阶段同时测试模拟器和真机环境
2. 版本升级策略：在升级 Firebase 相关依赖时，建议逐步升级并测试核心功能
3. 错误处理：完善 verifyPhoneNumber 方法的错误处理逻辑，提供友好的用户提示
4. 监控机制：实现 Firebase 性能监控，及时发现认证流程中的异常

总结

这个问题的核心在于 Firebase Auth 在 iOS 平台上处理推送通知认证的机制变化。虽然可以通过降级暂时解决问题，但建议开发者按照完整修复方案检查配置，以确保在后续版本升级时能够平滑过渡。同时，这也提醒我们在集成第三方服务时，需要充分理解其底层工作机制，才能快速定位和解决问题。