- 新鲜度 → 内容是最新的,还是复用了 Firecrawl 缓存中的副本?由
maxAge控制。 - 存活状态 → 底层对象是否仍然存在且处于活跃状态?你的应用需要根据现有证据自行判断。
maxAge 的权衡,并为对新鲜度敏感的操作提供检查清单和示例。
快速对比
新鲜度与性能的权衡 (maxAge)
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,但其实际状态可能已过时、不可用或发生其他变化。
因此,状态码和内容是否存在都无法判断页面是否处于存活状态。存活状态需要由你的应用根据特定来源的证据来判断。
对新鲜度敏感的操作的检查清单
- 最终获取时使用
maxAge: 0,确保响应不会从缓存中返回。 - 不要将 HTTP 200 或非空内容视为资源仍处于存活状态的证明。
- 检查渲染后的内容和重定向迹象。
metadata.sourceURL是你请求的 URL;metadata.url是引擎在响应中报告的 URL。两者不同时,可能表示发生了重定向,跳转至其他资源。两者相同也不能证明未发生重定向。 - 尽可能优先使用来源专用的 API 或标识符——它们通常会提供渲染页面中看不到的明确状态。
- 将无法判定的证据视为
unknown,不要假定其仍处于活跃状态;应在执行成本高昂或不可逆的步骤前停止。
实战示例:收集当前页面证据
unknown。
按场景的建议
要点总结
-
新鲜度和存活状态是两个不同的问题。
maxAge控制新鲜度;存活状态则需你根据证据自行判断。 - HTTP 200 和内容并不能证明所表示的状态仍是最新状态。
-
对于对新鲜度敏感的操作,请使用
maxAge: 0并遵循检查清单。 检查渲染后的内容,对比metadata.url与metadata.sourceURL以查找可能的重定向迹象,并优先使用特定来源的 API。 -
将无法定论的证据视为
unknown。 仅凭一次 抓取 绝不能将对象标记为active;在执行成本高昂或不可逆的步骤前停止。 - Firecrawl 没有存活状态字段。 你的应用应根据自身领域的定义作出判断。

