> ## Documentation Index
> Fetch the complete documentation index at: https://student-213fb9fc.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Node

> Firecrawl Node SDK 是对 Firecrawl API 的封装，帮助你轻松将网站转换为 Markdown。

<div id="installation">
  ## 安装
</div>

要安装 Firecrawl 的 Node SDK，你可以使用 npm：

```js Node theme={null}
# 使用 npm 安装 @mendable/firecrawl-js

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

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

<div id="usage">
  ## 使用
</div>

1. 在 [firecrawl.dev](https://firecrawl.dev) 获取 API 密钥
2. 将该密钥设置为名为 `FIRECRAWL_API_KEY` 的环境变量，或作为参数传递给 `FirecrawlApp` 类。

以下是一个包含错误处理的 SDK 使用示例：

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

const firecrawl = new Firecrawl({apiKey: "fc-YOUR_API_KEY"});

// 抓取网站内容
const scrapeResponse = await firecrawl.scrape('https://firecrawl.dev', {
  formats: ['markdown', 'html'],
});

console.log(scrapeResponse)

// 爬取整站
const crawlResponse = await firecrawl.crawl('https://firecrawl.dev', {
  limit: 100,
  scrapeOptions: {
    formats: ['markdown', 'html'],
  }
});

console.log(crawlResponse)
```

<div id="scraping-a-url">
  ### 抓取单个 URL
</div>

要带错误处理地抓取单个 URL，请使用 `scrapeUrl` 方法。它接收 URL 作为参数，并以字典形式返回抓取结果。

```js Node theme={null}
// 抓取网站：
const scrapeResult = await firecrawl.scrape('firecrawl.dev', { formats: ['markdown', 'html'] });

console.log(scrapeResult)
```

<div id="crawling-a-website">
  ### 爬取网站
</div>

要在具备错误处理的情况下爬取网站，请使用 `crawlUrl` 方法。它接收起始 URL 和可选参数。通过 `params` 参数，你可以为爬取任务指定其他选项，例如最大爬取页数、允许的域名以及输出格式。有关自动/手动分页与限制的说明，请参见 [Pagination](#pagination)。

```js Node（Node.js） theme={null}
const job = await firecrawl.crawl('https://docs.firecrawl.dev', { limit: 5, pollInterval: 1, timeout: 120 });
console.log(job.status);
```

<div id="sitemap-only-crawl">
  ### 仅爬取 Sitemap
</div>

使用 `sitemap: "only"` 仅爬取 sitemap 中的 URL（起始 URL 始终会被包含，并且会跳过 HTML 链接发现过程）。

```js Node theme={null}
const job = await firecrawl.crawl('https://docs.firecrawl.dev', {
  sitemap: 'only',
  limit: 25,
});
console.log(job.status, job.data.length);
```

<div id="start-a-crawl">
  ### 启动 Crawl
</div>

使用 `startCrawl` 可立即启动作业且无需等待。它会返回一个作业 `ID`，可用于查询状态。若需要在完成前阻塞等待的方式，请使用 `crawl`。分页行为和限制详见 [Pagination](#pagination)。

```js Node theme={null}
const { id } = await firecrawl.startCrawl('https://docs.firecrawl.dev', { limit: 10 });
console.log(id);
```

<div id="checking-crawl-status">
  ### 检查爬取状态
</div>

要在带错误处理的情况下检查爬取任务的状态，请使用 `checkCrawlStatus` 方法。它接收 `ID` 作为参数，并返回该爬取任务的当前状态。

```js Node theme={null}
const status = await firecrawl.getCrawlStatus("<crawl-id>");
console.log(status);
```

<div id="cancelling-a-crawl">
  ### 取消爬取
</div>

要取消爬取任务，请使用 `cancelCrawl` 方法。该方法接收 `startCrawl` 返回的任务 ID 作为参数，并返回取消结果。

```js Node theme={null}
const ok = await firecrawl.cancelCrawl("<crawl-id>");
console.log("已取消：", ok);
```

<div id="mapping-a-website">
  ### 网站映射
</div>

要在包含错误处理的情况下进行网站映射，请使用 `mapUrl` 方法。该方法接收起始 URL 作为参数，并以字典形式返回映射结果。

```js Node theme={null}
const res = await firecrawl.map('https://firecrawl.dev', { limit: 10 });
console.log(res.links);
```

<div id="crawling-a-website-with-websockets">
  ### 使用 WebSockets 爬取网站
</div>

要通过 WebSockets 爬取网站，请使用 `crawlUrlAndWatch` 方法。它接受起始 URL 和可选参数。`params` 参数可用于为爬取任务指定更多选项，例如最大爬取页数、允许的域名，以及输出 formats。

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

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

// 启动一次爬取并开始监控
const { id } = await firecrawl.startCrawl('https://mendable.ai', {
  excludePaths: ['blog/*'],
  limit: 5,
});

const watcher = firecrawl.watcher(id, { kind: 'crawl', pollInterval: 2, timeout: 120 });

watcher.on('document', (doc) => {
  console.log('DOC', doc);
});

watcher.on('error', (err) => {
  console.error('ERR', err?.error || err);
});

watcher.on('done', (state) => {
  console.log('DONE', state.status);
});

// 开始监控（优先使用 WS，回退到 HTTP）
await watcher.start();
```

<div id="pagination">
  ### 分页
</div>

当有更多数据可用时，Firecrawl 的 /crawl 和 batch 端点会返回一个 `next` URL。Node SDK 默认会自动分页并汇总所有文档；在这种情况下，`next` 将为 `null`。你可以禁用自动分页或设置上限。

<div id="crawl">
  #### 抓取
</div>

使用 waiter 方法 `crawl` 以获得最简便的体验，或启动一个任务并手动逐页处理。

<div id="simple-crawl-auto-pagination-default">
  ##### 简单爬取（自动分页，默认）
</div>

* 请参阅[网站爬取](#crawling-a-website)中的默认流程。

<div id="manual-crawl-with-pagination-control-single-page">
  ##### 手动抓取与分页控制（单页）
</div>

* 先启动作业，然后将 `autoPaginate: false` 设置为禁用自动分页，逐页获取。

```js 节点 theme={null}
const crawlStart = await firecrawl.startCrawl('https://docs.firecrawl.dev', { limit: 5 });
const crawlJobId = crawlStart.id;

const crawlSingle = await firecrawl.getCrawlStatus(crawlJobId, { autoPaginate: false });
console.log('单页抓取：', crawlSingle.status, '文档数：', crawlSingle.data.length, '下一页：', crawlSingle.next);
```

<div id="manual-crawl-with-limits-auto-pagination-early-stop">
  ##### 设有限制的手动抓取（自动分页 + 提前停止）
</div>

* 保持自动分页开启，但可通过 `maxPages`、`maxResults` 或 `maxWaitTime` 提前停止。

```js 节点 theme={null}
const crawlLimited = await firecrawl.getCrawlStatus(crawlJobId, {
  autoPaginate: true,
  maxPages: 2,
  maxResults: 50,
  maxWaitTime: 15,
});
console.log('受限爬取：', crawlLimited.status, '文档数：', crawlLimited.data.length, '下一页：', crawlLimited.next);
```

<div id="batch-scrape">
  #### 批量抓取
</div>

使用等待器方法 `batchScrape`，或手动启动作业并逐页处理。

<div id="simple-batch-scrape-auto-pagination-default">
  ##### 简单批量抓取（自动分页，默认）
</div>

* 默认流程请参见[批量抓取](/zh/features/batch-scrape)。

<div id="manual-batch-scrape-with-pagination-control-single-page">
  ##### 手动批量抓取并控制分页（单页）
</div>

* 启动作业，将 `autoPaginate: false` 以禁用自动分页，并按页逐一获取。

```js Node theme={null}
const batchStart = await firecrawl.startBatchScrape([
  'https://docs.firecrawl.dev',
  'https://firecrawl.dev',
], { options: { formats: ['markdown'] } });
const batchJobId = batchStart.id;

const batchSingle = await firecrawl.getBatchScrapeStatus(batchJobId, { autoPaginate: false });
console.log('批量单页：', batchSingle.status, '文档数：', batchSingle.data.length, '下一页：', batchSingle.next);
```

<div id="manual-batch-scrape-with-limits-auto-pagination-early-stop">
  ##### 手动批量抓取并设定限制（自动分页 + 提前停止）
</div>

* 保持自动分页开启，但可通过 `maxPages`、`maxResults` 或 `maxWaitTime` 提前停止。

```js Node theme={null}
const batchLimited = await firecrawl.getBatchScrapeStatus(batchJobId, {
  autoPaginate: true,
  maxPages: 2,
  maxResults: 100,
  maxWaitTime: 20,
});
console.log('批处理受限：', batchLimited.status, '文档数：', batchLimited.data.length, '下一个：', batchLimited.next);
```

<div id="browser">
  ## 浏览器
</div>

在云端启动浏览器会话并远程执行代码。

<div id="create-a-session">
  ### 创建会话
</div>

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

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

const session = await firecrawl.browser({ ttl: 300 });
console.log(session.id);          // 会话 ID
console.log(session.cdpUrl);      // wss://cdp-proxy.firecrawl.dev/cdp/...
console.log(session.liveViewUrl); // https://liveview.firecrawl.dev/...
```

<div id="execute-code">
  ### 执行代码
</div>

```js Node theme={null}
const result = await firecrawl.browserExecute(session.id, {
  code: 'await page.goto("https://news.ycombinator.com")\ntitle = await page.title()\nprint(title)',
});
console.log(result.result); // "Hacker News"
```

改为执行 JavaScript（而非 Python）：

```js Node theme={null}
const result = await firecrawl.browserExecute(session.id, {
  code: 'await page.goto("https://example.com"); const t = await page.title(); console.log(t);',
  language: "node",
});
```

通过 agent-browser 执行 Bash：

```js Node theme={null}
const result = await firecrawl.browserExecute(session.id, {
  code: "agent-browser open https://example.com && agent-browser snapshot",
  language: "bash",
});
```

<div id="profiles">
  ### 配置文件
</div>

在会话之间持久化并复用浏览器状态（cookies、localStorage 等）：

```js Node theme={null}
const session = await firecrawl.browser({
  ttl: 300,
  profile: {
    name: "my-profile",
    saveChanges: true,
  },
});
```

<div id="connect-via-cdp">
  ### 通过 CDP 连接
</div>

要获得对 Playwright 的完全控制能力，请使用 CDP URL 直接连接：

```js Node theme={null}
import { chromium } from "playwright";

const browser = await chromium.connectOverCDP(session.cdpUrl);
const context = browser.contexts()[0];
const page = context.pages()[0] || await context.newPage();

await page.goto("https://example.com");
console.log(await page.title());

await browser.close();
```

<div id="list-close-sessions">
  ### 列出 & 关闭会话
</div>

```js Node theme={null}
// 列出活动会话
const { sessions } = await firecrawl.listBrowsers({ status: "active" });
for (const s of sessions) {
  console.log(s.id, s.status, s.createdAt);
}

// 关闭会话
await firecrawl.deleteBrowser(session.id);
```

<div id="error-handling">
  ## 错误处理
</div>

SDK 会处理 Firecrawl API 返回的错误并抛出相应异常。若在请求过程中发生错误，将抛出包含详细错误信息的异常。上面的示例展示了如何使用 `try/catch` 代码块来处理这些错误。