# 抓取

> 将任意 URL 转换为干净的数据

import InstallationPython from "/snippets/zh/v2/installation/python.mdx";
import InstallationNode from "/snippets/zh/v2/installation/js.mdx";
import InstallationCLI from "/snippets/zh/v2/installation/cli.mdx";
import ScrapePython from "/snippets/zh/v2/scrape/base/python.mdx";
import ScrapeNode from "/snippets/zh/v2/scrape/base/js.mdx";
import ScrapeCURL from "/snippets/zh/v2/scrape/base/curl.mdx";
import ScrapeCLI from "/snippets/zh/v2/scrape/base/cli.mdx";
import ScrapeResponse from "/snippets/zh/v2/scrape/base/output.mdx";
import ExtractCURL from "/snippets/zh/v2/scrape/json/base/curl.mdx";
import ExtractPython from "/snippets/zh/v2/scrape/json/base/python.mdx";
import ExtractNode from "/snippets/zh/v2/scrape/json/base/js.mdx";
import ExtractOutput from "/snippets/zh/v2/scrape/json/base/output.mdx";
import ExtractNoSchemaCURL from "/snippets/zh/v2/scrape/json/no-schema/curl.mdx";
import ExtractNoSchemaPython from "/snippets/zh/v2/scrape/json/no-schema/python.mdx";
import ExtractNoSchemaNode from "/snippets/zh/v2/scrape/json/no-schema/js.mdx";
import ExtractNoSchemaOutput from "/snippets/zh/v2/scrape/json/no-schema/output.mdx";
import ScrapeActionsPython from "/snippets/zh/v2/scrape/actions/python.mdx";
import ScrapeActionsNode from "/snippets/zh/v2/scrape/actions/js.mdx";
import ScrapeActionsCURL from "/snippets/zh/v2/scrape/actions/curl.mdx";
import ScrapeActionsOutput from "/snippets/zh/v2/scrape/actions/output.mdx";
import BatchScrapePython from "/snippets/zh/v2/batch-scrape/short/python.mdx";
import BatchScrapeNode from "/snippets/zh/v2/batch-scrape/short/js.mdx";
import BatchScrapeCURL from "/snippets/zh/v2/batch-scrape/short/curl.mdx";
import BatchScrapeOutput from "/snippets/zh/v2/batch-scrape/base/output.mdx";
import BatchScrapeAsyncOutput from "/snippets/zh/v2/batch-scrape/base/async-output.mdx";
import ScrapeLocationPython from "/snippets/zh/v2/scrape/location/python.mdx";
import ScrapeLocationNode from "/snippets/zh/v2/scrape/location/js.mdx";
import ScrapeLocationCURL from "/snippets/zh/v2/scrape/location/curl.mdx";
import ScrapeBrandingPython from "/snippets/zh/v2/scrape/branding/base/python.mdx";
import ScrapeBrandingNode from "/snippets/zh/v2/scrape/branding/base/js.mdx";
import ScrapeBrandingCURL from "/snippets/zh/v2/scrape/branding/base/curl.mdx";
import ScrapeBrandingOutput from "/snippets/zh/v2/scrape/branding/base/output.mdx";
import ScrapeBrandingCombinedPython from "/snippets/zh/v2/scrape/branding/combined/python.mdx";
import ScrapeBrandingCombinedNode from "/snippets/zh/v2/scrape/branding/combined/js.mdx";
import ScrapeBrandingCombinedCURL from "/snippets/zh/v2/scrape/branding/combined/curl.mdx";
import ScrapeProductPython from "/snippets/zh/v2/scrape/product/base/python.mdx";
import ScrapeProductNode from "/snippets/zh/v2/scrape/product/base/js.mdx";
import ScrapeProductCURL from "/snippets/zh/v2/scrape/product/base/curl.mdx";
import ScrapeProductOutput from "/snippets/zh/v2/scrape/product/base/output.mdx";
import ScrapeProductCombinedPython from "/snippets/zh/v2/scrape/product/combined/python.mdx";
import ScrapeProductCombinedNode from "/snippets/zh/v2/scrape/product/combined/js.mdx";
import ScrapeProductCombinedCURL from "/snippets/zh/v2/scrape/product/combined/curl.mdx";
import ScrapeAudioPython from "/snippets/zh/v2/scrape/audio/python.mdx";
import ScrapeAudioNode from "/snippets/zh/v2/scrape/audio/js.mdx";
import ScrapeAudioCURL from "/snippets/zh/v2/scrape/audio/curl.mdx";
import ScrapeVideoPython from "/snippets/zh/v2/scrape/video/python.mdx";
import ScrapeVideoNode from "/snippets/zh/v2/scrape/video/js.mdx";
import ScrapeVideoCURL from "/snippets/zh/v2/scrape/video/curl.mdx";
import ScrapeQuestionPython from "/snippets/zh/v2/scrape/question/python.mdx";
import ScrapeQuestionNode from "/snippets/zh/v2/scrape/question/js.mdx";
import ScrapeQuestionCURL from "/snippets/zh/v2/scrape/question/curl.mdx";
import ScrapeHighlightsPython from "/snippets/zh/v2/scrape/highlights/python.mdx";
import ScrapeHighlightsNode from "/snippets/zh/v2/scrape/highlights/js.mdx";
import ScrapeHighlightsCURL from "/snippets/zh/v2/scrape/highlights/curl.mdx";
import PlaygroundCTA from "/snippets/zh/shared/playground-cta-scrape.mdx";

Firecrawl 可将网页转换为 markdown，非常适合 LLM 应用。

* 它可处理各种复杂情况：代理、缓存、限流、被 JS 阻止的内容
* 处理动态内容：动态网站、JS 渲染的网站、PDF 和图片
* 输出干净的 markdown、结构化数据、截图或 html。

详情请参阅 [Scrape Endpoint API 参考](https://docs.firecrawl.dev/api-reference/endpoint/scrape)。

<PlaygroundCTA />

<Note>如果请求失败，请参见 [Errors](/zh/api-reference/errors) 了解完整的错误代码目录、原因、补救措施和重试指南。</Note>

<div id="scraping-a-url-with-firecrawl">
  ## 使用 Firecrawl 抓取 URL
</div>

<div id="scrape-endpoint">
  ### /scrape 端点
</div>

用于抓取指定 URL 并获取其内容。

<div id="installation">
  ### 安装
</div>

<CodeGroup>
  <InstallationPython />

  <InstallationNode />

  <InstallationCLI />
</CodeGroup>

<div id="usage">
  ### 使用方式
</div>

<CodeGroup>
  <ScrapePython />

  <ScrapeNode />

  <ScrapeCURL />

  <ScrapeCLI />
</CodeGroup>

有关参数的更多信息，请参阅 [API 参考](https://docs.firecrawl.dev/api-reference/endpoint/scrape)。

<Tip>
  **PDF 和文档：**`/scrape` 会根据 URL 自动检测 PDF、DOCX 和其他文档类型。传入 PDF URL 的方式与传入任意网页相同——Firecrawl 会对其进行解析并返回干净的 markdown。对于无法通过 URL 访问的本地文件，请改用 [`/parse`](/zh/features/parse)。

  ```python Python
  doc = firecrawl.scrape("https://example.com/report.pdf", formats=["markdown"])
  print(doc.markdown)
  ```
</Tip>

<Info>
  每次抓取会消耗 1 个额度。某些选项会产生额外消耗：JSON 模式每页额外消耗 4 个额度，question 和 highlights formats 每种格式每页额外消耗 4 个额度，PII 脱敏每页额外消耗 4 个额度，PDF 解析每个 PDF 页面额外消耗 1 个额度，音频或视频提取每页额外消耗 4 个额度。
</Info>

<div id="response">
  ### 响应
</div>

各 SDK 会直接返回数据对象。cURL 将按下方所示原样返回载荷。

<ScrapeResponse />

<div id="response-metadata-and-status-codes">
  ### 响应元数据和状态码
</div>

抓取响应中有两个相互独立的状态层级，需要注意区分：

* **API 请求状态**：Firecrawl API 调用本身的 HTTP 状态，以及响应正文中的 `success` 布尔值。只要请求被接受并处理，就会返回 HTTP `200` 和 `success: true`，即使目标页面实际返回的是非 2xx 状态码。
* **页面状态** (`data.metadata.statusCode`) ：目标网站为该页面返回的 HTTP 状态码 (例如 `200`、`301`、`404`、`403`、`500`) 。它反映的是页面本身的响应情况。

因此，可靠的做法是：先确认请求成功 (HTTP `200` + `success: true`) ，再检查 `data.metadata.statusCode`，了解页面的实际结果。Firecrawl 将 2xx 或 `304` 的 `statusCode` 视为页面加载正常；其他状态则表示页面未能正常加载。当页面返回错误状态时，`data.metadata.error` 可能会包含更多详细信息。

<div id="scrape-formats">
  ## 抓取格式
</div>

现在你可以选择输出所需的格式。你可以指定多个输出格式。支持的格式包括：

* Markdown (`markdown`)
* 摘要 (`summary`)
* HTML (`html`) - 页面 HTML 的清洗版本
* 原始 HTML (`rawHtml`) - 按页面返回的不经修改的 HTML
* 原始 Base64 (`rawBase64`) - 经过 Base64 编码的原始 HTTP 响应正文；必须是请求中的唯一格式
* 截图 (`screenshot`，可选项包括 `fullPage`、`quality`、`viewport`) — 截图 URL 会在 24 小时后过期
* 链接 (`links`)
* JSON (`json`) - 结构化输出
* 图片 (`images`) - 提取页面中的所有图片 URL
* 品牌 (`branding`) - 提取品牌识别与设计系统
* Product (`product`) - 从产品页面提取结构化产品 (标题、价格、可用性、变体)
* 音频 (`audio`) - 从支持的视频 URL (例如 YouTube) 中提取 MP3 音频 (返回签名 GCS URL，1 小时后过期)
* 视频 (`video`) - 从支持的视频 URL (例如 YouTube) 中提取最佳质量的视频 (返回签名 GCS URL，1 小时后过期)
* Query (`query`，带有 `prompt` 和可选的 `mode`) - 针对页面提出一个自然语言问题；答案会在 `answer` 字段中返回

输出键将与你选择的格式对应。

`rawBase64` 格式会返回经过 Base64 编码的原始 HTTP 响应正文。`rawBase64` 字段包含纯 Base64 字符串，而非数据 URI。请从 `metadata.contentType` 读取 MIME 类型。请仅请求 `rawBase64`，因为 API 会拒绝将其与任何其他格式一起使用。响应中不包含 `markdown`、`html` 或 `rawHtml` 字段，并且它仅包含该 URL 对应的单个文件，不包含 CSS、图片或其他子资源。

<div id="extract-structured-data">
  ## 提取结构化数据
</div>

<div id="scrape-with-json-endpoint">
  ### /scrape (使用 JSON) 端点
</div>

用于从抓取的页面中提取结构化数据。

<Tip>
  要提取产品信息？对于产品页面，[`product` 格式](#extract-product-data)会以确定性的方式返回结构化的产品字段 (标题、价格、库存状态、变体) ——无需调用 LLM，也无需定义 schema。当你需要自定义字段或处理非产品页面时，再使用 `json`。
</Tip>

<CodeGroup>
  <ExtractPython />

  <ExtractNode />

  <ExtractCURL />
</CodeGroup>

输出：

<ExtractOutput />

<div id="extracting-without-schema">
  ### 无需 schema 的提取
</div>

现在，你只需向端点传入一个 `prompt`，即可在不提供 schema 的情况下进行提取。LLM 会自行决定数据结构。

<CodeGroup>
  <ExtractNoSchemaPython />

  <ExtractNoSchemaNode />

  <ExtractNoSchemaCURL />
</CodeGroup>

输出：

<ExtractNoSchemaOutput />

<div id="json-format-options">
  ### JSON 格式选项
</div>

使用 `json` 格式时，在 `formats` 中传入一个对象，包含以下参数：

* `schema`：用于结构化输出的 JSON Schema。
* `prompt`：可选提示；在提供 schema 时或仅需轻量指引时用于辅助抽取。

<div id="extract-brand-identity">
  ## 提取品牌识别度
</div>

<div id="scrape-with-branding-endpoint">
  ### /scrape (品牌信息) 端点
</div>

branding 格式会从网页中提取完整的品牌识别信息，包括颜色、字体、排版、间距、UI 组件等。它适用于设计系统分析、品牌监测，或构建需要理解网站视觉风格的工具。

<CodeGroup>
  <ScrapeBrandingPython />

  <ScrapeBrandingNode />

  <ScrapeBrandingCURL />
</CodeGroup>

<div id="response-2">
  ### 响应
</div>

品牌配置会返回一个完整的 `BrandingProfile` 对象，其结构如下：

<ScrapeBrandingOutput />

<div id="branding-profile-structure">
  ### 品牌档案结构
</div>

`branding` 对象包含以下属性：

* `colorScheme`: 检测到的配色方案 (`"light"` 或 `"dark"`)
* `logo`: 主徽标的 URL
* `colors`: 包含品牌颜色的对象：
  * `primary`、`secondary`、`accent`: 主要品牌色
  * `background`、`textPrimary`、`textSecondary`: 界面颜色
  * `link`、`success`、`warning`、`error`: 语义颜色
* `fonts`: 页面中使用的字体系列数组
* `typography`: 详细的排版信息：
  * `fontFamilies`: 正文、标题与代码字体系列
  * `fontSizes`: 标题与正文的尺寸定义
  * `fontWeights`: 字重定义 (细体、常规、中等、粗体)
  * `lineHeights`: 不同文本类型的行高值
* `spacing`: 间距与布局信息：
  * `baseUnit`: 基础间距单位 (像素)
  * `borderRadius`: 默认圆角
  * `padding`、`margins`: 间距值
* `components`: UI 组件样式：
  * `buttonPrimary`、`buttonSecondary`: 按钮样式
  * `input`: 输入框样式
* `icons`: 图标样式信息
* `images`: 品牌图像 (logo、favicon、og:image)
* `animations`: 动画与过渡设置
* `layout`: 布局配置 (栅格、页眉/页脚高度)
* `personality`: 品牌个性特征 (语气、调性、目标受众)

<div id="combining-with-other-formats">
  ### 与其他 formats 结合使用
</div>

你可以将 branding 格式与其他 formats 组合，以获取更全面的页面数据：

<CodeGroup>
  <ScrapeBrandingCombinedPython />

  <ScrapeBrandingCombinedNode />

  <ScrapeBrandingCombinedCURL />
</CodeGroup>

<div id="extract-product-data">
  ## 提取产品数据
</div>

`product` 格式会以**确定性**方式提取结构化的产品数据——它产出的结构化输出与 [`json` 格式](#extract-structured-data)相同，但无需调用 LLM，也不用自行定义 schema，专为产品页面而设计。如果你一直在用 `json` schema 提取产品字段，建议改用 `formats: ["product"]`——它更快、更便宜，但仅适用于产品。

它会返回一个 `product` 对象，其中包含 title、brand、category、description 和 variants；每个 variant 都带有 price、original price、availability 和 图片——适合用于价格监控、商品目录采集或比价工具。

<div id="scrape-with-product-endpoint">
  ### /scrape (带有 product 参数) 端点
</div>

<CodeGroup>
  <ScrapeProductPython />

  <ScrapeProductNode />

  <ScrapeProductCURL />
</CodeGroup>

<div id="response-3">
  ### 响应
</div>

`product` 格式会返回一个 `product` 对象，结构如下：

<ScrapeProductOutput />

<div id="product-object-structure">
  ### 产品对象结构
</div>

`product` 对象包含以下属性：

* `title`：产品名称
* `brand`：产品品牌 (可选)
* `category`：产品类别 (可选)
* `url`：产品的规范 URL
* `description`：产品描述 (可选)
* `variants`：产品变体数组。价格、可用性和图片信息都在各个变体上——即使是单 SKU 产品，也仍会准确返回一个包含这些信息的变体。每个变体包含：
  * `id`、`sku`、`title`：变体标识符和标签 (均为可选)
  * `values`：选项名称到选项值的映射，例如 `{ "color": "Charcoal" }` (可选)
  * `price`：当前价格对象 (可选) ：
    * `amount`：数值型价格
    * `currency`：货币代码，仅当页面提供该信息时才会返回 (可选)
    * `formatted`：页面上显示的价格 (可选)
  * `sale`：仅在变体有折扣时才会出现 (可选) 。包含：
    * `originalPrice`：原价 (折扣前价格) ，结构与 `price` 相同
  * `availability`：库存信息，在变体上始终存在：
    * `inStock`：该变体是否有库存
    * `text`：页面上的原始库存文本 (可选)
  * `images`：变体图片数组，每项都包含 `url` 和可选的 `alt` 文本 (可选)

<div id="how-product-extraction-works">
  ### 产品提取的工作方式
</div>

`product` 格式会以确定性方式从页面上的结构化数据中提取产品——不涉及 LLM。它会按优先级合并多个来源：**JSON-LD &gt; schema.org microdata &gt; RDFa &gt; 嵌入状态 (`__NEXT_DATA__`/Nuxt/Apollo/Redux/Remix)  &gt; AliExpress `runParams` &gt; GA4 `dataLayer` &gt; OpenGraph/`<meta>`**。合并过程会识别产品身份，因此绝不会将不同产品的字段混合在一起。只有当页面来源中提供了货币信息时，才会返回货币。

<Note>
  产品提取采用 fail-closed 策略：对于有歧义的页面，不会产出任何产品；而像 OpenGraph 这样较弱的来源，也只有在存在价格时才会参与补充。在没有可提取产品的页面上，响应会省略 `product` 对象，并添加一个 `warning` (例如“未找到产品...”) 。
</Note>

<Note>
  **自托管：** `product` 格式由专用的产品提取服务提供支持。在 Firecrawl Cloud 上可开箱即用。如果你选择自托管，请设置 `PRODUCT_EXTRACTION_SERVICE_URL` 并将其指向该服务——如果未设置，请求 `product` 格式时会返回警告，且不会返回产品 (音频/视频格式对其服务也采用相同模式) 。
</Note>

<div id="combining-with-other-formats-2">
  ### 与其他 formats 组合使用
</div>

你可以将 product 格式与其他 formats 组合使用，以获取更全面的页面数据：

<CodeGroup>
  <ScrapeProductCombinedPython />

  <ScrapeProductCombinedNode />

  <ScrapeProductCombinedCURL />
</CodeGroup>

<div id="audio-extraction">
  ## 音频提取
</div>

`audio` 格式可从受支持的网站 (如 YouTube) 提取音频并保存为 MP3 文件，同时返回一个已签名的 Google Cloud Storage URL。这适用于构建音频处理流程、转录服务或播客工具。

<Info>
  音频提取每页消耗 5 个额度 (1 个基础额度 + 4 个额外额度) 。
</Info>

<CodeGroup>
  <ScrapeAudioPython />

  <ScrapeAudioNode />

  <ScrapeAudioCURL />
</CodeGroup>

<div id="video-extraction">
  ## 视频提取
</div>

`video` 格式可从受支持的网站 (如 YouTube) 提取最高质量的视频，并返回一个已签名的 Google Cloud Storage URL。这适用于构建视频处理管道、内容审核工具或媒体归档工作流。

<Info>
  视频提取每页消耗 5 个额度 (1 个基础额度 + 4 个额外额度) 。
</Info>

<CodeGroup>
  <ScrapeVideoPython />

  <ScrapeVideoNode />

  <ScrapeVideoCURL />
</CodeGroup>

<span id="question-format" />

<div id="question-format">
  ## Question 格式
</div>

使用 `question` 格式对页面提出一个自然语言问题。Firecrawl 会在响应的 `answer` 字段中返回答案。

<Info>
  `question` 格式每页消耗 5 个额度 (1 个基础额度 + 4 个用于 LLM 调用的额外额度) 。
</Info>

格式对象中的选项：

* `question` (`type: "question"` 时必填) ：要回答的问题。最多 10,000 个字符。

你可以将 `question` 与其他 formats 组合使用——例如，同时请求 `markdown` 和 `question`，即可在一次调用中获得页面内容和答案。

<CodeGroup>
  <ScrapeQuestionPython />

  <ScrapeQuestionNode />

  <ScrapeQuestionCURL />
</CodeGroup>

`question` 格式也可通过 `/search` 中的 `scrapeOptions` 使用，这会对每个搜索结果执行相同的提取。

<span id="highlights-format" />

<div id="highlights-format">
  ## Highlights 格式
</div>

使用 `highlights` 格式可从页面中找出相关的源文本。Firecrawl 会在响应的 `highlights` 字段中返回所选文本。

<Info>
  `highlights` 格式每页消耗 5 额度 (1 个基础额度 + 4 个 LLM 调用的额外额度) 。
</Info>

格式对象中的选项：

* `query` (`type: "highlights"` 时必填) ：源文本选择请求。最大 10,000 个字符。

你可以将 `highlights` 与其他 formats 组合使用——例如，同时请求 `markdown` 和 `highlights`，即可在一次调用中获取页面内容和源文本。

<CodeGroup>
  <ScrapeHighlightsPython />

  <ScrapeHighlightsNode />

  <ScrapeHighlightsCURL />
</CodeGroup>

`highlights` 格式也可通过 `/search` 中的 `scrapeOptions` 使用，对每个搜索结果执行相同的提取。

<div id="pii-redaction">
  ## PII 脱敏
</div>

设置 `redactPII: true`，对返回的 markdown 中的个人身份信息进行脱敏处理。`markdown` 字段包含脱敏后的结果。

请参见 [PII 脱敏](/zh/features/pii-redaction) 了解 SDK、cURL、CLI 和 MCP 示例。

<div id="interacting-with-the-page-with-actions">
  ## 使用 actions 与页面交互
</div>

Firecrawl 允许你在抓取页面内容之前对网页执行各种 actions。这对于与动态内容交互、在页面之间导航，或访问需要用户操作的内容特别有用。

<Tip>
  **我们推荐使用 [交互](/zh/features/interact) 而不是 actions：这是我们更新、更强大的已抓取页面交互方式。**

  交互以有状态的浏览器会话形式运行，并可在多次调用之间保持存活，因此你可以通过以下任一方式逐步控制页面：

  * **自然语言**，适用于灵活、非确定性的流程。例如：*“搜索‘无线耳机’，筛选出 4 星以上且价格低于 200 美元的结果，并返回这些结果”*。
  * **Playwright 或 agent-browser 代码**，适用于确定性的步骤。例如：`await page.click('#export')`。

  交互还支持配置文件、持久会话以及可嵌入的实时浏览器视图 (包含一种交互模式，最终用户可以自行控制浏览器) 。
</Tip>

下面是一个示例，演示如何使用 actions 访问 google.com，搜索 Firecrawl，点击第一个结果，并截取页面截图。

在执行其他 actions 之前或之后，几乎都应使用 `wait` action，为页面加载预留足够时间。

<div id="example">
  ### 示例
</div>

<CodeGroup>
  <ScrapeActionsPython />

  <ScrapeActionsNode />

  <ScrapeActionsCURL />
</CodeGroup>

<div id="output">
  ### 输出
</div>

<CodeGroup>
  <ScrapeActionsOutput />
</CodeGroup>

对于抓取后还需要更强浏览器控制的工作流，例如已认证会话、多步骤导航或页面实时视图，我们建议使用 [交互](/zh/features/interact)，而不是继续扩展 actions 数组。

<div id="location-and-language">
  ## 位置与语言
</div>

指定国家/地区和首选语言，以根据你的目标位置和语言偏好获取相关内容。

<div id="how-it-works">
  ### 工作原理
</div>

当你指定位置设置时，Firecrawl 会在可用时使用合适的代理，并仿真相应的语言和时区设置。默认情况下，若未指定位置，位置将设为“US”。

<div id="usage-2">
  ### 用法
</div>

要使用位置和语言设置，请在请求体中包含 `location` 对象，并提供以下属性：

* `country`：ISO 3166-1 alpha-2 国家/地区代码 (例如“US”“AU”“DE”“JP”) 。默认值为“US”。
* `languages`：按优先级排序的首选语言和区域设置数组。默认使用所设位置对应的语言。

<CodeGroup>
  <ScrapeLocationPython />

  <ScrapeLocationNode />

  <ScrapeLocationCURL />
</CodeGroup>

有关受支持位置的更多详情，请参阅[代理文档](/zh/features/proxies)。

<div id="caching-and-maxage">
  ## 缓存与 maxAge
</div>

为加快请求速度，当有较新的副本可用时，Firecrawl 默认会直接从缓存返回结果。

* **默认新鲜度窗口**：`maxAge = 172800000` 毫秒 (2 天) 。如果缓存页面仍在该窗口内，将立即返回；否则会重新抓取页面并写入缓存。
* **性能**：在数据对时效性要求不高时，抓取速度可提升至最多 5 倍。
* **始终获取最新**：将 `maxAge` 设为 `0`。注意，这会完全绕过缓存，因此每次请求都会走完整的抓取流水线，这意味着请求完成所需时间更长，也更有可能失败。如果对每个请求的实时性不是绝对关键，建议使用非零的 `maxAge`。
* **避免存储**：如果不希望 Firecrawl 为本次请求缓存/存储结果，将 `storeInCache` 设为 `false`。
* **仅查缓存**：设置 `minAge` 可仅执行缓存查询，而不会触发新的抓取。该值以毫秒为单位，指定缓存数据必须满足的最小缓存时长。如果未找到缓存数据，将返回带有错误代码 `SCRAPE_NO_CACHED_DATA` 的 `404`。将 `minAge` 设为 `1` 可接受任意缓存数据，无论其缓存时长是多少。
* **变更跟踪**：包含 `changeTracking` 的请求会绕过缓存，因此会忽略 `maxAge`。
* **额度**：缓存结果每页仍消耗 1 个额度。缓存提升的是速度，而不是额度使用。

示例 (强制获取最新内容) ：

<CodeGroup>
  ```python Python
  from firecrawl import Firecrawl
  firecrawl = Firecrawl(api_key='fc-YOUR_API_KEY')

  doc = firecrawl.scrape(url='https://example.com', max_age=0, formats=['markdown'])
  print(doc)
  ```

  ```js Node
  import { Firecrawl } from 'firecrawl';

  const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });

  const doc = await firecrawl.scrape('https://example.com', { maxAge: 0, formats: ['markdown'] });
  console.log(doc);
  ```

  ```bash cURL
  curl -s -X POST "https://api.firecrawl.dev/v2/scrape" \
    -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "url": "https://example.com",
      "maxAge": 0,
      "formats": ["markdown"]
    }'
  ```
</CodeGroup>

示例 (使用 10 分钟缓存窗口) ：

<CodeGroup>
  ```python Python
  from firecrawl import Firecrawl
  firecrawl = Firecrawl(api_key='fc-YOUR_API_KEY')

  doc = firecrawl.scrape(url='https://example.com', max_age=600000, formats=['markdown', 'html'])
  print(doc)
  ```

  ```js Node

  const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });

  const doc = await firecrawl.scrape('https://example.com', { maxAge: 600000, formats: ['markdown', 'html'] });
  console.log(doc);
  ```

  ```bash cURL
  curl -s -X POST "https://api.firecrawl.dev/v2/scrape" \
    -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "url": "https://example.com",
      "maxAge": 600000,
      "formats": ["markdown", "html"]
    }'
  ```
</CodeGroup>

<div id="freshness-and-item-status">
  ### 新鲜度与条目状态
</div>

`maxAge` 决定 Firecrawl 是否可以返回缓存副本；它并不能说明页面所呈现的状态是否仍然有效。对新鲜度有要求时，请使用 `maxAge: 0` 跳过缓存，然后检查返回的内容，以及任何重定向或特定来源的状态信号。仅凭响应成功，并不能证明状态仍然有效。

请参见[验证新鲜度和可用性](/zh/developer-guides/usage-guides/verifying-freshness-and-liveness)，了解检查清单和示例。

<div id="batch-scraping-multiple-urls">
  ## 批量抓取多个 URL
</div>

你现在可以同时批量抓取多个 URL。它以起始 URL 和可选参数作为输入。params 参数允许你为批量抓取任务指定其他选项，例如输出 formats。

<div id="how-it-works-2">
  ### 工作原理
</div>

它与 `/crawl` 端点的运行方式非常相似。它会提交一个批量抓取作业，并返回一个作业 ID，用于检查该批量抓取的状态。

SDK 提供两种方式：同步与异步。同步方式会直接返回批量抓取作业的结果，异步方式则会返回一个作业 ID，供您用于查询批量抓取的状态。

<div id="usage-3">
  ### 使用方法
</div>

<CodeGroup>
  <BatchScrapePython />

  <BatchScrapeNode />

  <BatchScrapeCURL />
</CodeGroup>

<div id="response-4">
  ### Response
</div>

如果你使用 SDK 的同步方法，将直接返回批量抓取任务的结果；否则会返回一个作业 ID，你可以用它来查询批量抓取的状态。

<div id="synchronous">
  #### 同步执行
</div>

<BatchScrapeOutput />

<div id="asynchronous">
  #### 异步
</div>

你可以使用作业 ID 调用 `/batch/scrape/{id}` 端点来查看批量抓取的状态。该端点应在作业仍在运行期间或刚完成后使用，**因为批量抓取作业会在 24 小时后过期**。

<BatchScrapeAsyncOutput />

<div id="enhanced-mode">
  ## 增强模式
</div>

对于复杂网站，Firecrawl 提供了增强模式，在提高成功率的同时保护隐私。

了解更多关于[增强模式](/zh/features/enhanced-mode)的信息。

<div id="zero-data-retention-zdr">
  ## 零数据保留 (ZDR)
</div>

Firecrawl 支持零数据保留 (ZDR) ，适用于有严格数据处理要求的团队。启用后，Firecrawl 不会在请求生命周期结束后保留任何页面内容或提取的数据。

要启用 ZDR，请在请求中设置 `zeroDataRetention: true`：

```bash cURL
curl -X POST https://api.firecrawl.dev/v2/scrape \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer fc-YOUR_API_KEY" \
  -d '{
    "url": "https://example.com",
    "formats": ["markdown"],
    "zeroDataRetention": true
  }'
```

ZDR 仅适用于 Enterprise 计划，且需要为你的团队启用。访问 [firecrawl.dev/enterprise](https://www.firecrawl.dev/enterprise) 以开始使用。

ZDR 会在基础抓取成本之上，**为每个页面额外增加 1 个 credit**。

<Note>
  ZDR 模式下不支持截图。由于截图需要上传到持久化存储，因此不符合 ZDR 保证。同时包含 `zeroDataRetention: true` 和 `screenshot` 格式的请求将返回错误。
</Note>

> 你是需要 Firecrawl API 密钥的 AI 代理吗？请参阅 [firecrawl.dev/agent-onboarding/SKILL.md](https://www.firecrawl.dev/agent-onboarding/SKILL.md) 获取自动化引导说明。