验证内容新鲜度与对象存活状态

成功的 抓取 会告诉你页面返回了什么，但不能证明页面所反映的状态仍然有效。这是两个不同的问题。

• 新鲜度 → 内容是最新的，还是复用了 Firecrawl 缓存中的副本？由 maxAge 控制。
• 存活状态 → 底层对象是否仍然存在且处于活跃状态？你的应用需要根据现有证据自行判断。

本指南将解释两者的区别，介绍 maxAge 的权衡，并为对新鲜度敏感的操作提供检查清单和示例。

Firecrawl 会缓存之前抓取的页面，并在有可用副本时返回较新的副本，从而降低延迟。maxAge 指 Firecrawl 可以返回缓存副本而非重新获取页面时，该缓存副本允许的最大时长 (以毫秒为单位) 。

• 省略 maxAge：Firecrawl 可能会返回最近缓存的内容。默认时间窗口为 2 天；对于某些网站，Firecrawl 可能会使用不同的时间窗口。
• 设置 maxAge: 0：Firecrawl 会跳过该请求的缓存并重新获取页面。这会以延迟和可靠性为代价，换取更新鲜的结果。

默认应启用缓存。仅在内容过期会导致错误或高成本决策的读取操作中承担 maxAge: 0 带来的延迟成本——它不会改变该页面消耗的额度。

当 Firecrawl 针对该请求考虑使用缓存时，会返回 metadata.cacheState，因此在调整 maxAge 时可用它进行检查。maxAge: 0 的响应中不会包含它，因为该请求会完全跳过缓存。

有关缓存机制、常见的 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，不要假定其仍处于活跃状态；应在执行成本高昂或不可逆的步骤前停止。

跳过缓存，然后收集渲染后的内容和响应元数据，供应用程序根据自身的验证规则进行判断。抓取只提供证据；不会决定特定领域的状态。

import osfrom firecrawl import Firecrawlfirecrawl = Firecrawl(api_key=os.environ["FIRECRAWL_API_KEY"])def collect_current_page_evidence(url: str) -> dict:    # max_age=0 会跳过此请求的 Firecrawl 缓存。    doc = firecrawl.scrape(url, formats=["markdown"], max_age=0)    metadata = doc.metadata    requested_url = (metadata.source_url if metadata else None) or url    response_url = metadata.url if metadata else None    return {        "markdown": doc.markdown or "",        "status_code": metadata.status_code if metadata else None,        "requested_url": requested_url,        "response_url": response_url,        "possible_redirect": bool(response_url and response_url != requested_url),    }evidence = collect_current_page_evidence("https://example.com/resource")# 在此执行针对来源的内容、状态、API 或标识符检查。# 如果无法得出结论，请将状态保持为 unknown。

关键分界点在于收集完成后：Firecrawl 提供页面证据；应用程序根据针对来源的规则来解读这些证据。如果这些规则无法得出结论，请将状态保持为 unknown。

1. 新鲜度和存活状态是两个不同的问题。 maxAge 控制新鲜度；存活状态则需你根据证据自行判断。

2. HTTP 200 和内容并不能证明所表示的状态仍是最新状态。

3. 对于对新鲜度敏感的操作，请使用 maxAge: 0 并遵循检查清单。 检查渲染后的内容，对比 metadata.url 与 metadata.sourceURL 以查找可能的重定向迹象，并优先使用特定来源的 API。

4. 将无法定论的证据视为 unknown。 仅凭一次 抓取 绝不能将对象标记为 active；在执行成本高昂或不可逆的步骤前停止。

5. Firecrawl 没有存活状态字段。 你的应用应根据自身领域的定义作出判断。

• 抓取
• 快速抓取
• 选择数据提取器