# 更快的抓取 (/zh/features/fast-scraping)

<!-- agent-signals: reading_time_min: 2 · est_tokens: 1457 · updated: 2026-07-30 -->
Related: [搜索](/zh/features/search.md), [搜索高亮](/zh/features/search-highlights.md), [研究索引](/zh/features/research.md), [抓取](/zh/features/scrape.md), [批量抓取](/zh/features/batch-scrape.md), [JSON 模式 - 结构化结果](/zh/features/llm-extract.md)

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

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

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

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

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

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

**适用于：**

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

**不适用于：**

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

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

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

<CodeGroup>
  <CodeBlockTabs defaultValue="Python" groupId="javascript+python">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="Python">
        Python
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="JavaScript">
        JavaScript
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="Python">
      ```python  
      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)
      ```
    </CodeBlockTab>

    <CodeBlockTab value="JavaScript">
      ```javascript  
      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);
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

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

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

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

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

启用 `maxAge` 后：

* 针对最新内容，&#x2A;*响应速度提升 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>
  <CodeBlockTabs defaultValue="Python" groupId="curl+javascript+python">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="Python">
        Python
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="JavaScript">
        JavaScript
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="cURL">
        cURL
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="Python">
      ```python  
      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]}...")
      ```
    </CodeBlockTab>

    <CodeBlockTab value="JavaScript">
      ```javascript  
      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)}...`);
      });
      ```
    </CodeBlockTab>

    <CodeBlockTab value="cURL">
      ```bash  
      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
          }
        }'
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

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

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

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