Flutter Web Firebase手机号认证遭遇reCAPTCHA相关报错问题

遇到的问题 #

• 未添加captchaVerifier时，触发报错[firebase_auth/invalid-app-credential]，提示：手机号验证请求包含无效应用验证器，reCAPTCHA令牌响应无效或过期。
• 添加captchaVerifier后，先出现提示Failed to initialize reCAPTCHA Enterprise config. Triggering the reCAPTCHA v2 verification.，随后触发报错[firebase_auth/internal-error]。

用户核心代码：

Future<ConfirmationResult> authViaPhoneNo({
  required String phoneNo,
}) async {
  return auth.signInWithPhoneNumber(phoneNo, captchaVerifier);
}

Future<User?> verifyOTP({
  required ConfirmationResult result,
  required String otp,
}) async {
  final credential = await result.confirm(otp);
  return credential.user;
}

final captchaVerifier = RecaptchaVerifier(
    container: 'recaptcha-container',
    size: RecaptchaVerifierSize.compact,
    theme: RecaptchaVerifierTheme.dark,
    auth: FirebaseAuthPlatform.instance,
);

已在index.html中添加<div id="recaptcha-container"></div>。

排查与解决步骤 #

1. 确保DOM容器加载时机正确 #

reCAPTCHA验证依赖已挂载到DOM的容器，若容器未加载完成就初始化captchaVerifier，会导致验证失败。Flutter Web项目可延迟初始化：

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp(options: DefaultFirebaseOptions.currentPlatform);
  // 等待DOM完全加载
  await Future.delayed(const Duration(milliseconds: 300));
  runApp(const MyApp());
}

2. 修正captchaVerifier的Auth实例引用 #

避免直接使用FirebaseAuthPlatform.instance，改用初始化后的FirebaseAuth实例，确保上下文正确：

final FirebaseAuth auth = FirebaseAuth.instance;
final captchaVerifier = RecaptchaVerifier(
  container: 'recaptcha-container',
  size: RecaptchaVerifierSize.compact,
  theme: RecaptchaVerifierTheme.dark,
  auth: auth,
);

3. 检查Firebase控制台配置 #

• 进入项目Authentication > 登录方法，确认手机号登录已启用。
• 切换到reCAPTCHA Enterprise标签，若配置异常可暂时切换为reCAPTCHA v2模式；若使用Enterprise，确保已正确配置Web应用的reCAPTCHA密钥。
• 验证Web应用的firebaseConfig参数（apiKey、authDomain等）与控制台完全一致。

4. 区分测试手机号与普通手机号逻辑 #

Firebase官方测试手机号（如+16505550101等）无需reCAPTCHA验证，可做分支处理：

Future<ConfirmationResult> authViaPhoneNo({required String phoneNo}) async {
  // 匹配Firebase官方测试手机号前缀
  if (phoneNo.startsWith('+1650555')) {
    return auth.signInWithPhoneNumber(phoneNo);
  } else {
    return auth.signInWithPhoneNumber(phoneNo, captchaVerifier);
  }
}

5. 捕获详细错误信息定位问题 #

添加错误捕获，打印完整错误栈便于排查深层原因：

Future<ConfirmationResult> authViaPhoneNo({required String phoneNo}) async {
  try {
    return auth.signInWithPhoneNumber(phoneNo, captchaVerifier);
  } catch (e, stackTrace) {
    print('手机号认证错误详情: $e');
    print('错误调用栈: $stackTrace');
    rethrow;
  }
}

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