Firestore读取2万+文件报FAILED_PRECONDITION错误最佳实践咨询

9 FAILED_PRECONDITION: The requested snapshot version is too old是Firestore一致性快照机制的固有约束：所有默认的读请求（全量get、原生stream）都会在请求发起时绑定一个固定版本的数据库快照，Firestore后台只会保留近期的快照版本用于一致性读，当查询总耗时过长、读取数据量过大时，绑定的旧快照会被垃圾回收清理，直接触发该报错。2万+文档量级的读取触发该问题属于典型的请求模式不匹配，和权限、代码语法无关。

• 直接全量调用get()：单次请求绑定的快照有效期通常在60s以内，2万+文档的拉取、序列化、传输耗时极容易超过该阈值，失败是必然结果。
• 直接调用官方原生stream接口：默认stream实现依然绑定请求发起时的单版本快照，没有内置分片重连、快照续传逻辑，当网络波动、Firestore后台负载升高导致拉取速度变慢时，就会触发快照过期，因此会出现偶发成功、偶发失败的现象——拉取速度够快就成功，速度稍慢就失败，没有稳定性可言。

方案1：游标分页读取（通用在线场景首选，稳定性100%） #

搭配limit()做分页的方向完全可行，但必须搭配文档游标（startAfter） 实现，绝对不能用offset分页——offset会前置扫描跳过的所有文档，数据量越大查询越慢，反而会加剧超时问题。
实操配置：

• 单批次limit值设置为300-500，最大不要超过1000，避免触发单请求10MB的响应大小限制
• 每一批次查询独立发起，每次请求会生成新的快照，从根本上规避快照过期问题
• 批次之间增加100-200ms的间隔，避免触发Firestore的读频率限流
  参考实现（服务端JS SDK为例）：

let lastCursor = null
const BATCH_SIZE = 500
const result = []

do {
  let query = db.collection('your_target_collection').limit(BATCH_SIZE)
  if (lastCursor) {
    query = query.startAfter(lastCursor)
  }
  const batchRes = await query.get()
  batchRes.forEach(doc => result.push(doc.data()))
  // 更新游标为当前批次最后一条文档
  lastCursor = batchRes.docs.at(-1)
  // 加间隔防限流
  await new Promise(resolve => setTimeout(resolve, 150))
} while (lastCursor)

如果查询带筛选条件，提前给筛选、排序字段建好复合索引，避免单批次查询耗时过长。

方案2：托管导出（全量离线分析场景首选） #

如果需求是定期全量拉取集合做离线分析、数据同步，不要用SDK在线硬拉，直接调用Firestore内置的托管导出功能，将全量数据导出到对应云存储桶后再读取，亿级文档量级也能稳定运行，成本比在线查询低70%以上，完全不需要自己处理分页、重试逻辑。

方案3：优化后的流式读取 #

如果业务场景必须用流式读取，需要手动修改SDK配置：调小单流的批次拉取大小、打开内置的幂等重试开关，确保单次流持有快照的时长不超过30s，该方案稳定性弱于游标分页，仅作为兼容选项。

• 不要盲目调大单批次大小，单批次超过1000文档后，触发响应大小限制、查询超时的概率会指数级上升
• 数据拉取和业务处理逻辑解耦，拉取到的数据先写入本地缓存/临时存储，再做后续转换处理，减少请求链路的总耗时
• 服务端跑批量读任务时，不要用短超时的运行环境（比如默认配置的云函数，超时仅1min），至少配置5min以上的执行超时

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