Flutter Firebase QuerySnapshot未定义documents getter报错解决

该报错是 cloud_firestore 插件升级到 2.0.0 及以上版本后的破坏性变更导致：旧版本中QuerySnapshot类用于获取查询结果文档列表的documents getter 已被官方移除，替换为新的docs属性实现对应能力。

核心替换规则 #

将所有代码中调用QuerySnapshot对象的.documents属性，替换为.docs即可。

不同场景的写法示例 #

1. 普通查询取数据 #

旧错误写法（SDK升级后已失效）：

QuerySnapshot snapshot = await FirebaseFirestore.instance.collection('users').get();
List<DocumentSnapshot> userList = snapshot.documents;

新正确写法：

QuerySnapshot snapshot = await FirebaseFirestore.instance.collection('users').get();
// 替换 documents 为 docs
List<QueryDocumentSnapshot> userList = snapshot.docs;

2. 遍历查询结果 #

旧错误写法：

snapshot.documents.forEach((doc) {
  print(doc['username']);
});

新正确写法：

snapshot.docs.forEach((doc) {
  print(doc['username']);
});

3. StreamBuilder 实时监听场景 #

旧错误写法：

StreamBuilder<QuerySnapshot>(
  stream: FirebaseFirestore.instance.collection('users').snapshots(),
  builder: (context, snapshot) {
    if (!snapshot.hasData) return const CircularProgressIndicator();
    // 旧写法使用 documents
    final userDocs = snapshot.data.documents;
    return ListView(
      children: userDocs.map((doc) => Text(doc['username'] as String)).toList(),
    );
  },
)

新正确写法：

StreamBuilder<QuerySnapshot>(
  stream: FirebaseFirestore.instance.collection('users').snapshots(),
  builder: (context, snapshot) {
    if (!snapshot.hasData) return const CircularProgressIndicator();
    // 替换为 docs
    final userDocs = snapshot.data.docs;
    return ListView(
      children: userDocs.map((doc) => Text(doc['username'] as String)).toList(),
    );
  },
)

注意事项 #

• docs 属性返回的类型为List<QueryDocumentSnapshot>，相比旧版的List<DocumentSnapshot>类型更严谨，代表查询返回的文档一定存在，不需要额外做空值校验。
• 同版本升级的连带变更：旧版中DocumentSnapshot.data是无参 getter，新版改为需要调用的方法data()，如果替换docs后仍出现报错，需要同步将该部分写法从doc.data改为doc.data()。

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