> ## 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.

# 高级抓取指南

> 通过 Firecrawl 的完整 API 接口配置抓取选项、浏览器 actions、爬取、映射以及 代理 端点。

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

<div id="basic-scraping">
  ## 基础抓取
</div>

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

<CodeGroup>
  ```python Python theme={null}
  # 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)
  ```

  ```js Node theme={null}
  // npm install firecrawl

  import { Firecrawl } from 'firecrawl-js';

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

  const doc = await firecrawl.scrape('https://firecrawl.dev');

  console.log(doc.markdown);
  ```

  ```bash cURL theme={null}
  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"
      }'
  ```
</CodeGroup>

<div id="scraping-pdfs">
  ## 抓取 PDF
</div>

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

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

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

```json theme={null}
"parsers": [{ "type": "pdf", "mode": "fast", "maxPages": 50 }]
```

<div id="scrape-options">
  ## 抓取选项
</div>

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

<div id="formats-formats">
  ### Formats (`formats`)
</div>

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

**字符串 formats**：直接传入名称 (例如 `"markdown"`) 。

| Format     | Description                                  |
| ---------- | -------------------------------------------- |
| `markdown` | 页面内容转换为干净的 Markdown。                         |
| `html`     | 处理后的 HTML，已移除不必要的元素。                         |
| `rawHtml`  | 服务器返回的原始 HTML，保持原样。                          |
| `links`    | 页面上发现的所有链接。                                  |
| `images`   | 页面上发现的所有图片。                                  |
| `summary`  | 由 LLM 生成的页面内容摘要。                             |
| `branding` | 提取品牌标识信息 (颜色、字体、版式、间距、UI 组件) 。               |
| `product`  | 通过多源结构化数据从产品页面提取结构化产品信息 (标题、价格、库存状态、图片、变体) 。 |

**对象 formats**：传入包含 `type` 和其他选项的对象。

| Format           | Options                                                                                  | Description                                                    |
| ---------------- | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| `json`           | `prompt?: string`, `schema?: object`                                                     | 使用 LLM 提取结构化数据。提供 JSON schema 和/或自然语言 prompt (最多 10,000 个字符) 。 |
| `screenshot`     | `fullPage?: boolean`, `quality?: number`, `viewport?: { width, height }`                 | 捕获截图。每个请求最多一个。viewport 最大分辨率为 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 属性。                                  |

<div id="mobile-scraping">
  ### 移动端抓取
</div>

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

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

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

  firecrawl = 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)
  ```

  ```js Node theme={null}
  import { Firecrawl } from 'firecrawl-js';

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

  const doc = await firecrawl.scrape('https://example.com', {
    mobile: true,
    location: { country: 'GB', languages: ['en-GB'] },
    formats: [
      'markdown',
      { type: 'screenshot', fullPage: true, viewport: { width: 390, height: 844 } },
    ],
    onlyMainContent: false,
    waitFor: 2000,
  });

  console.log(doc.markdown);
  ```

  ```bash cURL theme={null}
  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",
      "mobile": true,
      "location": {
        "country": "GB",
        "languages": ["en-GB"]
      },
      "formats": [
        "markdown",
        { "type": "screenshot", "fullPage": true, "viewport": { "width": 390, "height": 844 } }
      ],
      "onlyMainContent": false,
      "waitFor": 2000
    }'
  ```
</CodeGroup>

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

```json theme={null}
{
  "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"
  }
}
```

<div id="content-filtering">
  ### 内容过滤
</div>

这些参数用于控制页面的哪些部分会出现在输出中。当 `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\"]"]`) 。                |

<div id="timing-and-cache">
  ### 时间与缓存
</div>

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

<div id="pdf-parsing">
  ### PDF 解析
</div>

| 参数        | 类型      | 默认值       | 描述                                           |
| --------- | ------- | --------- | -------------------------------------------- |
| `parsers` | `array` | `["pdf"]` | 控制 PDF 处理。使用 `[]` 跳过解析并返回 base64（固定费用 1 积分）。 |

```json theme={null}
{ "type": "pdf", "mode": "fast" | "auto" | "ocr", "maxPages": 10 }
```

| 属性         | 类型                          | 默认值      | 描述                                                       |
| ---------- | --------------------------- | -------- | -------------------------------------------------------- |
| `type`     | `"pdf"`                     | *(必填)*   | 解析器类型。                                                   |
| `mode`     | `"fast" \| "auto" \| "ocr"` | `"auto"` | `fast`：仅进行基于文本的抽取。`auto`：快速模式，必要时回退到 OCR。`ocr`：强制使用 OCR。 |
| `maxPages` | `integer`                   | —        | 解析的最大页数上限。                                               |

<div id="actions">
  ### Actions
</div>

在抓取前执行浏览器 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"`。 |

<CodeGroup>
  ```python Python theme={null}
  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)
  ```

  ```js Node theme={null}
  import { Firecrawl } from 'firecrawl-js';

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

  const doc = await 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']
  });

  console.log(doc.markdown);
  ```

  ```bash cURL theme={null}
  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": "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"]
    }'
  ```
</CodeGroup>

<div id="action-execution-notes">
  #### actions 执行说明
</div>

* 在使用 **Write** 前，需要先执行一次 `click` 以聚焦目标元素。
* **Scroll** 可以接受一个可选的 `selector`，用于滚动特定元素而不是整个页面。
* **Wait** 接受 `milliseconds`（固定延迟）或 `selector`（等待元素可见）两种参数中的一种。
* actions 按**顺序**执行：每一步都会在下一步开始前完成。
* actions **不支持 PDF**。如果 URL 解析为 PDF 文档，请求将会失败。

<div id="advanced-action-examples">
  #### 高级操作示例
</div>

**执行截图操作：**

```bash cURL theme={null}
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 }
    ]
  }'
```

**点击多个元素：**

```bash cURL theme={null}
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 文件：**

```bash cURL theme={null}
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 (例如提取页面内嵌数据) ：**

```bash cURL theme={null}
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` 数组里。

<div id="full-scrape-example">
  ### 完整抓取示例
</div>

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

```bash cURL theme={null}
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 参考文档](https://docs.firecrawl.dev/api-reference/endpoint/scrape)。

<div id="json-extraction-via-formats">
  ## 通过 formats 提取 JSON
</div>

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

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

  firecrawl = 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)
  ```

  ```js Node theme={null}
  import { Firecrawl } from 'firecrawl-js';

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

  const doc = await firecrawl.scrape('https://firecrawl.dev', {
    formats: [{
      type: 'json',
      prompt: 'Extract the features of the product',
      schema: {
        type: 'object',
        properties: { features: { type: 'object' } },
        required: ['features']
      }
    }]
  });

  console.log(doc.json);
  ```

  ```bash cURL theme={null}
  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"]}
      }]
    }'
  ```
</CodeGroup>

<div id="agent-endpoint">
  ## Agent endpoint
</div>

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

<div id="agent-options">
  ### 代理选项
</div>

| 参数                      | 类型        | 默认值              | 描述                                                                         |
| ----------------------- | --------- | ---------------- | -------------------------------------------------------------------------- |
| `prompt`                | `string`  | *(required)*     | 自然语言说明，用于描述要提取哪些数据 (最多 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-1-mini"` | 要使用的 AI 模型。`"spark-1-mini"` (默认，成本降低 60%) 或 `"spark-1-pro"` (更高准确率) 。      |

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

  firecrawl = 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"))
  ```

  ```js Node theme={null}
  import { Firecrawl } from 'firecrawl';

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

  // 启动代理任务
  const started = await firecrawl.startAgent({
    prompt: 'Extract the title and description',
    urls: ['https://docs.firecrawl.dev'],
    schema: { type: 'object', properties: { title: { type: 'string' }, description: { type: 'string' } }, required: ['title'] }
  });

  // 轮询状态
  const status = await firecrawl.getAgentStatus(started.id);
  console.log(status.status, status.data);
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.firecrawl.dev/v2/agent \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer fc-YOUR-API-KEY' \
    -d '{
      "prompt": "Extract the title and description",
      "urls": ["https://docs.firecrawl.dev"],
      "schema": {"type": "object", "properties": {"title": {"type": "string"}, "description": {"type": "string"}}, "required": ["title"]}
    }'
  ```
</CodeGroup>

<div id="check-agent-status">
  ### 检查 agent 状态
</div>

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

```bash cURL theme={null}
curl -X GET https://api.firecrawl.dev/v2/agent/YOUR-JOB-ID \
  -H 'Authorization: Bearer fc-YOUR-API-KEY'
```

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

<div id="crawling-multiple-pages">
  ## 爬取多个页面
</div>

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

```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://docs.firecrawl.dev",
      "limit": 10
    }'
```

<div id="response">
  ### 返回结果
</div>

```json theme={null}
{ "id": "1234-5678-9101" }
```

<div id="check-crawl-job">
  ### 检查爬取任务
</div>

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

```bash cURL theme={null}
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。

<div id="crawl-prompt-and-params-preview">
  ### 爬取 prompt 和参数预览
</div>

你可以提供自然语言 `prompt`，让 Firecrawl 推导爬取设置。请先预览这些设置：

```bash cURL theme={null}
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"
  }'
```

<div id="crawler-options">
  ### 爬虫选项
</div>

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

<div id="path-filtering">
  #### 路径过滤
</div>

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

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

<div id="crawl-scope">
  #### 爬取范围
</div>

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

<div id="sitemap-and-deduplication">
  #### Sitemap 和去重
</div>

| 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）。                          |

<div id="scrape-options-for-crawl">
  #### 爬取任务的抓取选项
</div>

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

<div id="crawl-example">
  ### 抓取示例
</div>

```bash cURL theme={null}
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
    }'
```

<div id="mapping-website-links">
  ## 网站链接映射
</div>

`/v2/map` 端点用于识别与指定网站相关的 URL。

```bash cURL theme={null}
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"
    }'
```

<div id="map-options">
  ### Map 选项
</div>

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

其 API 参考文档见此：[Map 端点文档](https://docs.firecrawl.dev/api-reference/endpoint/map)

<div id="whitelisting-firecrawl">
  ## Firecrawl 白名单设置
</div>

<div id="allowing-firecrawl-to-scrape-your-website">
  ### 允许 Firecrawl 抓取你的网站
</div>

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

<div id="allowing-your-application-to-call-the-firecrawl-api">
  ### 允许你的应用调用 Firecrawl API
</div>

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

* **IP Address**: `35.245.250.27`

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