Flutter结合FirebaseFirestore断网时StreamBuilder致App崩溃问题

问题核心：iPhone X真机关闭网络后，Firestore Stream抛出未处理错误导致App崩溃，模拟器无此问题，本质是Stream未处理错误+离线功能未正确生效。

解决方案步骤 #

1. 给StreamBuilder添加错误处理分支

当前代码完全未处理snapshot.hasError场景，Firestore断网时抛出的错误会直接触发未捕获异常。修改StreamBuilder：

chatList(){
    return StreamBuilder<QuerySnapshot>(
      stream: DatabaseService(uid: FirebaseAuth.instance.currentUser!.uid).getChatInfo(),
      builder: (context, snapshot){
        // 优先处理错误情况
        if(snapshot.hasError){
          // 可返回离线提示UI，或直接加载缓存的聊天列表
          return Center(child: Text('当前离线，查看本地缓存'));
        }
        if(snapshot.hasData){
          var docs = snapshot.data!.docs;
          if(docs.isNotEmpty){
            return ListView.separated(
              itemCount: docs.length,
              itemBuilder: (context, index) {
                var doc = docs[index];
                return ChatTile(
                  bondName: (doc['bondNames'][0] == userName)?  doc['bondNames'][1] : doc['bondNames'][0], 
                  chatId: doc['chatId'],
                  sender: checkSender(doc['sentById'].toString()),
                  lastMessage: doc['lastMessage'].toString(),
                  elapsedTime: calculateElapsedTime((doc['sentAt'] as Timestamp).toDate()),
                  read: doc['read'],
                  userId: userId ,
                );
              },
              separatorBuilder: (context, index) {
                return const Divider();
              },
            );
          }else{
            return noChatWidget();
          }
        }else{
          return Center(
            child: CircularProgressIndicator(
              color: Theme.of(context).primaryColor,
              )
            );
        }
      },
    );
  }

2. 强制启用Firestore离线持久化

虽然Firestore默认开启离线功能，但iOS真机可能需要明确初始化配置，确保断网时读取本地缓存：

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp();
  // 配置Firestore离线缓存
  FirebaseFirestore.instance.settings = const Settings(
    persistenceEnabled: true,
    cacheSizeBytes: Settings.CACHE_SIZE_UNLIMITED,
  );
  runApp(const MyApp());
}

3. 在Stream源头捕获错误

给getChatInfo()的Stream添加错误处理，避免错误传递到UI层：

// 示例getChatInfo方法，添加handleError
Stream<QuerySnapshot> getChatInfo() {
  return FirebaseFirestore.instance
      .collection('your-chat-collection')
      .where('participants', arrayContains: uid)
      .snapshots()
      .handleError((error) {
    debugPrint('Firestore Stream错误：$error');
    // 不抛出错误，避免崩溃
  });
}

4. 检查iOS权限配置

确保Info.plist中添加必要的网络权限，避免因权限缺失触发异常：

<key>NSAppTransportSecurity</key>
<dict>
  <key>NSAllowsArbitraryLoads</key>
  <true/>
</dict>
<key>NSLocalNetworkUsageDescription</key>
<string>需要访问网络以同步聊天数据</string>

模拟器无问题的原因 #

模拟器的网络栈与真机存在差异，Firestore在模拟器上的错误容忍度更高，且缓存机制的表现不一致，导致错误未触发崩溃。

内容的提问来源于stack exchange，提问作者Lukas Martínez