Firestore Stream创建异常：where子句报错及无数据返回求助

问题现象 #

基于Firestore对象快照创建Stream时遇到两个异常：

• 不添加where子句时，流无任何数据返回
• 添加where子句则抛出Firestore错误，无法定位原因
  注：已排除fromJson参数问题，因为其他获取单个Habit的函数可正常运行

问题函数 #

该函数存在异常：注释where子句时代码可运行但无数据输出；取消注释任意where子句则触发Firestore错误：

Stream<List<Habit>> loadActiveHabitsByUser(String userId) {
    _log.v('Trying to load all active habits by userId: $userId');
    int count = 0;
    try {
      return _habitCollectionReference
          // .where('userId' == userId)
          //  .where('isActive' == true)
          .snapshots()
          .map((snapshots) => snapshots.docs.map((doc) {
                count++;
                Habit result = doc.data() as Habit;
                _log.v('Habit with Id ${result.id} is habit #$count');
                return result;
              }).toList());
    } catch (error) {
      _log.v('A firestore error occurred loading active habits: $error');
      throw error;
    }
  }

报错信息 #

添加任意where子句时触发如下错误：

The following assertion was thrown building HomeView:
Supported [field] types are [String] and [FieldPath].
'package:cloud_firestore/src/query.dart':
Failed assertion: line 311 pos 7: 'field is String || field is FieldPath || field ==
FieldPath.documentId'

支持代码 #

函数使用的集合引用定义：

final CollectionReference _habitCollectionReference =
      FirebaseFirestore.instance.collection('habits').withConverter<Habit>(
          fromFirestore: (snapshot, _) => Habit.fromJson(
                snapshot.id,
                snapshot.data()!,
              ),
          toFirestore: (habit, _) => habit.toJson());

同一类中可正常运行的单个文档查询函数：

Future<Habit> loadHabit({required String id}) async {
    var ref = _habitCollectionReference.doc(id);

    final Habit habit = (await ref.get()).data()! as Habit;

    return habit;
  }

解决方案 #

1. where子句语法错误修复 #

报错核心原因是where方法调用语法错误：你把条件判断写在了where的参数位置，正确用法是传入字段名+匹配条件。

修改后的where子句代码：

return _habitCollectionReference
    .where('userId', isEqualTo: userId)
    .where('isActive', isEqualTo: true)
    .snapshots()
    // 后续map逻辑保持不变

2. 无数据返回问题排查 #

注释where子句后流无数据，可能的原因及排查步骤：

• 集合无数据：直接在Firebase控制台查看habits集合是否存在文档
• 权限规则限制：Firestore安全规则可能不允许当前用户读取整个集合，但单个文档查询因指定ID符合规则。可临时放宽规则（仅测试用）验证
• 文档转换异常：集合中可能存在不符合Habit结构的文档，导致转换失败但被外层try-catch捕获。可在map逻辑中添加局部错误捕获排查：

.map((snapshots) => snapshots.docs.map((doc) {
    count++;
    try {
        Habit result = doc.data() as Habit;
        _log.v('Habit with Id ${result.id} is habit #$count');
        return result;
    } catch (e) {
        _log.e('Failed to parse habit ${doc.id}: $e');
        return null;
    }
}).whereType<Habit>().toList()); // 过滤转换失败的null值

内容的提问来源于stack exchange，提问作者Charlie Page