高级抓取指南 - Firecrawl Docs

涵盖 Firecrawl 的抓取、爬取、map 和代理各端点下所有选项的参考说明。

基础抓取#

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

# pip install firecrawl-pyfrom firecrawl import Firecrawlfirecrawl = Firecrawl(api_key="fc-YOUR-API-KEY")doc = firecrawl.scrape("https://firecrawl.dev")print(doc.markdown)

抓取 PDF#

Firecrawl 支持 PDF。需要确保解析 PDF 时，请使用 parsers 选项 (例如 parsers: ["pdf"]) 。你可以通过 mode 选项来控制解析策略：

auto (默认) — 先尝试基于文本的快速提取，如有需要再回退到 OCR。
fast — 仅进行基于文本 (嵌入文本) 的解析。速度最快，但会跳过扫描件或图片较多的页面。
ocr — 对每一页强制使用 OCR 解析。适用于扫描文档，或在 auto 误判页面类型时使用。

{ type: "pdf" } 和 "pdf" 都默认使用 mode: "auto"。

"parsers": [{ "type": "pdf", "mode": "fast", "maxPages": 50 }]

抓取选项#

使用 /scrape 端点时，你可以通过以下选项来自定义请求。

Formats (`formats`)#

formats 数组控制抓取器返回哪些输出类型。默认值：["markdown"]。

字符串格式：直接传入名称 (例如 "markdown") 。

格式	描述
`markdown`	页面内容转换为干净的 Markdown。
`html`	处理后的 HTML，已移除不必要的元素。
`rawHtml`	服务器返回的原始 HTML，保持原样。
`rawBase64`	经 Base64 编码的原始 HTTP 响应正文，以纯 Base64 字符串形式返回。必须是请求中唯一的格式。MIME 类型位于 `metadata.contentType`。
`links`	页面上发现的所有链接。
`images`	页面上发现的所有图片。
`summary`	由 LLM 生成的页面内容摘要。
`branding`	提取品牌标识信息 (颜色、字体、版式、间距、UI 组件) 。
`product`	通过多源结构化数据从产品页面提取结构化产品信息 (标题、价格、库存状态、图片、变体) 。

对象格式：传入包含 type 和其他选项的对象。

格式	选项	描述
`json`	`prompt?: string`, `schema?: object`	使用 LLM 提取结构化数据。提供 JSON schema 和/或自然语言 prompt (最多 10,000 个字符) 。
`screenshot`	`fullPage?: boolean`, `quality?: number`, `viewport?: { width, height }`	捕获截图。每个请求最多一个。视口最大分辨率为 7680×4320。截图 URL 会在 24 小时后过期。
`changeTracking`	`modes?: ("json" \| "git-diff")[]`, `tag?: string`, `schema?: object`, `prompt?: string`	跟踪不同抓取结果之间的变化。需要在 formats 数组中同时包含 `"markdown"`。
`attributes`	`selectors: [{ selector: string, attribute: string }]`	从匹配 CSS 选择器的元素中提取指定的 HTML 属性。

移动端抓取#

设置 mobile: true 以模拟移动设备。当响应式网站在桌面端隐藏部分内容，或为移动浏览器提供不同布局时，这很有用。

对于有区域差异的网站，可结合 location 和移动端截图来验证渲染后的布局：

from firecrawl import Firecrawlfirecrawl = Firecrawl(api_key="fc-YOUR-API-KEY")doc = firecrawl.scrape(    "https://example.com",    mobile=True,    location={"country": "GB", "languages": ["en-GB"]},    formats=[        "markdown",        {"type": "screenshot", "fullPage": True, "viewport": {"width": 390, "height": 844}},    ],    only_main_content=False,    wait_for=2000,)print(doc.markdown)

如果站点在设置 mobile: true 后仍然呈现桌面端布局，请通过 headers 添加移动端 User-Agent：

{  "headers": {    "User-Agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1"  }}

内容过滤#

这些参数用于控制页面的哪些部分会出现在输出中。当 onlyMainContent 为 true (默认值) 时，会先去掉页面框架内容 (导航、页脚等) 。includeTags 和 excludeTags 是基于原始页面 DOM 而不是过滤后的结果进行匹配的，因此你的选择器应以元素在源 HTML 中的实际呈现为准。若将 onlyMainContent: false，则会使用整页 HTML 作为后续标签过滤的起点。

参数	类型	默认值	描述
`onlyMainContent`	`boolean`	`true`	仅返回主体内容。设为 `false` 则返回整页内容。
`includeTags`	`array`	—	要包含的 CSS 选择器——标签、类、ID 或属性选择器 (例如 `["h1", "p", ".main-content", "[data-testid=\"main\"]"]`) 。
`excludeTags`	`array`	—	要排除的 CSS 选择器——标签、类、ID 或属性选择器 (例如 `["#ad", "#footer", "[role=\"banner\"]"]`) 。

时间与缓存#

参数	类型	默认值	描述
`waitFor`	`integer` (ms)	`0`	在抓取前额外等待的时间，会叠加在智能等待的基础上。请谨慎使用。
`maxAge`	`integer` (ms)	`172800000`	如果缓存的存在时间小于该值，则返回缓存结果 (默认 2 天) 。设为 `0` 则始终获取最新内容。
`timeout`	`integer` (ms)	`60000`	在中止请求前允许的最长请求耗时 (默认 60 秒) 。最小值为 1000 (1 秒) 。

PDF 解析#

参数	类型	默认值	描述
`parsers`	`array`	`["pdf"]`	控制 PDF 处理。使用 `[]` 跳过解析并返回 base64 (固定费用 1 额度) 。

{ "type": "pdf", "mode": "fast" | "auto" | "ocr", "maxPages": 10, "pages": true, "blocks": true, "pageMarkers": true }

属性	类型	默认值	描述
`type`	`"pdf"`	(必填)	解析器类型。
`mode`	`"fast" \| "auto" \| "ocr"`	`"auto"`	`fast`：仅进行基于文本的提取。`auto`：快速模式，必要时回退到 OCR。`ocr`：强制使用 OCR。
`maxPages`	`integer`	—	解析的最大页数上限。
`pages`	`boolean`	`false`	同时在文档的 `pages` 字段中返回按物理页面划分的 Markdown。无需额外成本。
`blocks`	`boolean`	`false`	同时在文档的 `blocks` 字段中返回每页带类型信息的布局块 (标准化边界框、块类型、阅读顺序、Markdown 字符跨度) 。无需额外成本。
`pageMarkers`	`boolean`	`false`	使用 `<!-- page N -->` 标记在文档 Markdown 中标注分页 (仅位于页面之间；跨分页处合并的页面可能导致编号跳过 — 请参见解析) 。无需额外成本。

Actions#

在抓取前执行浏览器 actions。这对于动态内容、页面导航或受用户访问限制的页面很有用。每个请求最多可包含 50 个 action，且所有 wait action 与 waitFor 的累计等待时间不得超过 60 秒。

Action	Parameters	Description
`wait`	`milliseconds?: number`, `selector?: string`	按固定时长等待，或等待直到某个元素可见 (两者选其一，不要同时提供) 。使用 `selector` 时，30 秒后会超时。
`click`	`selector: string`, `all?: boolean`	点击与 CSS 选择器匹配的元素。设置 `all: true` 可点击所有匹配项。
`write`	`text: string`	在当前获得焦点的字段中输入文本。你必须先通过 `click` action 让该元素获得焦点。
`press`	`key: string`	按下键盘按键 (例如 `"Enter"`、`"Tab"`、`"Escape"`) 。
`scroll`	`direction?: "up" \| "down"`, `selector?: string`	滚动页面或某个特定元素。`direction` 的默认值为 `"down"`。
`screenshot`	`fullPage?: boolean`, `quality?: number`, `viewport?: { width, height }`	截取屏幕截图。最大视口分辨率为 7680×4320。
`scrape`	(none)	在 action 序列执行到此处时捕获当前页面的 HTML。
`executeJavascript`	`script: string`	在页面中运行 JavaScript 代码。返回值可在响应的 `actions.javascriptReturns` 数组中获取。
`pdf`	`format?: string`, `landscape?: boolean`, `scale?: number`	生成 PDF。支持的格式：`"A0"` 到 `"A6"`、`"Letter"`、`"Legal"`、`"Tabloid"`、`"Ledger"`。默认值为 `"Letter"`。

from firecrawl import Firecrawlfirecrawl = 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 前，需要先执行一次 click 以聚焦目标元素。
Scroll 可以接受一个可选的 selector，用于滚动特定元素而不是整个页面。
Wait 接受 milliseconds (固定延迟) 或 selector (等待元素可见) 两种参数中的一种。
actions 按顺序执行：每一步都会在下一步开始前完成。
actions 不支持 PDF。如果 URL 解析为 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": "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 }    ]  }'

执行 JavaScript (例如提取页面内嵌数据) ：

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": "executeJavascript", "script": "document.querySelector(\"#__NEXT_DATA__\").textContent" }    ],    "formats": ["markdown"]  }'

每个 executeJavascript 操作的返回值都会记录在响应中的 actions.javascriptReturns 数组里。

完整抓取示例#

以下请求组合了多个抓取选项：

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"]    }'

该请求会返回 Markdown、HTML、原始 HTML、链接以及整页截图。它将内容范围限定为 <h1>、<p>、<a> 和 .main-content，同时排除 #ad 和 #footer，在开始抓取前等待 1 秒，将超时时间设置为 15 秒，并启用 PDF 解析。

有关详细信息，请参阅完整的 Scrape API 参考文档。

通过 formats 提取 JSON#

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

from firecrawl import Firecrawlfirecrawl = Firecrawl(api_key='fc-YOUR-API-KEY')doc = firecrawl.scrape('https://firecrawl.dev', {  'formats': [{    'type': 'json',    'prompt': 'Extract the features of the product',    'schema': {      'type': 'object',      'properties': { 'features': { 'type': 'object' } },      'required': ['features']    }  }]})print(doc.json)

代理端点#

使用 /v2/agent 端点进行自动化的多页面数据提取。代理以异步方式运行：你先创建一个任务，然后通过轮询获取结果。

代理是此端点的权威参考，包含执行追踪、Webhook 和完整参数列表。

代理选项#

参数	类型	默认值	描述
`prompt`	`string`	(必填)	自然语言说明，用于描述要提取哪些数据 (最多 10,000 个字符) 。
`urls`	`array`	—	将代理的访问限制在这些 URL。
`schema`	`object`	—	用于组织提取数据结构的 JSON schema。
`maxCredits`	`number`	`2500`	代理可消耗的最大额度。Dashboard 最多支持 2,500；如需更高上限，请通过 API 设置 (高于 2,500 的值始终按付费请求计费) 。
`strictConstrainToURLs`	`boolean`	`false`	为 `true` 时，代理只会访问提供的这些 URL。
`model`	`string`	`"spark-2"`	要使用的 AI 模型。Spark 1 模型已弃用，目前会路由到 `"spark-2"`。
`effort`	`string`	(未设置)	推理预算：`"low"`、`"medium"` 或 `"high"`。每次运行均在 `"spark-2"` 上执行，因此无论是否指定 `model`，都可以发送 `effort`。

from firecrawl import Firecrawlfirecrawl = Firecrawl(api_key='fc-YOUR-API-KEY')# 启动代理任务started = firecrawl.start_agent(    prompt="Extract the title and description",    urls=["https://docs.firecrawl.dev"],    schema={"type": "object", "properties": {"title": {"type": "string"}, "description": {"type": "string"}}, "required": ["title"]})# 轮询状态status = firecrawl.get_agent_status(started["id"])print(status.get("status"), status.get("data"))

检查 agent 状态#

轮询 GET /v2/agent/{jobId} 以检查进度。响应中的 status 字段将为 "processing"、"completed" 或 "failed"。

cURL

curl -X GET https://api.firecrawl.dev/v2/agent/YOUR-JOB-ID \  -H 'Authorization: Bearer fc-YOUR-API-KEY'

Python 和 Node SDK 还提供了一个便捷方法 (firecrawl.agent()) ，用于启动任务并自动轮询，直到任务完成。

爬取多个页面#

要爬取多个页面，请使用 /v2/crawl 端点。爬取会以异步方式运行，并返回一个任务 ID。使用 limit 参数控制爬取的页面数量。若省略该参数，爬取最多会处理 10,000 个页面。

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",      "limit": 10    }'

返回结果#

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

检查爬取任务#

使用任务 ID 检查爬取状态并获取结果。

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'

如果内容大于 10MB，或者爬取任务仍在运行中，响应中可能包含 next 参数，也就是下一页结果的 URL。

爬取 prompt 和参数预览#

你可以提供自然语言 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": "Extract docs and blog"  }'

爬虫选项#

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

路径过滤#

参数	类型	默认值	说明
`includePaths`	`array`	—	要包含的 URL 的正则表达式模式 (默认仅匹配路径名) 。
`excludePaths`	`array`	—	要排除的 URL 的正则表达式模式 (默认仅匹配路径名) 。
`regexOnFullURL`	`boolean`	`false`	在完整 URL 上进行模式匹配，而不仅仅是路径名。

Warning

起始 URL 也会与 includePaths 进行匹配。如果它不匹配任何模式，爬取结果可能会返回 0 个页面。

爬取范围#

参数	类型	默认值	描述
`maxDiscoveryDepth`	`integer`	—	用于发现新 URL 的最大链接深度。
`limit`	`integer`	`10000`	最大爬取页面数。
`crawlEntireDomain`	`boolean`	`false`	通过遍历同级和父级页面来覆盖整个域名。
`allowExternalLinks`	`boolean`	`false`	跟踪指向外部域名的链接。
`allowSubdomains`	`boolean`	`false`	跟踪主域名下的子域名。
`delay`	`number` (s)	—	两次爬取之间的延迟时间 (秒) 。设置此项会强制并发数为 1。

Sitemap 和去重#

Parameter	Type	Default	Description
`sitemap`	`string`	`"include"`	`"include"`：使用 sitemap + 链接发现。`"skip"`：忽略 sitemap。`"only"`：仅抓取 sitemap 中的 URL。
`deduplicateSimilarURLs`	`boolean`	`true`	将 URL 变体 (`www.`、`https`、结尾斜杠、`index.html`) 视为同一 URL 进行规范化去重。
`ignoreQueryParameters`	`boolean`	`false`	在去重前移除查询字符串 (例如将 `/page?a=1` 和 `/page?a=2` 视为同一个 URL) 。

爬取任务的抓取选项#

参数	类型	默认值	描述
`scrapeOptions`	`object`	`{ formats: ["markdown"] }`	每个页面的抓取配置。支持上述所有抓取选项。

抓取示例#

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"    }'

Map 选项#

参数	类型	默认值	描述
`search`	`string`	—	按文本匹配筛选链接。
`limit`	`integer`	`100`	返回的最大链接数。
`sitemap`	`string`	`"include"`	`"include"`、`"skip"` 或 `"only"`。
`includeSubdomains`	`boolean`	`true`	包含子域名。

其 API 参考文档见此：Map 端点文档

Firecrawl 白名单设置#

允许 Firecrawl 抓取你的网站#

User Agent (用户代理) ：请在防火墙或安全规则中允许 FirecrawlAgent。
IP addresses (IP 地址) ：Firecrawl 不使用固定的对外 IP 地址集合。

允许你的应用调用 Firecrawl API#

如果你的防火墙阻止应用向外部服务发出出站请求，你需要将 Firecrawl 的 API 服务器 IP 地址加入白名单，这样你的应用才能访问 Firecrawl API (api.firecrawl.dev) ：

IP Address: 35.245.250.27

将此 IP 添加到防火墙的出站允许列表中，这样你的后端就可以向 Firecrawl 发送抓取 (scrape) 、爬取 (crawl) 、映射 (map) 以及智能体 (agent) 请求。

基础抓取#

抓取 PDF#

抓取选项#

Formats (formats)#

移动端抓取#

内容过滤#

时间与缓存#

PDF 解析#

Actions#

actions 执行说明#

高级操作示例#

完整抓取示例#

通过 formats 提取 JSON#

代理端点#

代理选项#

检查 agent 状态#

爬取多个页面#

返回结果#

检查爬取任务#

爬取 prompt 和参数预览#

爬虫选项#

路径过滤#

爬取范围#

Sitemap 和去重#

爬取任务的抓取选项#

抓取示例#

网站链接映射#

Map 选项#

Firecrawl 白名单设置#

允许 Firecrawl 抓取你的网站#

允许你的应用调用 Firecrawl API#

Formats (`formats`)#