Node - Firecrawl Docs

从你的 Node.js 应用中抓取单个页面、爬取整个站点，并映射 URL。SDK 会处理分页、重试和异步任务轮询，让你能够专注于使用返回的数据。

安装#

使用 npm 安装 SDK：

Node

// 使用 npm 安装 firecrawlimport { Firecrawl } from 'firecrawl';const firecrawl = new Firecrawl({  // 无需 API 密钥即可开始使用 — 添加一个以获得更高的限流额度：  // apiKey: "fc-YOUR-API-KEY",});

使用#

在 firecrawl.dev 获取 API 密钥
将该密钥设置为名为 FIRECRAWL_API_KEY 的环境变量，或作为参数传递给 Firecrawl 类。

Note

没有 API 密钥？ 你可以在不提供密钥的情况下构造 Firecrawl，并在免密钥的 Free 档位中使用 scrape、search 和 interact (按 IP 限流——请参见限流) 。所有其他方法都需要密钥。

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

Node

import { Firecrawl } from 'firecrawl';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)

抓取单个 URL#

使用 scrape 方法抓取单个 URL，并返回结构化的页面数据。

Node

// 抓取网站：const scrapeResult = await firecrawl.scrape('firecrawl.dev', { formats: ['markdown', 'html'] });console.log(scrapeResult)

解析上传的文件#

当你想上传本地文件 (html、pdf、docx、xlsx 等) ，而不是通过 URL 抓取时，请使用 parse。 parse 不支持 changeTracking，也不支持仅适用于浏览器的选项，例如 screenshot、branding、actions、waitFor、location 和 mobile。

Node

const parsed = await firecrawl.parse(  {    data: "<html><body><h1>Node Parse</h1></body></html>",    filename: "upload.html",    contentType: "text/html",  },  {    formats: ["markdown"],  },);console.log(parsed.markdown);

爬取网站#

使用 crawl 方法从单个 URL 开始爬取整个网站。你可以设置页面上限，将范围限制在特定域名内，并选择输出格式。请参见 Pagination 了解自动和手动分页。

Node（Node.js）

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

仅爬取 Sitemap#

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

Node

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

启动爬取#

使用 startCrawl 可启动一次爬取且无需等待其完成。该方法会返回一个任务 ID，供你稍后轮询。若需要阻塞等待直到完成，请改用 crawl。分页行为和限制详见 Pagination。

Node

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

检查爬取状态#

使用 checkCrawlStatus 方法检查爬取任务当前是仍在运行、已完成还是已失败。传入 startCrawl 返回的任务 ID。

Node

const status = await firecrawl.getCrawlStatus("<crawl-id>");console.log(status);

取消爬取#

使用 cancelCrawl 方法取消正在运行中的爬取。传入由 startCrawl 返回的任务 ID。

Node

const ok = await firecrawl.cancelCrawl("<crawl-id>");console.log("已取消：", ok);

网站映射#

使用 map 方法可发现网站上的所有 URL。传入起始 URL，即可返回已发现页面的列表。

Node

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

运行代理#

使用 agent 方法将研究或提取任务交给代理。传入 prompt、用于定义输出结构的可选 schema，以及用于限制本次运行额度消耗的 maxCredits。

Node

import { Firecrawl } from 'firecrawl';import { z } from 'zod';const firecrawl = new Firecrawl({ apiKey: "fc-YOUR_API_KEY" });const result = await firecrawl.agent({  prompt: "Find the founders of Firecrawl",  schema: z.object({    founders: z.array(z.object({      name: z.string().describe("Full name of the founder"),      role: z.string().describe("Role or position").optional(),      background: z.string().describe("Professional background").optional()    })).describe("List of founders")  }),  model: "spark-2",  maxCredits: 100});console.log(result.data);

代理运行是异步的。使用 startAgent 可立即获取任务 ID，然后通过 getAgentStatus 轮询任务状态。

Node

import { Firecrawl } from 'firecrawl';const firecrawl = new Firecrawl({ apiKey: "fc-YOUR_API_KEY" });// 启动一个 Agent 任务const started = await firecrawl.startAgent({  prompt: "Find the founders of Firecrawl"});// 检查任务状态if (started.id) {  const status = await firecrawl.getAgentStatus(started.id);  console.log(status.status, status.data);}

每次运行还会记录执行追踪和输出快照，你可以使用 getAgentTrace 和 getAgentSnapshot 读取它们。事件 schema 和完整参数列表请参见 Agent。

使用 WebSockets 爬取网站#

使用 watcher(jobId, options) 实时流式获取爬取结果。你会在每个页面完成爬取时立即收到结果，无需等待整个任务结束。

Node

import { Firecrawl } from 'firecrawl';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();

分页#

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

抓取#

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

简单爬取 (自动分页，默认)

请参阅网站爬取中的默认流程。

手动抓取与分页控制 (单页)

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

节点

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);

设有限制的手动抓取 (自动分页 + 提前停止)

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

节点

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

批量抓取#

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

简单批量抓取 (自动分页，默认)

默认流程请参见批量抓取。

手动批量抓取并控制分页 (单页)

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

Node

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);

手动批量抓取并设定限制 (自动分页 + 提前停止)

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

Node

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

浏览器#

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

创建会话#

Node

import { Firecrawl } from 'firecrawl';const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });const session = await firecrawl.browser({ ttl: 600 });console.log(session.id);          // 会话 IDconsole.log(session.cdpUrl);      // wss://cdp-proxy.firecrawl.dev/cdp/...console.log(session.liveViewUrl); // https://liveview.firecrawl.dev/...

执行代码#

Node

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：

Node

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：

Node

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

浏览器配置#

保存浏览器状态 (cookies、localStorage 等) ，以便跨会话复用：

Node

const session = await firecrawl.browser({  ttl: 600,  profile: {    name: "my-profile",    saveChanges: true,  },});

通过 CDP 连接#

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

Node

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();

查看并关闭会话#

Node

// 列出活跃会话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);

绑定到抓取任务的交互式会话#

使用抓取任务 ID，可在该次抓取回放后的页面上下文中继续交互：

interact(jobId, {...}) 会在绑定到抓取任务的浏览器会话中运行代码。
首次调用 interact 时，会基于抓取上下文自动初始化会话。
对同一任务 ID 再次调用 interact 时，会复用当前的浏览器状态。
完成后，可使用 stopInteraction(jobId) 停止交互式会话。

Node

const doc = await firecrawl.scrape("https://example.com", {  actions: [{ type: "click", selector: "a[href='/pricing']" }],});const scrapeJobId = doc.metadata?.scrapeId;if (!scrapeJobId) throw new Error("Missing scrape job id");const run = await firecrawl.interact(scrapeJobId, {  code: "console.log(await page.url())",  language: "node",  timeout: 60,});console.log(run.stdout);await firecrawl.stopInteraction(scrapeJobId);

错误处理#

SDK 会针对 Firecrawl API 返回的任何错误抛出包含详细信息的异常。请像上面的示例所示，使用 try/catch 代码块包装调用。

你是需要 Firecrawl API 密钥的 AI 代理吗？请参阅 firecrawl.dev/agent-onboarding/SKILL.md 了解自动化接入说明。

安装#

使用#

抓取单个 URL#

解析上传的文件#

爬取网站#

仅爬取 Sitemap#

启动 爬取#

检查爬取状态#

取消爬取#

网站映射#

运行代理#

使用 WebSockets 爬取网站#

分页#

抓取#

简单爬取 (自动分页，默认)

手动抓取与分页控制 (单页)

设有限制的手动抓取 (自动分页 + 提前停止)

批量抓取#

简单批量抓取 (自动分页，默认)

手动批量抓取并控制分页 (单页)

手动批量抓取并设定限制 (自动分页 + 提前停止)

浏览器#

创建会话#

执行代码#

浏览器配置#

通过 CDP 连接#

查看并关闭会话#

绑定到抓取任务的交互式会话#

错误处理#

启动爬取#