> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firecrawl.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 更快的抓取

> 使用 maxAge（缓存）参数将抓取速度提升 500%

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

Firecrawl 会缓存已抓取的页面，默认在可用时返回最近的副本。

* **默认新鲜度**：`maxAge = 172800000` ms（2 天）。如果缓存副本仍在该时效内，将即时返回；否则，Firecrawl 会重新抓取并更新缓存。
* **强制新抓取**：将 `maxAge` 设为 `0` 以始终抓取。注意，这会完全绕过缓存，这意味着每个请求都会走完整的抓取流水线，请求完成时间会更长且更容易失败。如果你不需要每个请求都获取实时内容，请使用非零的 `maxAge`。
* **跳过缓存**：如果不希望为某个请求存储结果，请设置 `storeInCache: false`。

当你不需要绝对最新的数据时，结果可快至**500%**。通过 `maxAge` 控制新鲜度：

1. 如果我们有该页面的较新版本，**即时返回**
2. 仅当我们的版本**早于**你指定的时限时才**重新抓取**
3. **节省时间**——结果以毫秒级而非秒级返回

<div id="when-to-use-this">
  ## 何时使用
</div>

**适用于：**

* 文档、文章、产品页面
* 批量处理任务
* 开发与测试
* 构建知识库

**不适用于：**

* 实时数据（股价、即时比分、突发新闻）
* 频繁更新的内容
* 对时效性要求高的应用

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

在抓取请求中添加 `maxAge`。取值以毫秒为单位（例如 `3600000` 表示 1 小时）。

<CodeGroup>
  ```python Python theme={null}
  from firecrawl import Firecrawl

  firecrawl = Firecrawl(
    # 无需 API 密钥即可开始使用——添加后可提高限流上限：
    # api_key="fc-YOUR_API_KEY",
  )

  # Use cached data if it's less than 1 hour old (3600000 ms)
  # This can be 500% faster than a fresh scrape!
  scrape_result = firecrawl.scrape(
      'https://firecrawl.dev',
      formats=['markdown'],
      max_age=3600000  # 1 hour in milliseconds
  )

  print(scrape_result.markdown)
  ```

  ```javascript JavaScript theme={null}
  import { Firecrawl } from 'firecrawl';

  const firecrawl = new Firecrawl({
    // 无需 API 密钥即可开始使用——添加一个以获得更高限流：
    // apiKey: "fc-YOUR_API_KEY",
  });

  // Use cached data if it's less than 1 hour old (3600000 ms)
  // This can be 500% faster than a fresh scrape!
  const scrapeResult = await firecrawl.scrape('https://firecrawl.dev', {
    formats: ['markdown'],
    maxAge: 3600000 // 1 hour in milliseconds
  });

  console.log(scrapeResult.markdown);
  ```
</CodeGroup>

<div id="common-maxage-values">
  ## 常见的 maxAge（缓存）取值
</div>

以下是一些实用的参考值：

* **5 分钟**：`300000` - 适用于半动态内容
* **1 小时**：`3600000` - 适用于每小时更新的内容
* **1 天**：`86400000` - 适用于每日更新的内容
* **1 周**：`604800000` - 适用于相对静态的内容

<div id="performance-impact">
  ## 性能影响
</div>

启用 `maxAge` 后：

* 针对最新内容，**响应速度提升 500%**
* **结果即时返回**，无需等待重新抓取

<div id="important-notes">
  ## 重要说明
</div>

* **默认**：`maxAge` 为 `172800000`（2 天）
* **需要时新抓**：如果我们的数据早于 `maxAge`，我们会自动抓取最新内容
* **无过期数据**：你不会收到早于你指定 `maxAge` 的数据
* **点数**：缓存结果仍按每页 1 点数计费。缓存提升的是速度和延迟，而不是点数消耗。

<div id="when-caching-is-bypassed">
  ### 何时会跳过缓存
</div>

当请求中包含以下任一项时，将自动跳过缓存：

* 自定义 `headers`
* `actions` (浏览器自动化步骤)
* 浏览器 `profile`
* `changeTracking` 格式
* 自定义 `screenshot` 视口或质量设置

<div id="cache-hit-matching">
  ### 缓存命中条件
</div>

要命中缓存，原始请求与后续请求中的以下参数必须完全一致：`url`、`mobile`、`location`、`waitFor`、`blockAds`、`screenshot` (是否启用以及是否为整页) ，以及隐身代理模式。

你可以通过查看响应中的 `metadata.cacheState` 来确认缓存状态——其值会是 `"hit"` 或 `"miss"`。

<div id="faster-crawling">
  ## 更快的爬取
</div>

在爬取多个页面时同样能获得速度优势。在 `scrapeOptions` 中使用 `maxAge`，即可返回我们最近访问过页面的缓存结果。

<CodeGroup>
  ```python Python theme={null}
  from firecrawl import Firecrawl
  from firecrawl.v2.types import ScrapeOptions

  firecrawl = Firecrawl(api_key="fc-YOUR_API_KEY")

  # Crawl with cached scraping - 500% faster for pages we've seen recently
  crawl_result = firecrawl.crawl(
      'https://firecrawl.dev',
      limit=100,
      scrape_options=ScrapeOptions(
          formats=['markdown'],
          max_age=3600000  # 若缓存数据生成时间在 1 小时内，则直接使用缓存
      )
  )

  for page in crawl_result.data:
      print(f"URL: {page.metadata.source_url}")
      print(f"Content: {page.markdown[:200]}...")
  ```

  ```javascript JavaScript theme={null}
  import { Firecrawl } from 'firecrawl';

  const firecrawl = new Firecrawl({ apiKey: "fc-YOUR_API_KEY" });

  // 启用缓存的抓取进行爬取——对最近见过的页面快 500%
  const crawlResult = await firecrawl.crawl('https://firecrawl.dev', {
    limit: 100,
    scrapeOptions: {
      formats: ['markdown'],
      maxAge: 3600000 // 如果缓存未超过 1 小时，则直接使用
    }
  });

  crawlResult.data.forEach(page => {
    console.log(`URL: ${page.metadata.sourceURL}`);
    console.log(`内容: ${page.markdown.substring(0, 200)}...`);
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.firecrawl.dev/v2/crawl \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer fc-YOUR_API_KEY' \
    -d '{
      "url": "https://firecrawl.dev",
      "limit": 100,
      "scrapeOptions": {
        "formats": ["markdown"],
        "maxAge": 3600000
      }
    }'
  ```
</CodeGroup>

使用 `maxAge` 进行爬取时，如果该页面存在近期缓存数据，你爬取的每个页面都可获得高达 500% 的速度提升。

立即开始使用 `maxAge`，大幅加速你的抓取与爬取！

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