Flutter Firestore模拟器中查询监听器重复触发的原因

问题场景 #

我有一个Flutter组件，同时监听两个Firestore查询：

class ExampleWidget extends StatefulWidget {
  const ExampleWidget({super.key});

  @override
  State<ExampleWidget> createState() => _ExampleWidgetState();
}

class _ExampleWidgetState extends State<ExampleWidget> {
  @override
  void initState() {
    FirebaseFirestore.instance
        .collection('items')
        .where('tags', arrayContains: 'foo')
        .snapshots()
        .listen(
            (items) => print('Got items from query 1: ${items.docs.length}'));

    FirebaseFirestore.instance
        .collection('items')
        .snapshots()
        .listen(
            (items) => print('Got items from query 2: ${items.docs.length}'));

    super.initState();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(body: Center(child: Text('Example')));
  }
}

组件在main.dart中直接渲染：

Future<void> main() async {
  await Firebase.initializeApp(options: DefaultFirebaseOptions.currentPlatform);
  FirebaseFirestore.instance.useFirestoreEmulator('localhost', 8080);
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter Demo',
      theme: ThemeData(primarySwatch: Colors.blue),
      home: ExampleWidget(),
    );
  }
}

现有Firestore数据：

items:
  item#1:
    tags: ['foo']
  item#2:
    tags: ['foo']
  item#3:
    tags: ['bar']

生产环境运行时日志符合预期：

Got items from query 1: 2
Got items from query 2: 3

但在Firebase模拟器中运行时，第二个查询的监听器触发了两次：

Got items from query 1: 2
Got items from query 2: 2
Got items from query 2: 3

原因分析 #

• 模拟器缓存机制差异：Firestore模拟器在初始化阶段，会先返回本地缓存的旧数据（如果存在），再同步返回最新的服务器数据；而生产环境的Firestore SDK默认策略会优先返回最新数据，不会触发两次快照。
• 全集合查询的初始化流程：第二个查询是全集合查询，模拟器启动后可能先加载了部分缓存数据（比如前两个文档），待完整数据同步完成后，再次触发快照更新。
• 模拟器调试特性：Firestore模拟器为了方便调试，其本地缓存逻辑和生产环境的离线缓存不完全一致，初始化时的额外同步步骤会导致监听器收到多次回调。

解决方法 #

1. 禁用本地缓存 #

在初始化Firestore时关闭持久化缓存，避免模拟器返回缓存数据：

Future<void> main() async {
  await Firebase.initializeApp(options: DefaultFirebaseOptions.currentPlatform);
  // 禁用本地缓存
  FirebaseFirestore.instance.settings = const Settings(persistenceEnabled: false);
  FirebaseFirestore.instance.useFirestoreEmulator('localhost', 8080);
  runApp(const MyApp());
}

2. 过滤重复快照 #

使用distinct()操作符，只处理内容发生实际变化的快照，忽略重复回调：

FirebaseFirestore.instance
    .collection('items')
    .snapshots()
    // 对比前后快照的文档长度与内容，过滤重复
    .distinct((prev, curr) {
      if (prev.docs.length != curr.docs.length) return false;
      return prev.docs.every((doc) => curr.docs.any((currDoc) => 
        currDoc.id == doc.id && currDoc.data().toString() == doc.data().toString()
      ));
    })
    .listen((items) => print('Got items from query 2: ${items.docs.length}'));

3. 重置模拟器数据 #

每次启动模拟器前，通过Firebase CLI执行重置命令，清空残留的缓存数据：

firebase emulators:start --import=./empty-data

（提前创建一个空的empty-data目录，用于初始化干净的模拟器环境）

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