Firecrawl 搜索与网页抓取 API 详细部署教程

Firecrawl 是一个强大的开源 API 服务，专为 AI 应用设计，能够将网页内容转化为干净的 Markdown 或结构化 JSON 数据。它支持搜索、抓取、爬取以及与网页交互（如点击、滚动），是构建 AI 智能体数据管道的理想工具。本教程将指导您如何使用 Firecrawl 的云服务和自托管部署。

📋 目录

Firecrawl 是什么
核心功能概览
云服务快速开始（推荐）
自托管部署
核心用法与 SDK
AI 智能体集成
更新与卸载
常见问题与注意事项

Firecrawl 是什么

Firecrawl 是一个“网页上下文 API”，专门解决 AI 应用从互联网获取干净、结构化数据的难题。它负责处理代理、速率限制、JavaScript 渲染等复杂问题，输出 LLM 友好的格式。

核心优势：

高可靠性：覆盖 96% 的网页，包括 JavaScript 重页面。
极速响应：P95 延迟仅 3.4 秒，适合实时应用。
LLM 就绪输出：输出 Markdown、结构化 JSON、截图等，减少 token 消耗。
开发者友好：提供 Python、Node.js、Go、Java 等多种 SDK，并支持 MCP（模型上下文协议）和 CLI 工具。

核心功能概览

功能	描述	典型用途
搜索 (Search)	搜索网络并从结果中获取完整页面内容	查找最新信息、新闻或特定主题资料
抓取 (Scrape)	将任何 URL 转换为 Markdown、HTML、截图或结构化 JSON	提取单页内容，用于摘要或数据录入
交互 (Interact)	抓取页面后，通过 AI 提示或代码与之交互（点击、滚动、输入）	自动化表单提交、登录、搜索后提取数据
智能体 (Agent)	用自然语言描述需求，AI 自动搜索、导航和检索数据，无需提供 URL	“查找 Firecrawl 的创始人”，自动整合信息
爬取 (Crawl)	通过单次请求抓取整个网站的所有 URL	文档站点迁移、内容索引
地图 (Map)	即时发现网站上的所有 URL	了解网站结构、构建站点地图
批量抓取	异步抓取数千个 URL	大规模数据采集

云服务快速开始（推荐）

这是最快捷的方式，无需管理基础设施。

1. 注册并获取 API 密钥
访问 Firecrawl 官网注册账号，登录后在仪表板获取您的 API 密钥（形如 fc-YOUR_API_KEY）。

2. 安装 SDK（以 Python 为例）

1	pip install firecrawl-py

3. 开始使用

搜索：

from firecrawl import Firecrawl

app = Firecrawl(api_key="fc-YOUR_API_KEY")
search_result = app.search("最新 AI 新闻", limit=5)
print(search_result)

抓取单页：

1 2	result = app.scrape('https://example.com') print(result.markdown) # 输出干净的 Markdown 内容

使用智能体（Agent） ：

1
2
3

# 自动搜索并整理信息
result = app.agent(prompt="请找到 Firecrawl 项目的创始人及其背景信息")
print(result.data)

爬取整个网站：

# 爬取文档站点，限制 50 页
docs = app.crawl("https://docs.firecrawl.dev", limit=50)
for doc in docs.data:
    print(doc.metadata.source_url)

自托管部署

Firecrawl 是开源软件（AGPL-3.0），您可以将其部署在自己的基础设施上。以下提供两种主流方式。

方式一：使用 Docker Compose（推荐）

官方提供了 docker-compose.yaml 文件，可以一键启动所有依赖服务。

1. 克隆仓库

1 2	git clone https://github.com/firecrawl/firecrawl.git cd firecrawl

2. 启动服务

1	docker-compose up -d

此命令会拉取并启动 Firecrawl API、Worker、FoundationDB 等必需容器。

3. 验证服务
服务启动后，API 默认监听 http://localhost:3000。您可以通过以下命令测试：

1
2
3

curl -X POST http://localhost:3000/v2/scrape \
  -H 'Content-Type: application/json' \
  -d '{"url": "https://example.com"}'

注意事项：

自托管版本可能缺少云服务的某些高级功能（如内置代理池）。
请根据您的负载调整 docker-compose.yaml 中的资源限制和环境变量。
完整配置选项请参考项目中的 SELF_HOST.md 文件。

方式二：从源码构建

适合需要深度定制或二次开发的场景。

环境要求：

Node.js 18+
包管理器 (npm/yarn/pnpm)
Python 3.9+ (部分辅助脚本)
FoundationDB (用于状态存储)

构建步骤：

# 1. 克隆并安装依赖
git clone https://github.com/firecrawl/firecrawl.git
cd firecrawl
npm install

# 2. 构建项目
npm run build

# 3. 启动 API 服务（需确保 FoundationDB 运行）
npm run start:api

详细的开发环境配置请阅读项目根目录的 CONTRIBUTING.md。

核心用法与 SDK

Firecrawl 提供多种语言的 SDK，用法高度一致。

Node.js SDK：

import { Firecrawl } from 'firecrawl';

const app = new Firecrawl({ apiKey: 'fc-YOUR_API_KEY' });

// 交互（Interact）示例
const scrapeResult = await app.scrape('https://amazon.com');
await app.interact(scrapeResult.metadata.scrapeId, {
  prompt: "搜索 '机械键盘'"
});

Go SDK：

package main

import (
    "context"
    "fmt"
    firecrawl "github.com/firecrawl/firecrawl/apps/go-sdk"
)

func main() {
    client, _ := firecrawl.NewClient()
    ctx := context.Background()
    
    // 使用智能体并指定努力程度
    result, _ := client.Agent(ctx, &firecrawl.AgentOptions{
        Prompt: "比较 Firecrawl 和 Apify 的企业功能",
        Effort: "high",  // low, medium, high
    })
    fmt.Println(result.Data)
}

其他 SDK（Java、.NET、Ruby、PHP、Rust 等）的安装和使用方式请参考项目文档。

AI 智能体集成

Firecrawl 能轻松集成到各种 AI 智能体框架中。

1. 通过 MCP（模型上下文协议）集成
在 Claude Desktop 等 MCP 客户端的配置文件中添加：

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

配置后，您的 AI 助手就能直接调用 Firecrawl 的工具搜索和抓取网页。

2. 通过 CLI 一键安装技能
对于支持技能的 CLI 助手（如 Claude Code），可以运行：

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

重启智能体后，它便获得了实时网页数据访问能力。

更新与卸载

云服务：由官方维护，无需您操心更新。
自托管 Docker：
- 更新：docker-compose pull && docker-compose up -d
- 卸载：docker-compose down -v （-v 会删除数据卷）
源码构建：
- 更新：git pull 并重新 npm install && npm run build
- 卸载：删除项目目录即可。

常见问题与注意事项

Firecrawl 如何处理网站的 robots.txt？
默认情况下，Firecrawl 尊重网站的 robots.txt 规则。

自托管版本与云服务的功能差异？
云服务包含额外的优化（如内置代理池、更高并发）。自托管版本适合开发测试或对数据隐私有极高要求的场景。

使用 Firecrawl 有什么法律风险？
用户有责任遵守目标网站的隐私政策和服务条款。 请合理使用，避免对目标网站造成过大负担。

API 调用的计费方式？
使用云服务时，API 调用消耗积分（credits）。具体的计费标准请参考官网定价页面。自托管版本无此费用。

通过以上步骤，您应该能够顺利开始使用 Firecrawl。如需获取最新的 API 细节和高级配置选项，建议直接查阅其官方文档和 API 参考。