Flutter使用StreamBuilder监听Cloud Firestore触发RangeError错误如何解决

报错原因 #

RangeError (index): Invalid value: Valid value range is empty: 0 报错的核心原因是Stream返回的QuerySnapshot的docs集合为空，你直接访问索引[0]触发越界。导致docs为空的直接原因是Firestore筛选逻辑错误，同时还有多处代码不规范问题共同触发故障。

具体修复步骤 #

1. 修正LevelService的getLevel方法 #

你写的level.where('Level', isEqualTo: 1-6)实际是筛选Level等于-5（1减6的计算结果），同时完全过滤了你初始化设置的Level=0的记录，自然查不到任何数据。改成仅按用户ID筛选即可，等级后续自行判断：

Stream<QuerySnapshot> getLevel() {
  return userTodos.where('userID', isEqualTo: userID).snapshots();
}

2. 增加docs非空判断，禁止直接访问索引0 #

在StreamBuilder中拿到snapshot后，先判断docs是否有数据，再读取等级字段：

if (snapshot.hasData) {
  // 先判断docs非空，避免越界
  if (snapshot.data!.docs.isEmpty) {
    return const Center(child: CircularProgressIndicator());
  }
  final userDoc = snapshot.data!.docs.first;
  final int userLevel = userDoc.get('Level') as int;
  // 后续等级判断逻辑
}

3. 修正Build过程中调用导航的错误 #

不能在builder函数中直接执行Navigator.push，要放到帧渲染完成后的回调里，避免渲染异常：

if (userLevel == 1) {
  WidgetsBinding.instance.addPostFrameCallback((_) {
    Navigator.push(context, MaterialPageRoute(builder: (context) => const ToDo1F()));
  });
} else if (userLevel == 2) {
  WidgetsBinding.instance.addPostFrameCallback((_) {
    Navigator.push(context, MaterialPageRoute(builder: (context) => const ToDo2F()));
  });
}
// 其他等级逻辑同理

4. 统一字段大小写，避免匹配失败 #

Firestore字段是大小写敏感的，你代码中存在大量大小写不一致的问题，需要统一：

• 初始化时setLevel('level', 0)的字段名是小写level，和后续读取、更新用的大写Level不匹配，统一改为Level
• select方法中key == 'level 3'是小写l，其他都是大写L，修正为'Level 3'
• updateUser方法中一会传'Level'一会传'level'，统一改为'Level'
• 初始化创建用户文档时，记得写入userID字段，否则按userID筛选也会查不到数据

5. 可选优化：直接监听单文档而非集合 #

如果每个用户对应一条记录，直接用用户ID作为文档ID，监听单文档比监听集合更高效：

// LevelService中新增方法
Stream<DocumentSnapshot> getUserLevelDoc() {
  return userTodos.doc(userID).snapshots();
}

对应StreamBuilder的泛型改成AsyncSnapshot<DocumentSnapshot>，读取数据更方便。

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