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

# 从 v1 迁移到 v2

> 关键变更、对应关系，以及升级到 v2 的前后示例片段。

<div id="overview">
  ## 概述
</div>

<div id="key-improvements">
  ### 关键改进
</div>

* **默认更快**：请求会使用 `maxAge`（默认 2 天）进行缓存，并启用合理的默认设置，如 `blockAds`、`skipTlsVerification` 和 `removeBase64Images`。

* **新的摘要格式**：现在可以将 `"summary"` 指定为格式，直接获取页面内容的精炼摘要。

* **更新的 JSON 提取**：JSON 提取和变更追踪现在使用对象格式：`{ type: "json", prompt, schema }`。旧的 `"extract"` 格式已重命名为 `"json"`。

* **更强大的截图选项**：使用对象形式：`{ type: "screenshot", fullPage, quality, viewport }`。

* **新的搜索来源**：通过设置 `sources` 参数，除网页结果外，还可在 `"news"` 和 `"images"` 中进行搜索。

* **基于提示的智能爬取**：传入自然语言 `prompt` 进行爬取，系统会自动推导路径/限制。开始任务前，可使用新的 /crawl/params-preview 端点检查推导出的选项。

<div id="quick-migration-checklist">
  ## 快速迁移清单
</div>

* 将 v1 客户端用法替换为 v2 客户端：
  * JS：`const firecrawl = new Firecrawl({ apiKey: 'fc-YOUR-API-KEY' })`
  * Python：`firecrawl = Firecrawl(api_key='fc-YOUR-API-KEY')`
  * API：改用新的 `https://api.firecrawl.dev/v2/` 端点。
* 更新格式：
  * 需要时使用 "summary"
  * JSON 模式：进行 JSON 抽取时使用 `{ type: "json", prompt, schema }`
  * Screenshot 和 Screenshot\@fullPage：指定选项时使用 screenshot 对象格式
* 在 SDK 中采用标准化的异步流程：
  * Crawls：`startCrawl` + `getCrawlStatus`（或 `crawl` 等待器）
  * Batch：`startBatchScrape` + `getBatchScrapeStatus`（或 `batchScrape` 等待器）
  * Extract：`startExtract` + `getExtractStatus`（或 `extract` 等待器）
* 爬取选项映射（见下文）
* 使用 `/crawl/params-preview` 检查爬取的 `prompt`

<div id="sdk-surface-v2">
  ## SDK 外观（v2）
</div>

<div id="jsts">
  ### JS/TS
</div>

#### 方法名变更 (v1 → v2)

**Scrape、Search 和 Map**

| v1 (Firecrawl)        | v2 (Firecrawl)            |
| --------------------- | ------------------------- |
| `scrapeUrl(url, ...)` | `scrape(url, options?)`   |
| `search(query, ...)`  | `search(query, options?)` |
| `mapUrl(url, ...)`    | `map(url, options?)`      |

**爬取**

| v1                          | v2                           |
| --------------------------- | ---------------------------- |
| `crawlUrl(url, ...)`        | `crawl(url, options?)` (等待器) |
| `asyncCrawlUrl(url, ...)`   | `startCrawl(url, options?)`  |
| `checkCrawlStatus(id, ...)` | `getCrawlStatus(id)`         |
| `cancelCrawl(id)`           | `cancelCrawl(id)`            |
| `checkCrawlErrors(id)`      | `getCrawlErrors(id)`         |

**批量抓取**

| v1                                | v2                               |
| --------------------------------- | -------------------------------- |
| `batchScrapeUrls(urls, ...)`      | `batchScrape(urls, opts?)` (等待器) |
| `asyncBatchScrapeUrls(urls, ...)` | `startBatchScrape(urls, opts?)`  |
| `checkBatchScrapeStatus(id, ...)` | `getBatchScrapeStatus(id)`       |
| `checkBatchScrapeErrors(id)`      | `getBatchScrapeErrors(id)`       |

**提取**

| v1                            | v2                     |
| ----------------------------- | ---------------------- |
| `extract(urls?, params?)`     | `extract(args)`        |
| `asyncExtract(urls, params?)` | `startExtract(args)`   |
| `getExtractStatus(id)`        | `getExtractStatus(id)` |

**其他 / 已移除**

| v1                                | v2                         |
| --------------------------------- | -------------------------- |
| `generateLLMsText(...)`           | (v2 SDK 中无)                |
| `checkGenerateLLMsTextStatus(id)` | (v2 SDK 中无)                |
| `crawlUrlAndWatch(...)`           | `watcher(jobId, options?)` |
| `batchScrapeUrlsAndWatch(...)`    | `watcher(jobId, options?)` |

***

<div id="python-sync">
  ### Python（同步）
</div>

<div id="method-name-changes-v1-v2">
  #### 方法名变更（v1 → v2）
</div>

**Scrape、Search 和 Map**

| v1                | v2            |
| ----------------- | ------------- |
| `scrape_url(...)` | `scrape(...)` |
| `search(...)`     | `search(...)` |
| `map_url(...)`    | `map(...)`    |

**Crawling**

| v1                        | v2                      |
| ------------------------- | ----------------------- |
| `crawl_url(...)`          | `crawl(...)`（waiter）    |
| `async_crawl_url(...)`    | `start_crawl(...)`      |
| `check_crawl_status(...)` | `get_crawl_status(...)` |
| `cancel_crawl(...)`       | `cancel_crawl(...)`     |

**Batch Scraping**

| v1                             | v2                             |
| ------------------------------ | ------------------------------ |
| `batch_scrape_urls(...)`       | `batch_scrape(...)`（waiter）    |
| `async_batch_scrape_urls(...)` | `start_batch_scrape(...)`      |
| `get_batch_scrape_status(...)` | `get_batch_scrape_status(...)` |
| `get_batch_scrape_errors(...)` | `get_batch_scrape_errors(...)` |

**Extraction**

| v1                        | v2                        |
| ------------------------- | ------------------------- |
| `extract(...)`            | `extract(...)`            |
| `start_extract(...)`      | `start_extract(...)`      |
| `get_extract_status(...)` | `get_extract_status(...)` |

**其他 / 已移除**

| v1                                   | v2                     |
| ------------------------------------ | ---------------------- |
| `generate_llms_text(...)`            | （v2 SDK 中无）            |
| `get_generate_llms_text_status(...)` | （v2 SDK 中无）            |
| `watch_crawl(...)`                   | `watcher(job_id, ...)` |

***

<div id="python-async">
  ### Python（异步）
</div>

* `AsyncFirecrawl` 提供相同的方法（均可 await）。

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

* 基础场景请使用字符串 formats："markdown"、"html"、"rawHtml"、"links"、"summary"、"images"。
* 请使用 `parsers: [ { "type": "pdf" } | "pdf" ]`，而非 `parsePDF`。
* 对于 JSON、变更跟踪和截图，请使用对象 formats：

<div id="json-format">
  ### JSON 格式
</div>

<CodeGroup>
  ```js Node theme={null}
  const formats = [ {
    "type": "json",
    "prompt": "从页面中提取公司使命。"
  }];

  doc = firecrawl.scrape(url, { formats });
  ```

  ```python Python theme={null}
  formats = [ { "type": "json", "prompt": "从页面中提取公司使命。" } ];

  doc = firecrawl.scrape(url, formats=formats);
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.firecrawl.dev/v2/scrape \
      -H 'Content-Type: application/json' \
      -H 'Authorization: Bearer YOUR_API_KEY' \
      -d '{
        "url": "https://docs.firecrawl.dev/",
        "formats": [{
          "type": "json",
          "prompt": "从页面中提取公司使命。"
        }]
      }'
  ```
</CodeGroup>

<div id="screenshot-format">
  ### 截图格式
</div>

<CodeGroup>
  ```js Node theme={null}
  // 截图格式（JS）
  const formats = [ { "type": "screenshot", "fullPage": true, "quality": 80, "viewport": { "width": 1280, "height": 800 } } ];

  doc = firecrawl.scrape(url, { formats });
  ```

  ```python Python theme={null}
  # 截图格式（Python）
  formats = [ { "type": "screenshot", "fullPage": true, "quality": 80, "viewport": { "width": 1280, "height": 800 } } ];
  doc = firecrawl.scrape(url, formats=formats);
  ```

  ```bash cURL theme={null}
  # 截图格式（cURL）
  curl -X POST https://api.firecrawl.dev/v2/scrape \
      -H 'Content-Type: application/json' \
      -H 'Authorization: Bearer YOUR_API_KEY' \
      -d '{
        "url": "https://docs.firecrawl.dev/",
        "formats": [{
          "type": "screenshot",
          "fullPage": true,
          "quality": 80,
          "viewport": { "width": 1280, "height": 800 }
        }]
      }'
  ```
</CodeGroup>

<div id="crawl-options-mapping-v1-v2">
  ## 爬取选项映射（v1 → v2）
</div>

| v1                      | v2                                    |
| ----------------------- | ------------------------------------- |
| `allowBackwardCrawling` | （已移除）请使用 `crawlEntireDomain`          |
| `maxDepth`              | （已移除）请使用 `maxDiscoveryDepth`          |
| `ignoreSitemap` (bool)  | `sitemap`（例如：“only”、“skip”或“include”） |
| (none)                  | `prompt`                              |

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

查看爬取参数预览示例：

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

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

  const params = await firecrawl.crawlParamsPreview('https://docs.firecrawl.dev', 'Extract docs and blog');
  console.log(params);
  ```

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

  firecrawl = Firecrawl(api_key='fc-YOUR-API-KEY')
  preview = firecrawl.crawl_params_preview(url='https://docs.firecrawl.dev', prompt='Extract docs and blog')
  print(preview)
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.firecrawl.dev/v2/crawl/params-preview \
      -H 'Content-Type: application/json' \
      -H 'Authorization: Bearer YOUR_API_KEY' \
      -d '{
        "url": "https://docs.firecrawl.dev",
        "prompt": "Extract docs and blog"
      }'
  ```
</CodeGroup>