firecrawl-scraper

Firecrawl 网页抓取工具

状态：已可用于生产环境 ✅ 最后更新：2026-08-03 官方文档：https://docs.firecrawl.dev API 版本：v2.5

---

什么是 Firecrawl？

Firecrawl 是面向 AI 的网页数据 API，可将整个网站转换为适用于大模型的 Markdown 或结构化数据。它支持：

• JavaScript 渲染 - 执行客户端 JavaScript，以捕获动态内容
• 绕过反机器人机制 - 绕过 CAPTCHA 和机器人检测系统
• 格式转换 - 输出 Markdown、JSON 或结构化数据
• 截图捕获 - 保存页面的可视化呈现
• 浏览器自动化 - 提供完整的无头浏览器功能

---

API 端点

1. /v2/scrape - 单页抓取

抓取单个网页并返回干净、结构化的内容。

适用场景：

• 提取文章内容
• 获取产品详情
• 抓取指定页面
• 将 HTML 转换为 Markdown

主要选项：

• formats：["markdown", "html", "screenshot"]
• onlyMainContent：true/false（移除导航栏、页脚和广告）
• waitFor：抓取前等待的毫秒数
• actions：浏览器自动化操作（点击、滚动等）

2. /v2/crawl - 全站爬取

从起始 URL 爬取所有可访问的页面。

适用场景：

• 为整个文档网站建立索引
• 归档网站内容
• 构建知识库
• 抓取多页内容

主要选项：

• limit：爬取的最大页面数
• maxDepth：跟进链接的最大深度
• allowedDomains：限制为指定域名
• excludePaths：跳过特定 URL 模式

3. /v2/map - URL 发现

映射网站上的所有 URL，但不抓取内容。

适用场景：

• 查找站点地图
• 发现所有页面
• 规划爬取策略
• 审查网站结构

4. /v2/extract - 结构化数据提取

使用 AI 从页面中提取指定的数据字段。

适用场景：

• 提取产品价格和名称
• 解析联系信息
• 构建结构化数据集
• 自定义数据模式

主要选项：

• schema：用于定义所需结构的 Zod 或 JSON 模式
• systemPrompt：引导 AI 的提取行为

---

身份验证

所有 Firecrawl 请求都需要 API 密钥。

获取 API 密钥

1. 在 https://www.firecrawl.dev 注册
2. 前往控制面板 → API Keys
3. 复制 API 密钥（以 fc- 开头）

安全存储

切勿将 API 密钥硬编码在代码中！

# .env file
FIRECRAWL_API_KEY=fc-your-api-key-here

# .env.local (for local development)
FIRECRAWL_API_KEY=fc-your-api-key-here

---

SDK 快速入门

Python

pip install firecrawl-py  # v4.5.0+

from firecrawl import FirecrawlApp
import os

app = FirecrawlApp(api_key=os.environ.get("FIRECRAWL_API_KEY"))
result = app.scrape_url("https://example.com", params={"formats": ["markdown"], "onlyMainContent": True})
print(result.get("markdown"))

TypeScript/Node.js

bun add @mendable/firecrawl-js  # v4.32.0+

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

const app = new FirecrawlApp({ apiKey: process.env.FIRECRAWL_API_KEY });
const result = await app.scrapeUrl('https://example.com', { formats: ['markdown'], onlyMainContent: true });
console.log(result.markdown);

参见：templates/ 中的爬取、提取和高级示例

---

常见用例

用例	端点	主要选项
抓取文档	crawl_url()	limit: 500、allowedDomains
提取产品数据	extract()	Zod 模式 + systemPrompt
抓取新闻文章	scrape_url()	onlyMainContent: true、removeBase64Images
发现 URL	map()	爬取前查找所有页面

参见：references/common-patterns.md 中的完整示例。

---

错误处理

# Python
try:
    result = app.scrape_url("https://example.com")
except FirecrawlException as e:
    print(f"Firecrawl error: {e}")

// TypeScript
try {
  const result = await app.scrapeUrl('https://example.com');
} catch (error) {
  console.error('Error:', error.message);
}

---

速率限制与最佳实践

最佳实践	原因
使用 onlyMainContent: true	减少积分消耗，让输出更简洁
设置合理的 limit	避免过高成本
先使用 map 端点	规划爬取策略
缓存结果	避免重复抓取
批量调用 extract	处理多个 URL 时效率更高

积分：免费套餐每月 500 积分，付费套餐额度更高。

---

集成 Cloudflare Workers

⚠️ SDK 无法在 Workers 中运行（依赖 Node.js）。请使用直接 REST API：

const response = await fetch('https://api.firecrawl.dev/v2/scrape', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${env.FIRECRAWL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ url, formats: ['markdown'], onlyMainContent: true })
});

参见：references/common-patterns.md 中包含缓存的完整 Workers 示例。

---

何时使用此技能

✅ 使用 Firecrawl	❌ 不要使用
现代 JS 渲染的网站	简单的静态 HTML（使用 cheerio）
适用于大模型的简洁 Markdown	现有的 Puppeteer 配置可正常工作
RAG/聊天机器人内容	有可用的直接 API
结构化数据提取	预算受限
绕过机器人防护

---

常见问题

问题	原因	修复方法
"Invalid API Key"	未设置密钥	检查 $FIRECRAWL_API_KEY 是否以 fc- 开头
"Rate limit exceeded"	已用完月度额度	检查控制面板，升级套餐
"Timeout error"	页面加载缓慢	添加 waitFor: 10000
"Content is empty"	JS 加载延迟	添加 actions: [{type: "wait", milliseconds: 3000}]

---

高级功能

功能	用法
浏览器操作	actions: [{type: "click", selector: "button"}]
自定义标头	headers: {"User-Agent": "Custom Bot"}
Webhook	webhook: "https://your-domain.com/webhook"
屏幕截图	formats: ["screenshot"]

参见：references/endpoints.md，了解完整的 API 参考。

---

何时加载参考文档

参考文档	加载时机……
endpoints.md	需要完整的 API 端点文档
common-patterns.md	Cloudflare Workers、缓存、批处理、错误处理

---

软件包版本

软件包	版本
firecrawl-py	4.5.0+
@mendable/firecrawl-js	4.32.0+
API	v2

注意：Node.js SDK 要求 Node.js >=22.0.0，无法在 Workers 中运行。

---

官方文档：https://docs.firecrawl.dev | GitHub：https://github.com/mendableai/firecrawl

节省 Token：约 60% | 适用于生产环境：✅