Firestore addSnapshotListener 行为确认：回调返回所有匹配文档还是仅新插入文档？

你观察到的这个行为是完全正确且有官方保障的，这正是Firestore addSnapshotListener 针对查询监听的设计逻辑。

核心行为说明 #

addSnapshotListener 对于查询的监听遵循两个关键规则：

1. 首次触发：当你刚注册这个监听器时，它会立即返回当前查询条件匹配的所有文档的完整快照，也就是所有符合status: success且trashed: false的现有文档。
2. 数据更新触发：每当有数据变化（插入、更新、删除符合查询条件的文档）时，监听器会再次返回当前时刻所有符合查询条件的完整文档集合，而不是只返回变化的单个/部分文档。

所以你看到的「新文档插入时，新文档+所有现有匹配文档都被返回」的现象，是完全符合预期的行为。

如何仅处理增量变化？ #

如果你的业务只需要关注新增/修改/删除的文档（而不是每次都处理全量集合），可以通过QuerySnapshot的documentChanges属性来区分具体的变化类型，而不是直接遍历所有documents。比如在你的回调里可以这样修改：

guard let querySnapshot = querySnapshot else {
    print("No documents or an error occurred: \(error?.localizedDescription ?? "Unknown error")")
    return
}

// 遍历变化的文档，区分操作类型
for change in querySnapshot.documentChanges {
    switch change.type {
    case .added:
        // 新增的文档（包括首次监听时的所有文档，以及后续插入的新文档）
        let noteData = change.document.data()
        print("新增文档: \(noteData)")
    case .modified:
        // 被修改的文档
        let updatedNote = change.document.data()
        print("修改文档: \(updatedNote)")
    case .removed:
        // 被删除的文档（或不再符合查询条件的文档）
        let removedNote = change.document.data()
        print("移除文档: \(removedNote)")
    }
}

这里需要注意：首次监听时，所有现有匹配文档都会以.added类型出现在documentChanges中；之后的增量更新里，只有真正变化的文档会出现在这个列表里，对应各自的操作类型。

总结 #

你遇到的行为是Firestore查询监听器的标准、预期行为，官方会持续保障这个逻辑的一致性。如果需要全量数据就直接用documents属性，如果需要增量处理就用documentChanges来区分操作类型。

备注：内容来源于stack exchange，提问作者Cheok Yan Cheng