Firestore查询报错：Bad state: DocumentSnapshotPlatform中字段不存在

我尝试从Firestore的clients集合中获取数据，但每次运行代码都会报错："Unhandled Exception: Bad state: field does not exist within the DocumentSnapshotPlatform"，无法获取任何数据。相关代码如下：

class EnterRefferal extends StatefulWidget {
  @override
  _EnterRefferalState createState() => _EnterRefferalState();
}
class _EnterRefferalState extends State<EnterRefferal> {
  List<String> refId = [];
  void initState() {
    super.initState();
    FirebaseFirestore.instance
        .collection("clients")
        .get()
        .then((QuerySnapshot querySnapshot) => {
              setState(() {
                querySnapshot.docs.forEach((doc) {
                  refId.addAll([doc["refID"]]);
                });
              }),
            });
  }
  @override
  Widget build(BuildContext context) {
    print(refId);
}

问题分析与解决方法 #

1. 先排查字段名拼写问题 #

Firestore的字段名是大小写敏感的！你代码里写的是doc["refID"]，先去Firestore控制台确认clients集合下的文档里，字段名是不是和这个完全一致——比如实际字段是refId、RefID或者referralId，都会导致找不到字段触发报错。

2. 处理部分文档缺失字段的情况 #

如果clients集合里有部分文档没有refID字段，直接用doc["refID"]访问就会抛出异常。可以改用get方法并设置默认值，安全获取字段：

querySnapshot.docs.forEach((doc) {
  var id = doc.get("refID", defaultValue: null);
  if (id != null) {
    refId.add(id.toString());
  }
});

这样即使字段不存在，也不会报错，还能过滤掉无效的null值。

3. 优化异步数据的状态管理 #

你当前在initState里手动处理异步请求，第一次build时refId还是空列表，而且没有错误处理逻辑。推荐用FutureBuilder来更优雅地处理异步加载：

@override
Widget build(BuildContext context) {
  return FutureBuilder<QuerySnapshot>(
    future: FirebaseFirestore.instance.collection("clients").get(),
    builder: (context, snapshot) {
      // 加载中状态
      if (snapshot.connectionState == ConnectionState.waiting) {
        return const CircularProgressIndicator();
      }
      // 捕获错误
      if (snapshot.hasError) {
        return Text("加载失败: ${snapshot.error}");
      }
      // 处理有效数据
      List<String> refId = snapshot.data!.docs
          .map((doc) => doc.get("refID", defaultValue: null))
          .where((id) => id != null)
          .cast<String>()
          .toList();
      
      print(refId);
      return Text("共获取到${refId.length}个推荐ID"); // 替换成你的实际UI组件
    },
  );
}

这种方式能自动处理加载、错误、成功三种状态，避免手动管理setState的繁琐。

4. 检查Firestore安全规则 #

如果安全规则没有允许读取clients集合，可能会导致获取的数据不完整甚至字段缺失。测试阶段可以先临时放开权限（上线后记得改成符合业务需求的规则）：

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    match /clients/{document} {
      allow read: if true;
      allow write: if request.auth != null;
    }
  }
}

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