Flutter应用Firestore用户文档创建偶发失败问题求助

结合你的描述和代码，核心问题是跨区域用户在邮箱验证后，Firestore未生成对应users文档，导致进入空白首页，本地无法复现的原因大概率是地域网络延迟、Auth状态同步差异或规则/逻辑的潜在漏洞。以下是具体排查和修复方向：

1. 修复Firestore规则优先级歧义 #

当前规则中，顶层match /{document=**}的write规则会覆盖users集合的规则（Firestore规则会匹配所有适用路径，只要有一个规则拒绝就会失败）。调整规则顺序，优先处理users集合的权限，避免冲突：

rules_version = '2';

service cloud.firestore {
  match /databases/{database}/documents {
    // 优先处理users集合权限
    match /users/{userEmail} {
      allow read: if request.auth != null;
      allow write: if request.auth != null && request.auth.token.email == userEmail;
    }

    // 其他集合仅允许管理员写入
    match /{document=**} {
      allow read: if request.auth != null;
      allow write: if request.auth.token.email == 'jishnu.mehta@samskritabharatiusa.org';
    }
  }
}

2. 优化异步逻辑，避免全量查询与状态不同步 #

问题点： #

• readUser中使用usersRef.get()全量拉取所有用户文档，跨区域用户会因网络延迟导致查询超时，且无法及时检测到刚创建的用户文档；
• Auth状态同步延迟：东海岸用户调用currentUser!.reload()后，可能仍未同步到邮箱验证后的状态，导致后续操作异常。

修复代码： #

修改readUser方法，直接查询当前用户文档：

Future readUser() async {
  final currentUser = FirebaseAuth.instance.currentUser;
  if (currentUser == null) return Future.error('未找到已认证用户');

  // 直接查询当前用户的文档，替代全量查询
  final userDoc = await FirebaseFirestore.instance.collection('users').doc(currentUser.email!).get();
  
  if (userDoc.exists) {
    Map<String, dynamic> userMap = userDoc.data()!;
    String code = userMap['code'];
    await readQuizzes(code);
    appUser = AppUser.fromMap(userMap);

    for (Quiz quiz in quizzes) {
      Map<String, dynamic>? quizState = appUser.quizStates[quiz.name];
      if (quizState != null) {
        quiz.readFromState(quizState);
      }
    }
    updateMasteredQuizzes();
  } else {
    // 明确抛出错误，让FutureBuilder显示错误页，而非进入空白页
    return Future.error('用户文档不存在，请重新注册');
  }

  // 单独拉取排行榜数据，与当前用户查询分离
  final lbSnapshot = await FirebaseFirestore.instance.collection('users').get();
  lbUsers = lbSnapshot.docs
      .where((doc) => doc.id != currentUser.email!)
      .map((doc) => LeaderboardUser.fromMap(doc.data()))
      .toList();

  return Future.value(appUser);
}

给initApp添加超时处理与异常捕获：

Future<List<dynamic>> initApp() async {
  try {
    final currentUser = FirebaseAuth.instance.currentUser;
    if (currentUser == null) throw Exception('用户未完成认证');

    // 给跨区域操作添加超时，避免无限等待
    await currentUser.reload().timeout(const Duration(seconds: 10));
    await context.read<MyAppState>().readHintPages().timeout(const Duration(seconds: 10));
    
    if (widget.newUser) {
      await context.read<MyAppState>().createUserInDB().timeout(const Duration(seconds: 10));
    }
    
    await context.read<MyAppState>().readUser().timeout(const Duration(seconds: 15));

    context.read<MyAppState>().navigateTo(0);
    return [];
  } catch (e) {
    // 上报错误到Firebase Crashlytics，便于排查跨区域用户的具体问题
    FirebaseCrashlytics.instance.recordError(e, StackTrace.current, reason: 'App初始化失败');
    rethrow;
  }
}

3. 添加用户端错误日志监控 #

因为本地无法复现跨区域问题，必须在代码中添加错误上报，收集用户端的具体异常：

import 'package:firebase_crashlytics/firebase_crashlytics.dart';

// 在createUserInDB中添加日志
Future createUserInDB() async {
  final userRef = FirebaseFirestore.instance.collection('users').doc(
        FirebaseAuth.instance.currentUser!.email!,
      );
  try {
    await userRef.set({
      'name': appUser.name,
      'quizStates': {},
      'lbPoints': 0,
      'seshHistory': {},
      'code': 'choose',
    });
    return Future.value();
  } catch (error) {
    FirebaseCrashlytics.instance.recordError(error, StackTrace.current, reason: '创建用户文档失败');
    return Future.error('(From createUserInDB) $error');
  }
}

4. 检查Firebase项目区域设置 #

如果你的Firestore数据库部署在西海岸（如us-west2），东海岸用户会有明显的网络延迟。建议：

• 将Firestore切换为多区域部署，覆盖北美地区；
• 检查Firebase Auth的区域配置，确保用户验证后的状态同步更快。

5. 验证newUser参数准确性 #

添加日志确认widget.newUser的传递是否正确：

// 在initApp开头添加
FirebaseCrashlytics.instance.log('InitApp: newUser = ${widget.newUser}');

如果newUser被错误标记为false，会直接跳过createUserInDB步骤，导致无用户文档。

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