高级抓取指南

本指南将带你了解 Firecrawl 的各个端点，并讲解如何结合所有参数充分发挥其功能。

使用 Firecrawl 进行基础抓取

要抓取单个页面并获取干净的 Markdown 内容，可以使用 /scrape 端点。

# pip install firecrawl-py

from firecrawl import Firecrawl

firecrawl = Firecrawl(api_key="fc-YOUR-API-KEY")

doc = firecrawl.scrape("https://firecrawl.dev")

print(doc.markdown)

抓取 PDF

Firecrawl 支持 PDF。需要确保解析 PDF 时，请使用 parsers 选项（例如 parsers: ["pdf"]）。

抓取选项

使用 /scrape 端点时，你可以通过以下选项定制抓取。

formats（`formats`）

类型: array
字符串: ["markdown", "links", "html", "rawHtml", "summary", "images"]
对象 formats:
- JSON: { type: "json", prompt, schema }
- 截图: { type: "screenshot", fullPage?, quality?, viewport? }
- 变更跟踪: { type: "changeTracking", modes?, prompt?, schema?, tag? }（需要 markdown）
默认值: ["markdown"]

全页内容 vs 主内容（`onlyMainContent`）

类型: boolean
描述: 默认仅返回主内容。将其设为 false 可返回全页内容。
默认值: true

包含标签（`includeTags`）

类型: array
描述: 抓取时要包含的 HTML 标签/类名/ID。

排除标签（`excludeTags`）

类型: array
描述: 在抓取时需要排除的 HTML 标签/类名/ID。

等待页面就绪（`waitFor`）

类型: integer
描述: 抓取前额外等待的毫秒数（尽量少用）。该等待时间是在 Firecrawl 智能等待功能基础上的额外延时。
默认值: 0

新鲜度与缓存（`maxAge`）

类型: integer（毫秒）
描述: 如果页面的缓存版本在 maxAge 内仍然有效，Firecrawl 会立即返回；否则将抓取最新内容并更新缓存。将其设为 0 可始终获取最新内容。
默认值: 172800000（2 天）

请求超时（`timeout`）

类型: integer
描述: 在中止前的最长时长（毫秒）。
默认值: 30000（30 秒）

PDF 解析（`parsers`）

类型: array
描述: 用于控制解析行为。要解析 PDF，请设置 parsers: ["pdf"]。
费用: PDF 解析按每页收取 1 个积分。若要跳过 PDF 解析并以 base64 格式接收文件（统一收取 1 个积分），请设置 parsers: []。
限制页数: 若要将 PDF 解析限制在指定页数内，请使用 parsers: [{"type": "pdf", "maxPages": 10}]。

actions（`actions`）

使用 /scrape 端点时，Firecrawl 允许你在抓取页面内容之前，在网页上执行一系列 actions。这在需要与动态内容交互、在页面之间导航，或访问依赖用户操作才能显示的内容时尤其有用。

Type: array
Description: 抓取前要运行的一系列浏览器步骤。
Supported actions:
- wait - 等待页面加载：{ type: "wait", milliseconds: number } 或 { type: "wait", selector: string }
- click - 点击元素：{ type: "click", selector: string, all?: boolean }
- write - 向输入字段中键入文本：{ type: "write", text: string }（元素必须先通过 click 获得焦点）
- press - 模拟键盘按键：{ type: "press", key: string }
- scroll - 滚动页面：{ type: "scroll", direction: "up" | "down", selector?: string }
- screenshot - 捕获页面截图：{ type: "screenshot", fullPage?: boolean, quality?: number, viewport?: { width: number, height: number } }
- scrape - 抓取子元素内容：{ type: "scrape" }
- executeJavascript - 执行 JS 代码：{ type: "executeJavascript", script: string }
- pdf - 生成 PDF 文件：{ type: "pdf", format?: string, landscape?: boolean, scale?: number }

from firecrawl import Firecrawl

firecrawl = Firecrawl(api_key='fc-YOUR-API-KEY')

doc = firecrawl.scrape('https://example.com', {
  'actions': [
    { 'type': 'wait', 'milliseconds': 1000 },
    { 'type': 'click', 'selector': '#accept' },
    { 'type': 'scroll', 'direction': 'down' },
    { 'type': 'click', 'selector': '#q' },
    { 'type': 'write', 'text': 'firecrawl' },
    { 'type': 'press', 'key': 'Enter' },
    { 'type': 'wait', 'milliseconds': 2000 }
  ],
  'formats': ['markdown']
})

print(doc.markdown)

actions 执行注意事项

Write action：在使用 write 之前，必须先通过一个 click action 使目标元素获得焦点。文本会逐字输入，以模拟键盘输入。
Scroll selector：如果你只想滚动某个特定元素而不是整个页面，请在 scroll 中提供 selector 参数。
Wait with selector：你可以在 wait 中使用 selector 参数来等待特定元素变为可见，或者使用 milliseconds 来等待固定时长。
actions 按顺序执行：actions 会按顺序执行，Firecrawl 会在当前页面交互完成后再继续执行下一个 action。

高级操作示例

执行截图操作：

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",
    "actions": [
      { "type": "click", "selector": "#load-more" },
      { "type": "wait", "milliseconds": 1000 },
      { "type": "screenshot", "fullPage": true, "quality": 80 }
    ]
  }'

点击多个元素：

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",
    "actions": [
      { "type": "click", "selector": ".expand-button", "all": true },
      { "type": "wait", "milliseconds": 500 }
    ],
    "formats": ["markdown"]
  }'

生成 PDF 文件：

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",
    "actions": [
      { "type": "pdf", "format": "A4", "landscape": false }
    ]
  }'

示例用法

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://docs.firecrawl.dev",
      "formats": [
        "markdown",
        "links",
        "html",
        "rawHtml",
        { "type": "screenshot", "fullPage": true, "quality": 80 }
      ],
      "includeTags": ["h1", "p", "a", ".main-content"],
      "excludeTags": ["#ad", "#footer"],
      "onlyMainContent": false,
      "waitFor": 1000,
      "timeout": 15000,
      "parsers": ["pdf"]
    }'

在此示例中，scraper 将：

以 Markdown 返回完整页面内容。
在响应中包含 Markdown、原始 HTML、HTML、链接以及截图。
仅包含 HTML 标签 <h1>、<p>、<a>，以及类名为 .main-content 的元素，同时排除任何 ID 为 #ad 和 #footer 的元素。
在开始抓取前等待 1000 毫秒（1 秒），以便页面加载。
将抓取请求的最长持续时间设置为 15000 毫秒（15 秒）。
通过 parsers: ["pdf"] 显式解析 PDF。

API 参考： Scrape Endpoint Documentation

通过 formats 进行 JSON 提取

在 formats 中使用 JSON 格式对象，一次性提取结构化数据：

curl -X POST https://api.firecrawl.dev/v2/scrape \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer fc-YOUR-API-KEY' \
  -d '{
    "url": "https://firecrawl.dev",
    "formats": [{
      "type": "json",
      "prompt": "Extract the features of the product",
      "schema": {"type": "object", "properties": {"features": {"type": "object"}}, "required": ["features"]}
    }]
  }'

Extract 接口

当你需要通过轮询状态来进行异步提取时，请使用专门的 Extract 任务 API。

import Firecrawl from '@mendable/firecrawl-js';

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

// Start extract job
const started = await firecrawl.startExtract({
  urls: ['https://docs.firecrawl.dev'],
  prompt: 'Extract title',
  schema: { type: 'object', properties: { title: { type: 'string' } }, required: ['title'] }
});

// Poll status
const status = await firecrawl.getExtractStatus(started.id);
console.log(status.status, status.data);

抓取多个页面

要抓取多个页面，请使用 /v2/crawl 端点。

cURL

curl -X POST https://api.firecrawl.dev/v2/crawl \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer fc-YOUR-API-KEY' \
    -d '{
      "url": "https://docs.firecrawl.dev"
    }'

返回一个 ID

{ "id": "1234-5678-9101" }

检查抓取任务

用于查看抓取任务的状态并获取其结果。

cURL

curl -X GET https://api.firecrawl.dev/v2/crawl/1234-5678-9101 \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer fc-YOUR-API-KEY'

分页/下一页 URL

如果内容大小超过 10MB，或者爬取任务仍在运行，响应中可能会包含一个 next 参数，即指向下一页结果的 URL。

爬取提示与参数预览

你可以提供自然语言的 prompt，让 Firecrawl 自动推导爬取设置。请先预览结果：

cURL

curl -X POST https://api.firecrawl.dev/v2/crawl/params-preview \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer fc-YOUR-API-KEY' \
  -d '{
    "url": "https://docs.firecrawl.dev",
    "prompt": "提取文档与博客"
  }'

爬虫选项

当使用 /v2/crawl 端点时，你可以使用以下选项来自定义爬取行为：

includePaths

类型: array
说明: 要包含的正则表达式模式。
示例: ["^/blog/.*$", "^/docs/.*$"]

excludePaths

类型: array
描述: 用于排除的正则表达式模式。
示例: ["^/admin/.*$", "^/private/.*$"]

maxDiscoveryDepth

类型: integer
描述: 查找新 URL 的最大发现深度。

limit

类型: integer
描述: 爬取的最大页面数量。
默认值: 10000

crawlEntireDomain

类型: boolean
描述: 跨同级/父级页面扩展爬取以覆盖整个域名。
默认值: false

allowExternalLinks

类型: boolean
描述: 跟随指向外部域名的链接。
默认值: false

allowSubdomains

类型: boolean
描述: 允许跟踪主域的子域名。
默认值: false

delay

Type: number
Description: 每次抓取之间的延迟（单位：秒）。
Default: undefined

scrapeOptions

类型: object
描述: 抓取器选项（参见上面的格式）。
示例: { "formats": ["markdown", "links", {"type": "screenshot", "fullPage": true}], "includeTags": ["h1", "p", "a", ".main-content"], "excludeTags": ["#ad", "#footer"], "onlyMainContent": false, "waitFor": 1000, "timeout": 15000}
默认值: formats: ["markdown"]，默认启用缓存（maxAge 约 2 天）

示例用法

cURL

curl -X POST https://api.firecrawl.dev/v2/crawl \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer fc-你的-API-KEY' \
    -d '{
      "url": "https://docs.firecrawl.dev",
      "includePaths": ["^/blog/.*$", "^/docs/.*$"],
      "excludePaths": ["^/admin/.*$", "^/private/.*$"],
      "maxDiscoveryDepth": 2,
      "limit": 1000
    }'

网站链接映射

/v2/map 端点用于查找与指定网站相关的 URL。

使用方法

cURL

curl -X POST https://api.firecrawl.dev/v2/map \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer fc-YOUR-API-KEY' \
    -d '{
      "url": "https://docs.firecrawl.dev"
    }'

映射选项

search

类型: string
描述: 过滤包含指定文本的链接。

limit

类型: integer
描述: 返回的链接数量最大值。
默认值: 100

sitemap

类型: "only" | "include" | "skip"
描述: 控制在映射时对 sitemap 的使用。
默认值: "include"

includeSubdomains

类型: boolean
说明: 是否包含该网站的子域名。
默认值: true

Firecrawl 白名单设置

允许 Firecrawl 抓取你的网站

如果你希望 Firecrawl 抓取自己的网站，并且需要将该爬虫添加到白名单：

User Agent（用户代理）：Firecrawl 使用 FirecrawlAgent 作为 User Agent 标识自身。请在防火墙或安全规则中允许该 User Agent 字符串。
IP Addresses（IP 地址）：Firecrawl 在对外发起抓取请求时不会使用固定的 IP 地址范围。

允许你的应用调用 Firecrawl API

如果你的防火墙阻止应用向外部服务发出出站请求，请将 35.245.250.27 加入白名单，以允许你的应用调用 Firecrawl 的 API。

快速入门

新功能

标准功能

Webhook 回调

开发者指南

使用场景

参与贡献

​使用 Firecrawl 进行基础抓取

​抓取 PDF

​抓取选项

​formats（formats）

​全页内容 vs 主内容（onlyMainContent）

​包含标签（includeTags）

​排除标签（excludeTags）

​等待页面就绪（waitFor）

​新鲜度与缓存（maxAge）

​请求超时（timeout）

​PDF 解析（parsers）

​actions（actions）

​actions 执行注意事项

​高级操作示例

​示例用法

​通过 formats 进行 JSON 提取

​Extract 接口

​抓取多个页面

​检查抓取任务

​分页/下一页 URL

​爬取提示与参数预览

​爬虫选项

​includePaths

​excludePaths

​maxDiscoveryDepth

​limit

​crawlEntireDomain

​allowExternalLinks

​allowSubdomains

​delay

​scrapeOptions

​示例用法

​网站链接映射

​使用方法

​映射选项

​search

​limit

​sitemap

​includeSubdomains

​Firecrawl 白名单设置

​允许 Firecrawl 抓取你的网站

​允许你的应用调用 Firecrawl API

使用 Firecrawl 进行基础抓取

抓取 PDF

抓取选项

formats（`formats`）

全页内容 vs 主内容（`onlyMainContent`）

包含标签（`includeTags`）

排除标签（`excludeTags`）

等待页面就绪（`waitFor`）

新鲜度与缓存（`maxAge`）

请求超时（`timeout`）

PDF 解析（`parsers`）

actions（`actions`）

actions 执行注意事项

高级操作示例

示例用法

通过 formats 进行 JSON 提取

Extract 接口

抓取多个页面

检查抓取任务

分页/下一页 URL

爬取提示与参数预览

爬虫选项

includePaths

excludePaths

maxDiscoveryDepth

limit

crawlEntireDomain

allowExternalLinks

allowSubdomains

delay

scrapeOptions

示例用法

网站链接映射

使用方法

映射选项

search

limit

sitemap

includeSubdomains

Firecrawl 白名单设置

允许 Firecrawl 抓取你的网站

允许你的应用调用 Firecrawl API