Firecrawl 新手教程

01这是什么

Firecrawl 是一个把「网页 URL」变成「AI 可直接用的干净数据」的 API。你给它一个网址（或一个问题），它返回整洁的 Markdown、截图，或按你定义的 schema 抽好的结构化 JSON。

传统抓取要自己应付 JS 渲染、反爬、代理轮换、cookie、弹窗——Firecrawl 把这些全封装成一个 HTTP 调用。网页本来就不是给机器看的，它做的事就是把「给人看的网页」翻译成「给模型看的上下文」。

它不做什么（消除误解）

• 不是 AI 模型：它不「理解」内容，它负责把网页可靠地拿下来并清洗格式化。理解的事交给接入的 LLM。
• 不只是一个爬虫库：光 pip install 一个包跑不起来——云服务要有 API Key，自托管要拉起一套多容器服务（见第 5 节）。
• 不绕过 robots.txt 去偷数据：默认遵守网站的 robots.txt 规则，UA 是 FirecrawlAgent。合规边界要自己把握。
• 不是一次性的「下载器」：它会做页面清洗（去导航栏、cookie 横幅、广告），输出是为 token 效率优化的，不是逐字节保真的原始拷贝。

02为什么需要它

想让 LLM 用上实时网页数据，最常见的三条路都有硬伤：

它在生态里的位置

搜索 API 负责「找到 URL」（比如用 /search），Firecrawl 负责「把 URL 读干净」。2026 年大量 agent 栈（LangGraph、CrewAI、以及接进 Cursor / Claude 的 MCP）都把这类「fetch 整页」当默认工具。

03核心流程

无论云服务还是自托管，认知模型都是「给它一个任务，它返回可用的数据」。核心三条能力：

单页任务走 scrape；多 URL、不知道要爬哪些页面时，升级到 crawl（整站爬）、map（列出站内所有 URL）、agent（自然语言描述需求让它自动找）。

04两条路：云服务 vs 自托管

Firecrawl 有两种用法，选错会白费力气。先看差别，再决定走哪条。

本教程主线走云服务讲透核心概念与跑通流程，第 8 节单独讲自托管。

05环境自检

用云服务，先确认自己有没有三样东西：

• API Key：去 firecrawl.dev 注册后获取，形如 fc-xxx。在 Dashboard 的 API Keys 页能找到。
• 目标语言 SDK（或直接用 cURL，零安装）。
• 能上网——它访问的是公网网站。

选择你的 SDK / 调用方式

0660 秒实战：第一次抓取

最稳的验证方式：用 cURL 抓一页，看能不能拿到干净的 Markdown。把下面 fc-YOUR_KEY 换成你的 Key。

curl -X POST https://api.firecrawl.dev/v2/scrape \
  -H 'Authorization: Bearer fc-YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"url": "https://news.ycombinator.com", "formats": ["markdown"]}'

返回体里 data.markdown 就是清洗后的正文，data.metadata 带标题/描述等元信息。✅ 成功会看到类似：

{
  "success": true,
  "data": {
    "markdown": "[Hacker News](https://news.ycombinator.com)\n\n---\n\n...正文...",
    "metadata": { "title": "Hacker News", "statusCode": 200 }
  }
}

换 Python SDK，同一件事：

from firecrawl import Firecrawl

app = Firecrawl(api_key="fc-YOUR_KEY")
result = app.scrape("https://news.ycombinator.com", formats=["markdown"])
print(result["data"]["markdown"][:500])

07能拿回什么：输出格式

scrape 的 formats 参数决定输出。核心几种：

结构化抽取（json + schema）

不想拿回 Markdown 再让模型解析，就传一个 JSON schema，让 Firecrawl 直接返回你要的字段形状：

result = app.scrape(
    "https://www.amazon.com/...",
    formats=["json"],
    json_options={
        "schema": {
            "type": "object",
            "properties": {
                "title":  {"type": "string"},
                "price":  {"type": "number"},
                "rating": {"type": "number"}
            },
            "required": ["title", "price"]
        }
    }
)
print(result["data"]["json"])  # {"title": "...", "price": 123.45, ...}

08多页与整站：Crawl / Map / Agent

单页用 scrape。当「不止一页、但你不确定是哪些页」时，用下面三兄弟：

Map —— 先看这个站有哪些 URL

urls = app.map("https://firecrawl.dev", search="pricing")
print(urls)  # 列出与 pricing 相关的站内链接

Crawl —— 顺着链接把整站（或某分区）爬下来

docs = app.crawl("https://docs.firecrawl.dev", limit=50, formats=["markdown"])
for doc in docs["data"]:
    print(doc["metadata"]["sourceURL"])

crawl 是异步任务：提交后拿到 job id，SDK 会自动轮询直到完成。limit 控制最大页数，避免把整个站爬爆。

Agent —— 只描述需求，让它自己找自己抽

不预先给 URL，直接说你要什么，agent 会自动搜索、导航、抽取：

# 配合结构化 schema，拿回你要的字段
from pydantic import BaseModel

class Pricing(BaseModel):
    plan: str
    price: float

result = app.agent(
    prompt="Find the pricing plans for Notion",
    schema=Pricing
)

09需要点两下的页面：Interact

有的信息藏在登录后、分页后面、或要靠点几次才加载（比如在电商站搜个词再点开商品）。Firecrawl 的处理方式：

1. 先 scrape 页面，拿到 scrapeId；
2. 对同一个 scrapeId 调 interact，用自然语言或Playwright 代码让它操作页面（点击、输入、滚动、等待、按键盘）；
3. 操作完再读取页面最新内容。

scrape = app.scrape("https://www.amazon.com")
scrape_id = scrape["id"]

app.interact(scrape_id, prompt="Search for 'mechanical keyboard'")  # 自然语言即可
page = app.scrape(scrape_id)  # 读取交互后的页面
print(page["data"]["markdown"][:400])

10费用与额度

云服务按「积分（credit）」计费，抓取失败一般不扣分（唯一的例外：FIRE-1 agent 请求无论成败都计费）。核心换算：

高级能力（json 抽取增强、enhanced proxy 等）会额外计分，具体看定价页的 credits 表。

套餐速览（年付价，官网为准）

11进阶：自托管

量级大、要源码/数据主权、或公司内部要用，才走这条路。心里要有数：这不是装个 pip 包，是拉起一个微服务栈。

官方推荐从 Docker Compose 起步（docker compose up）。当前基线会跑：API 与 worker、Playwright、Redis、RabbitMQ、NuQ PostgreSQL，以及可选的 FoundationDB（用作任务队列后端）。只有 API 默认暴露到宿主机，端口 3002。

几个被官方点名的注意点

• 别用 apps/api/.env.example 当 compose 契约：根目录 .env 才对应 docker-compose.yaml。上手看官方 self-host 指南 + 你 checkout 那份 compose 文件。
• 离开可信网络前先加认证：默认 API 是无认证的。要外网访问先设计好鉴权、TLS、网络策略。
• 数据持久化要自己配：默认 compose 对 Postgres/Redis/RabbitMQ 没定义持久卷，数据要存活必须自己加 volume 并测试备份恢复。
• AI 功能默认没接模型：要用到 AI 特性时，自接 OpenAI / OpenAI 兼容端点 / Ollama。
• 反爬要自己补：开源基线用自带 Playwright + fetch 兜底；更强的反爬（代理轮换、Fire-engine）得自己接。

更正式的部署可参考仓库里的 Kubernetes manifests 与 Helm chart（作为版本化起点，不是替你拍板的生产架构）。

12不止于此：Agent / MCP 一键接入

Firecrawl 在 2026 年这么火，一大半是因为它能一键接进 AI agent。你的 Claude Code / Cursor / Windsurf 等 MCP 客户端，配好后能直接「联网查网页」。

接 MCP（Claude / Cursor / Windsurf 通用）

{
  "mcpServers": {
    "firecrawl-mcp": {
      "command": "npx",
      "args": ["-y", "firecrawl-mcp"],
      "env": { "FIRECRAWL_API_KEY": "fc-YOUR_KEY" }
    }
  }
}

接 Claude Code（skills，一条命令自动配好）

npx -y firecrawl-cli@latest init --all --browser

这条命令兼容 Claude Code、Antigravity、OpenCode 等客户端，agent 内置 skill 后就知道何时该去抓网页。

Cursor CLI：逐条命令配好 + 实际怎么用

如果你用的是 Cursor CLI（命令行 agent，不是图形界面 IDE），配 Firecrawl 很简单。Cursor CLI 会在启动时读取 .cursor/mcp.json，读取顺序是「项目级优先、全局兜底」——和 IDE 同一套机制。共有两条路径任选：

方式一：全局配置（个人常用，所有项目生效）

在用户主目录建/改 ~/.cursor/mcp.json，把下面这段合并进已有 mcpServers：

{
  "mcpServers": {
    "firecrawl": {
      "command": "npx",
      "args": ["-y", "firecrawl-mcp"],
      "env": { "FIRECRAWL_API_KEY": "fc-你的KEY" }
    }
  }
}

若你的机器没装 Node/npx，或用远端托管版更省事（无需本地进程，适合 CI 与 headless）：

{
  "mcpServers": {
    "firecrawl": {
      "url": "https://mcp.firecrawl.dev/fc-你的KEY/v2/mcp"
    }
  }
}

方式二：项目级配置（随仓库走，团队共享）

在项目根目录放 .cursor/mcp.json 并提交进 Git，队友拉下来即有同样工具。配置内容与上面完全一致，只是文件位置不同。项目级与全局同名服务器冲突时，以项目级为准。

用 Cursor CLI 自带命令确认 / 管理

配置写好即可用。Cursor CLI 也提供命令直接管理服务器，方便你在终端里核对：

# 列出已注册的 MCP 服务器
cursor agent mcp list

# headless 自动批准 MCP（避免交互询问）
cursor agent --approve-mcps -p "帮我抓 https://firecrawl.dev 首页并总结"

配好后：Firecrawl 会暴露哪些工具

第一次跑通：3 步看到 Firecrawl 真被调起来

配置写好保存后，开一个新终端（已开的终端不会重读 mcp.json），进入任意项目目录：

# 第 1 步：确认 firecrawl 出现在服务器列表里
cursor agent mcp list
# 看到类似 "firecrawl  firecrawl-mcp  stdio  npx -y firecrawl-mcp" 就 OK

# 第 2 步：进项目根目录（mcp.json 所在目录），起一个交互会话
cd /你的项目
cursor agent
# 看到类似 Cursor 启动画面，按提示选模型（Composer / Sonnet 都行）

# 第 3 步：在交互 prompt 里直接说人话
> 抓 https://firecrawl.dev 首页，用 3 句话告诉我这个产品干什么的

agent 会在终端里先回一句「我要调 firecrawl_scrape」，下方打印工具调用与返回，首次会弹一行"Allow once / Always"让你确认 MCP 工具是否可调——按方向键选 Always 之后这次会话就不再问。整个过程像这样：

> 抓 https://firecrawl.dev 首页，3 句话总结
✓ Calling firecrawl_scrape
  url: "https://firecrawl.dev"
  formats: ["markdown"]
✓ 1 credit used
Firecrawl 是一个把任意网页转成干净 Markdown / 结构化 JSON 的 API
服务，面向 AI agent 设计。它能爬整站、做 schema 抽取、配合 LLM
做结构化提取，并提供了官方 MCP 服务器让 Claude Code / Cursor /
Windsurf 等客户端一键联网。
> 

三种启动方式，按场景挑

# A. 交互式 REPL（边聊边追细节）
cursor agent
> 帮我调研 MCP 协议 2026 年的版本演进
> 抓 https://modelcontextprotocol.io 的 changelog 存到 ./changelog.md

# B. 一次性任务（脚本里最常用），-p 后跟 prompt
cursor agent -p "抓 https://news.ycombinator.com 当日 Top 10 标题与链接，列成 Markdown 表格"

# C. 管道喂 prompt（适合大量 prompt 批量跑）
echo "抓 https://example.com 并提取所有 h2 标题" | cursor agent -p -

# D. headless：自动批准所有 MCP 工具调用，省掉人工按 Allow
cursor agent --approve-mcps -p "调研 5 个网页抓取 MCP 并对比" > report.md

# E. 指定模型
cursor agent --model sonnet -p "对比 Firecrawl 和 Jina Reader 的差异"
cursor agent --model composer-1.5 -p "..."

6 组工具的真实 prompt 模板（直接抄）

进阶：串进脚本做批量

最常见的实战用法——把 prompt 列表喂给 cursor agent，每条出一份结果：

#!/usr/bin/env bash
# batch-research.sh：批量调研 10 家竞品官网首页
urls=(
  "https://firecrawl.dev"
  "https://jina.ai/reader"
  "https://www.diffbot.com"
  # ... 再加几条
)
for u in "${urls[@]}"; do
  echo "=== $u ==="
  cursor agent --approve-mcps -p "抓 $u ，3 句话总结它在做什么" \
    | tee -a research.md
  echo "" >> research.md
done

配合 cron / launchd 就能做「每天抓一次竞品首页出日报」。注意：headless 模式务必加 --approve-mcps，否则每个工具调用都要你点一下，回不到批处理场景。

常见坑 & 排错

• 改完 mcp.json 没生效：必须新开一个 cursor agent 会话，已开的进程不会重读文件。
• 每次都弹 Allow 询问：加 --approve-mcps（一次性任务）或交互里选 Always（当前会话）。
• firecrawl 工具不在 agent 的工具列表里：cursor agent mcp list 看是否注册成功；再 cat .cursor/mcp.json 看 JSON 是否合法（多逗号、引号错位最常见）。
• 调了工具但返回 401/402：到 firecrawl.dev/app 确认 KEY 有效、积分没用完。
• 超时（crawl 大站点）：crawl 是异步任务，agent 会自动轮询；终端可能被超时断，但任务在云端跑，下次重连会拿到结果。
• Windows 报 spawn npx ENOENT：把 command 改成 npx.cmd 的全路径，或改用远端 URL 模式（无需本地 Node）。

13真实用在哪

别把 Firecrawl 想窄成「爬虫」。它解决的是「任何需要把实时网页变成 AI 能用的结构数据」的地方：

14FAQ / 踩坑

15参考链接

仓库结构速览

firecrawl/
├── apps/
│   ├── api/                  # 核心 API 与 worker
│   ├── playwright-service-ts # 无头浏览器渲染服务
│   ├── go-html-to-md-service # HTML → Markdown 转换服务
│   ├── nuq-postgres          # 任务队列存储
│   ├── python-sdk, js-sdk,
│   │   go-sdk, java-sdk, …   # 各语言官方 SDK
│   └── ui/ingestion-ui       # 数据导入界面
├── skills/                   # 构建类 skill 源码
├── examples/                 # 示例
├── docker-compose.yaml       # 自托管编排
└── SELF_HOST.md              # 自托管要点