名称: firecrawl-scraper 描述: Firecrawl v2.5 API 用于网页抓取/爬取，转换为LLM-ready markdown。适用于站点提取、动态内容、或遇到JavaScript渲染、机器人检测、内容加载错误的情况。

关键词: firecrawl, firecrawl api, 网页抓取, 网页爬虫, 抓取网站, 爬取网站, 提取内容, html转markdown, 站点爬虫, 内容提取, 网页自动化, firecrawl-py, firecrawl-js, llm就绪数据, 结构化数据提取, 机器人绕过, javascript渲染, 抓取api, 爬取api, 映射urls, 批量抓取许可证: MIT

Firecrawl 网页爬取技能

状态: 生产就绪 ✅ 最后更新: 2025-11-21 官方文档: https://docs.firecrawl.dev API版本: v2.5

什么是Firecrawl？

Firecrawl 是一个 用于AI的网页数据API，能够将整个网站转换为LLM-ready的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密钥

在 https://www.firecrawl.dev 注册
转到仪表板 → API密钥
复制您的API密钥（以 fc- 开头）

安全存储

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

# .env 文件
FIRECRAWL_API_KEY=fc-your-api-key-here

# .env.local (用于本地开发)
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.4.1+

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错误: {e}")

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

速率限制与最佳实践

最佳实践	原因
使用 `onlyMainContent: true`	减少积分使用，输出更干净
设置合理的 `limit`	避免过度成本
先使用 `map` 端点	计划爬取策略
缓存结果	避免重复抓取
批量提取调用	对多个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）
为LLMs提供干净的markdown	现有Puppeteer设置有效
RAG/聊天机器人内容	直接API可用
结构化数据提取	预算限制
机器人保护绕过

常见问题

问题	原因	修复
“无效API密钥”	密钥未设置	检查 `$FIRECRAWL_API_KEY` 以 `fc-` 开头
“速率限制超过”	月度积分用尽	检查仪表板，升级计划
“超时错误”	页面加载慢	添加 `waitFor: 10000`
“内容为空”	JS加载晚	添加 `actions: [{type: \"wait\", milliseconds: 3000}]`

高级功能

功能	用法
浏览器操作	`actions: [{type: \"click\", selector: \"button\"}]`
自定义头部	`headers: {\"User-Agent\": \"自定义机器人\"}`
Webhooks	`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.4.1+
API	v2

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

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

令牌节省: ~60% | 生产就绪: ✅

Firecrawl 网页爬取技能

什么是Firecrawl？

API端点

1. /v2/scrape - 单页抓取

2. /v2/crawl - 全站爬取

3. /v2/map - URL发现

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

认证

获取API密钥

安全存储

SDK快速入门

Python

TypeScript/Node.js

常见使用案例

错误处理

速率限制与最佳实践

Cloudflare Workers集成

何时使用此技能

常见问题

高级功能

何时加载参考

包版本

1. `/v2/scrape` - 单页抓取

2. `/v2/crawl` - 全站爬取

3. `/v2/map` - URL发现

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