Flutter查询Firestore已存数据时返回null报类型转换错误

• 报错的直接原因是DocumentSnapshot的data()方法返回了Null，直接用as Map<String, dynamic>做非空强转，就会触发类型不匹配的_CastError。
• 根本原因是当前查询条件没有命中Firestore中真实存在的文档，不存在的文档快照调用data()会默认返回null。常见触发场景包括：
  • 传入的集合名collectionName和控制台实际集合名不匹配，存在大小写错误、多余空格、拼写错误
  • 传入的文档IDdocId错误，比如传了空值、传了文档内的普通业务字段而非真实文档ID
  • Firestore安全规则拦截了当前用户的读请求，未授权的查询会返回空文档快照而非抛出明确的权限错误

• 增加文档存在性校验，不要拿到文档快照直接做类型强转，同时增加异常捕获逻辑，修复后的参考代码如下：

Future<Map<String, dynamic>?> getDocumentInfo(String collectionName, String docId) async {
  try {
    DocumentSnapshot document = await FirebaseFirestore.instance
        .collection(collectionName)
        .doc(docId)
        .get();
    // 先校验文档是否真实存在
    if (document.exists) {
      final docData = document.data();
      if (docData != null) {
        return docData as Map<String, dynamic>;
      }
    }
    print("查询失败：对应路径文档不存在或数据为空");
    return null;
  } catch (e) {
    print("拉取Firestore文档异常：$e");
    return null;
  }
}

• 完成路径与权限排查
  • 逐字符核对传入的集合名和Firestore控制台的集合名完全一致，如果查询的是子集合，要补全所有上级文档的路径层级
  • 核对传入的docId和控制台目标文档的ID完全匹配，如果存数据时是Firestore自动生成的ID，不要手动传入自定义业务字段作为查询条件
  • 检查Firestore安全规则，确认当前应用的登录身份拥有目标集合的读权限，避免权限拦截导致返回空结果

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