Skip to main content
成功的 抓取 会告诉你页面返回了什么,但不能证明页面所反映的状态仍然有效。这是两个不同的问题。
  • 新鲜度 → 内容是最新的,还是复用了 Firecrawl 缓存中的副本?由 maxAge 控制。
  • 存活状态 → 底层对象是否仍然存在且处于活跃状态?你的应用需要根据现有证据自行判断。
本指南将解释两者的区别,介绍 maxAge 的权衡,并为对新鲜度敏感的操作提供检查清单和示例。

快速对比


新鲜度与性能的权衡 (maxAge)

Firecrawl 会缓存之前抓取的页面,并在有可用副本时返回较新的副本,从而降低延迟。maxAge 指 Firecrawl 可以返回缓存副本而非重新获取页面时,该缓存副本允许的最大时长 (以毫秒为单位) 。
  • 省略 maxAge:Firecrawl 可能会返回最近缓存的内容。默认时间窗口为 2 天;对于某些网站,Firecrawl 可能会使用不同的时间窗口。
  • 设置 maxAge: 0:Firecrawl 会跳过该请求的缓存并重新获取页面。这会以延迟和可靠性为代价,换取更新鲜的结果。
默认应启用缓存。仅在内容过期会导致错误或高成本决策的读取操作中承担 maxAge: 0 带来的延迟成本——它不会改变该页面消耗的额度。 当 Firecrawl 针对该请求考虑使用缓存时,会返回 metadata.cacheState,因此在调整 maxAge 时可用它进行检查。maxAge: 0 的响应中不会包含它,因为该请求会完全跳过缓存。 有关缓存机制、常见的 maxAge 值、缓存命中匹配规则,以及会自动绕过缓存的请求选项,请参见快速抓取

maxAge 的适用位置

如果需要重新获取通过 /search 找到的页面,请使用 /scrape 并设置 maxAge: 0,再次抓取该 URL。

新鲜度不代表存活状态

即使设置了 maxAge: 0,结果也只能反映页面在该次获取时返回的内容。页面可能返回包含内容的 HTTP 200,但其实际状态可能已过时、不可用或发生其他变化。 因此,状态码和内容是否存在都无法判断页面是否处于存活状态。存活状态需要由你的应用根据特定来源的证据来判断。

对新鲜度敏感的操作的检查清单

在执行依赖当前状态的操作前,应将抓取输出视为证据,而非确证
  1. 最终获取时使用 maxAge: 0,确保响应不会从缓存中返回。
  2. 不要将 HTTP 200 或非空内容视为资源仍处于存活状态的证明。
  3. 检查渲染后的内容和重定向迹象。 metadata.sourceURL 是你请求的 URL;metadata.url 是引擎在响应中报告的 URL。两者不同时,可能表示发生了重定向,跳转至其他资源。两者相同也不能证明未发生重定向。
  4. 尽可能优先使用来源专用的 API 或标识符——它们通常会提供渲染页面中看不到的明确状态。
  5. 将无法判定的证据视为 unknown,不要假定其仍处于活跃状态;应在执行成本高昂或不可逆的步骤前停止。

实战示例:收集当前页面证据

跳过缓存,然后收集渲染后的内容和响应元数据,供应用程序根据自身的验证规则进行判断。抓取只提供证据;不会决定特定领域的状态。
关键分界点在于收集完成后:Firecrawl 提供页面证据;应用程序根据针对来源的规则来解读这些证据。如果这些规则无法得出结论,请将状态保持为 unknown

按场景的建议


要点总结

  1. 新鲜度和存活状态是两个不同的问题。 maxAge 控制新鲜度;存活状态则需你根据证据自行判断。
  2. HTTP 200 和内容并不能证明所表示的状态仍是最新状态。
  3. 对于对新鲜度敏感的操作,请使用 maxAge: 0 并遵循检查清单。 检查渲染后的内容,对比 metadata.urlmetadata.sourceURL 以查找可能的重定向迹象,并优先使用特定来源的 API。
  4. 将无法定论的证据视为 unknown 仅凭一次 抓取 绝不能将对象标记为 active;在执行成本高昂或不可逆的步骤前停止。
  5. Firecrawl 没有存活状态字段。 你的应用应根据自身领域的定义作出判断。

延伸阅读