firecrawl 项目说明书

Doramagic 项目包 · 项目说明书

firecrawl 项目

生成时间：2026-05-11 04:15:16 UTC

项目概览

Firecrawl 是一个由 Mendable.ai 开发的开源网页抓取和爬虫平台，旨在将网站转换为可供大语言模型（LLM）使用的结构化数据。Firecrawl 提供从网站搜索、内容抓取、页面交互到智能代理的全栈解决方案，帮助开发者轻松获取互联网数据并用于 AI 应用开发。

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 Search（搜索）

继续阅读本节完整说明和来源证据。

章节 Scrape（抓取）

继续阅读本节完整说明和来源证据。

章节 Interact（交互）

继续阅读本节完整说明和来源证据。

项目简介

项目采用多语言 SDK 架构设计，提供了 Python、Node.js、Java、Ruby、Go、.NET、Rust、PHP 等多种编程语言的官方 SDK，支持开发者使用熟悉的开发环境集成 Firecrawl 功能。资料来源：README.md:1-50

核心功能模块

Firecrawl 平台提供四大核心功能模块，分别对应不同的网页数据采集场景：

Search（搜索）

Search 模块支持对互联网进行自然语言搜索，返回与查询关键词相关的网页列表。每个搜索结果包含 URL、标题和页面摘要的 Markdown 格式内容，非常适合构建知识库或信息检索应用。资料来源：README.md:45-60

Scrape（抓取）

Scrape 是 Firecrawl 最核心的功能模块，用于从单个 URL 提取结构化数据。支持多种输出格式，包括 Markdown、HTML、JSON（通过 Schema 提取）、链接列表、截图等。开发者可以配置只提取主内容、设置等待时间、控制输出格式等参数。资料来源：README.md:70-95

Interact（交互）

Interact 模块支持基于抓取结果的浏览器自动化交互。用户可以先使用 Scrape 抓取页面，然后通过 AI 提示词或 JavaScript 代码与页面进行交互，如点击按钮、填写表单、搜索内容等操作。资料来源：README.md:100-120

Agent（智能代理）

Agent 模块是 Firecrawl 的高级功能，允许开发者使用自然语言描述目标，系统自动完成数据采集和整理。例如，开发者可以描述"查找某公司的创始人信息"，Agent 会自动规划搜索路径、抓取相关页面并提取结构化结果。资料来源：apps/python-sdk/README.md:30-35

系统架构

整体架构图

graph TD
    subgraph 客户端层
        Python[Python SDK]
        NodeJS[Node.js SDK]
        Java[Java SDK]
        Ruby[Ruby SDK]
        Go[Go SDK]
        DotNet[.NET SDK]
        Rust[Rust SDK]
        PHP[PHP SDK]
        CLI[Firecrawl CLI]
        DirectAPI[直接 API 调用]
    end

    subgraph API 网关层
        Gateway[API Gateway]
        Auth[身份验证]
        RateLimit[限流控制]
    end

    subgraph 核心服务层
        ScrapeService[Scrape 服务]
        CrawlService[Crawl 服务]
        MapService[Map 服务]
        SearchService[Search 服务]
        AgentService[Agent 服务]
        InteractService[Interact 服务]
    end

    subgraph 数据处理层
        HTMLParser[HTML 解析器]
        MarkdownConverter[Markdown 转换]
        JSONExtractor[JSON Schema 提取]
        ScreenshotEngine[截图引擎]
        GoHTML2MD[Go HTML-to-MD 库]
    end

    subgraph 监控服务
        Monitor[监控服务]
        Notification[通知服务]
    end

    客户端层 --> API 网关层
    API 网关层 --> 核心服务层
    核心服务层 --> 数据处理层
    核心服务层 --> 监控服务

API 端点概览

端点	方法	功能描述	异步支持
`/v2/scrape`	POST	抓取单个 URL 的内容	否
`/v2/crawl`	POST	启动网站爬虫任务	是（轮询）
`/v2/map`	POST	发现网站所有 URL	否
`/v2/search`	POST	互联网全文搜索	否
`/v1/scrape`	POST	旧版抓取接口	否

资料来源：README.md:20-80

多语言 SDK 支持

Firecrawl 提供了丰富的官方 SDK，覆盖主流编程语言生态：

SDK 功能对比

SDK	包名称	安装方式	版本	特殊功能
Python	`firecrawl-py`	`pip install firecrawl-py`	2.x	Agent、异步爬虫
Node.js	`@mendable/firecrawl-js`	`npm install @mendable/firecrawl-js`	最新	Zod Schema 支持
Java	`com.firecrawl:firecrawl-java`	Maven/Gradle	1.1.1	构建器模式
Ruby	`firecrawl-sdk`	`gem install firecrawl-sdk`	1.0	-
Go	`github.com/firecrawl/firecrawl-go-sdk`	`go get`	-	-
.NET	`firecrawl-sdk`	`dotnet add package firecrawl-sdk`	-	HttpClient 可定制
Rust	`firecrawl`	Cargo.toml	2.1.0	异步运行时
PHP	`firecrawl/sdk`	Composer	-	Laravel Facade

资料来源：apps/python-sdk/README.md:1-20 apps/js-sdk/firecrawl/README.md:1-30 apps/java-sdk/README.md:1-20 apps/ruby-sdk/README.md:1-25 apps/dotnet-sdk/README.md:1-20 apps/rust-sdk/README.md:1-30 apps/php-sdk/README.md:1-20

Python SDK 示例

from firecrawl import Firecrawl
from firecrawl.types import ScrapeOptions

firecrawl = Firecrawl(api_key="fc-YOUR_API_KEY")

# 抓取单个页面
doc = firecrawl.scrape("https://firecrawl.dev", formats=["markdown"])
print(doc.markdown)

# 批量爬虫
docs = firecrawl.crawl("https://docs.firecrawl.dev", limit=50)
for doc in docs.data:
    print(doc.metadata.source_url)

# 使用 Agent
result = firecrawl.agent(prompt="查找 Stripe 公司的创始人")
print(result.data)

资料来源：apps/python-sdk/README.md:15-45

Node.js SDK 示例

import Firecrawl from '@mendable/firecrawl-js';
import { z } from 'zod';

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

// 使用 Zod Schema 提取结构化数据
const schema = z.object({
  title: z.string(),
  price: z.number(),
});

const result = await app.extract({
  urls: ['https://example.com/product'],
  prompt: '提取产品名称和价格',
  schema,
});

console.log(result.data);

资料来源：apps/js-sdk/firecrawl/README.md:40-60

高级功能

批量抓取（Batch Scrape）

批量抓取功能允许开发者一次性提交多个 URL 进行抓取，适合需要对多个页面进行数据采集的场景。系统会自动管理任务队列和并发控制。资料来源：README.md:80-95

job = app.batch_scrape([
    "https://firecrawl.dev",
    "https://docs.firecrawl.dev",
    "https://firecrawl.dev/pricing"
], formats=["markdown"])

for doc in job.data:
    print(doc.metadata.source_url)

文件解析（Parse）

Parse 功能支持上传本地文件（HTML、PDF、DOCX 等）并进行解析，无需通过 URL 抓取。该功能适用于处理本地文档或通过其他渠道获取的文件内容。资料来源：apps/python-sdk/README.md:60-80

doc = firecrawl.parse(
    b"<!DOCTYPE html><html><body><h1>Content</h1></body></html>",
    filename="upload.html",
    content_type="text/html",
    options=ParseOptions(formats=["markdown"]),
)

JSON Schema 提取

通过 JSON Schema 定义数据结构，Firecrawl 可以自动从页面中提取符合模式的数据，返回结构化的 JSON 输出。资料来源：apps/java-sdk/README.md:50-75

JsonFormat jsonFmt = JsonFormat.builder()
    .prompt("提取产品名称和价格")
    .schema(Map.of(
        "type", "object",
        "properties", Map.of(
            "name", Map.of("type", "string"),
            "price", Map.of("type", "number")
        )
    ))
    .build();

Document doc = client.scrape("https://example.com/product",
    ScrapeOptions.builder()
        .formats(List.of(jsonFmt))
        .build());

网站地图（Map）

Map 功能快速发现网站上的所有页面 URL，支持基于关键词的智能搜索排序。返回结果包含每个 URL 的标题和描述信息。资料来源：README.md:40-50

result = app.map("https://firecrawl.dev", search="pricing")
# 返回与 "pricing" 相关的 URL 列表

配置选项

ScrapeOptions 参数表

参数	类型	默认值	说明
`formats`	List[str]	["markdown"]	输出格式列表
`only_main_content`	bool	false	仅提取主体内容
`wait_for`	int	0	等待加载时间（毫秒）
`timeout`	int	60000	请求超时（毫秒）
`remove_base64_images`	bool	true	移除 Base64 图片
`include_raw_html`	bool	false	包含原始 HTML
`extractor_options`	dict	None	JSON 提取配置
`actions`	List[dict]	None	自动化操作列表

CrawlOptions 参数表

参数	类型	默认值	说明
`limit`	int	None	最大页面数量
`scrape_options`	ScrapeOptions	None	抓取配置
`poll_interval`	int	2	轮询间隔（秒）
`depth`	int	None	爬虫深度限制
`allow_dangerous`	bool	false	允许危险操作

资料来源：apps/python-sdk/README.md:40-65 apps/rust-sdk/README.md:30-60

集成生态

Firecrawl 与多个主流平台和工具深度集成：

AI 工具集成

集成产品	说明	文档链接
Firecrawl Skill	CLI 工具集成	文档
Firecrawl MCP	Model Context Protocol 服务器	GitHub
DeepSeek V3 Crawler	DeepSeek 模型驱动的爬虫	示例
Gemini 2.5 Extractor	Gemini 模型数据提取	示例

平台集成

平台	说明
Lovable	可在 Lovable 应用中直接使用 Firecrawl
Zapier	通过 Zapier 自动化工作流集成
n8n	支持 n8n 工作流自动化平台

资料来源：README.md:120-140

环境配置

API Key 配置

Firecrawl 支持两种 API Key 配置方式：

环境变量配置（推荐）：设置 FIRECRAWL_API_KEY 环境变量
代码显式传入：在客户端初始化时直接传入 API Key

常用环境变量

变量名	说明	示例
`FIRECRAWL_API_KEY`	API 密钥（必填）	`fc-xxxxxxxxxxxx`
`FIRECRAWL_API_URL`	自托管实例 URL	`http://localhost:3002`
`FIRECRAWL_BACKOFF_FACTOR`	重试退避因子	`0.5`

# Bash/Shell
export FIRECRAWL_API_KEY="fc-your-api-key"
export FIRECRAWL_API_URL="http://localhost:3002"

// .NET
var client = new FirecrawlClient(
    apiKey: "fc-your-api-key",
    apiUrl: "https://your-firecrawl-instance.com",
    httpClient: new HttpClient { Timeout = TimeSpan.FromSeconds(60) }
);

资料来源：apps/dotnet-sdk/README.md:20-45 apps/php-sdk/README.md:25-40

工作流程示例

典型数据采集流程

graph LR
    A[确定目标网站] --> B[使用 Map 发现 URL]
    B --> C[评估 URL 相关性]
    C --> D[配置抓取参数]
    D --> E[执行批量抓取]
    E --> F[解析响应数据]
    F --> G[存储结构化数据]

交互式数据提取流程

graph TD
    A[Scrape 抓取页面] --> B[获取 scrapeId]
    B --> C[使用 Interact 交互]
    C --> D[执行 JS 代码或 AI 提示]
    D --> E[等待操作完成]
    E --> F[获取更新后的页面状态]
    F --> G[提取最终数据]

总结

Firecrawl 是一个功能全面的网页数据采集平台，通过统一 API 和多语言 SDK 为开发者提供了便捷的网页抓取、爬虫、搜索和智能代理能力。其设计理念是简化网页数据获取的复杂性，让开发者能够专注于业务逻辑而非底层实现。无论是构建知识库、训练 AI 模型还是自动化数据采集任务，Firecrawl 都能提供可靠的解决方案。

资料来源：[README.md:20-80]()

系统架构

Firecrawl 是一个现代化的网页抓取和数据提取平台，采用微服务化的 SDK 架构设计。系统由中央 API 服务器、多语言 SDK 客户端、异步任务队列服务以及原生性能优化库组成，旨在为 AI 系统提供搜索、抓取和网页交互的完整解决方案。

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 API 服务器

继续阅读本节完整说明和来源证据。

章节 队列服务

继续阅读本节完整说明和来源证据。

章节 原生性能库

继续阅读本节完整说明和来源证据。

整体架构概览

Firecrawl 采用典型的客户端-服务器架构，API 服务器托管在 api.firecrawl.dev，通过 RESTful API 与多语言 SDK 进行通信。

graph TD
    A[多语言 SDK 客户端] --> B[Firecrawl API 服务器]
    B --> C[队列服务 Queue Service]
    B --> D[抓取引擎 Scraping Engines]
    B --> E[原生库 Native Libraries]
    C --> F[异步任务处理器]
    D --> G[网站内容]
    E --> H[HTML 转 Markdown]

核心组件

API 服务器

API 服务器是整个系统的核心枢纽，基于 Node.js/TypeScript 构建，负责处理所有客户端请求并进行任务调度。

组件	功能	源码位置
路由控制器	处理 API 端点路由	apps/api/src/index.ts
服务初始化	加载和管理各类服务模块	apps/api/src/services/index.ts
测试工具	开发环境验证	apps/api/src/harness.ts

队列服务

队列服务负责管理异步任务的调度和执行，确保长时间运行的任务不会阻塞主请求线程。

// apps/api/src/services/queue-service.ts 核心职责
// - 任务入队和出队管理
// - 任务状态追踪
// - 优先级调度
// - 失败重试机制

队列服务支持异步爬取、批量抓取等长时间运行的操作，客户端可以通过轮询任务 ID 来获取执行结果。

原生性能库

为了优化核心性能，Firecrawl 集成了原生语言库：

库名称	语言	用途
go-html-to-md	Go	HTML 到 Markdown 的高性能转换
Rust SDK	Rust	底层高性能操作

# go-html-to-md 构建命令
cd apps/api/sharedLibs/go-html-to-md
go build -o <OUTPUT> -buildmode=c-shared html-to-markdown.go

输出文件根据操作系统不同：

SDK 多语言架构

Firecrawl 提供统一的 SDK 体验，覆盖主流编程语言：

graph LR
    A[统一 API 接口] --> B[Python SDK]
    A --> C[Node.js SDK]
    A --> D[Ruby SDK]
    A --> E[Java SDK]
    A --> F[.NET SDK]
    A --> G[Rust SDK]
    A --> H[PHP SDK]

SDK	包名/依赖	文档位置
Python	`firecrawl-py`	apps/python-sdk/README.md
Node.js	`@mendable/firecrawl-js`	apps/js-sdk/README.md
Ruby	`firecrawl-sdk`	apps/ruby-sdk/README.md
Java	`com.firecrawl:firecrawl-java`	apps/java-sdk/README.md
.NET	`firecrawl-sdk`	apps/dotnet-sdk/README.md
Rust	`firecrawl`	apps/rust-sdk/README.md
PHP	`firecrawl-sdk`	apps/php-sdk/README.md

功能模块架构

核心功能

graph TD
    subgraph Firecrawl 核心功能
        S[Search 搜索] --> Scr[Scrape 抓取]
        Scr --> Cr[Crawl 爬取]
        Cr --> M[Map 站点地图]
        M --> Ex[Extract 提取]
        Ex --> I[Interact 交互]
        I --> Ag[Agent 智能代理]
    end

抓取引擎

系统支持多种专业化的抓取引擎，针对不同数据源进行优化：

引擎	用途	源码示例
Wikipedia 引擎	维基百科结构化数据	apps/api/src/scraper/scrapeURL/engines/wikipedia/index.ts
通用引擎	标准网页抓取	默认引擎

数据提取服务

Firecrawl 提供基于 AI 的数据提取能力：

// apps/api/src/lib/extract/fire-0/extraction-service-f0.ts
// - Schema 验证
// - 单实体/多实体提取
// - 结果混合与去重

监控与通知系统

系统包含完整的监控通知机制：

// apps/api/src/services/notification/monitoring_email.ts
// - 变更检测摘要邮件
// - 新增页面通知
// - 移除页面告警
// - 错误统计

监控邮件功能支持定期发送网站变更报告，包括新增、移除、变更的页面数量统计。

认证与配置

API 密钥管理

Firecrawl 支持多种 API 密钥配置方式：

配置方式	优先级	示例
构造函数参数	最高	`Client("fc-your-api-key")`
环境变量	次高	`FIRECRAWL_API_KEY`
配置文件	最低	各 SDK 特定配置

客户端初始化示例

# Python SDK
from firecrawl import Firecrawl
app = Firecrawl(api_key="fc-YOUR_API_KEY")

// Java SDK
FirecrawlClient client = FirecrawlClient.builder()
    .apiKey("fc-your-api-key")
    .build();

// Rust SDK
use firecrawl::{Client, ScrapeOptions, Format, CrawlOptions};
let client = Client::new("fc-YOUR_API_KEY")?;

数据流架构

sequenceDiagram
    participant C as 客户端 SDK
    participant A as API 服务器
    participant Q as 队列服务
    participant E as 抓取引擎
    participant N as 原生库
    
    C->>A: 发起抓取请求
    A->>Q: 入队异步任务
    A-->>C: 返回任务 ID
    Q->>E: 调度抓取任务
    E->>N: HTML 内容处理
    N-->>E: Markdown 输出
    E-->>Q: 任务完成
    C->>A: 轮询任务状态
    A-->>C: 返回抓取结果

安全与数据处理

HTML 转义处理

系统对外部数据实施严格的 HTML 转义，防止 XSS 等安全问题：

// apps/api/src/scraper/scrapeURL/engines/wikipedia/index.ts
function escapeHtml(str: string): string {
  return str
    .replace(/&/g, "&amp;")
    .replace(/</g, "&lt;")
    .replace(/>/g, "&gt;")
    .replace(/"/g, "&quot;");
}

内容过滤

系统内置内容安全过滤机制，包括：

仅提取主体内容选项
可配置的等待时间
格式选择（Markdown、HTML、JSON 等）

扩展与集成

第三方集成

平台	集成方式	说明
Mendable	Firecrawl Skill	AI 技能集成
Lovalbe	内置支持	无代码平台集成
Zapier	App Integration	自动化工作流
n8n	Workflow Nodes	自托管自动化
Gemini	示例项目	AI 模型集成
DeepSeek	示例项目	大语言模型爬虫

品牌标识处理

系统包含品牌识别模块，能够从抓取页面中提取品牌名称和 Logo 信息。

技术栈总结

层级	技术选型
API 服务器	Node.js / TypeScript / Express
原生性能库	Go (HTML→Markdown), Rust
队列系统	基于 TypeScript 的异步队列
SDK 生态	Python, Node.js, Ruby, Java, .NET, Rust, PHP
部署方式	云原生，支持自托管

该架构设计遵循松耦合原则，各组件通过明确定义的接口进行通信，便于独立扩展和维护。

来源：https://github.com/firecrawl/firecrawl / 项目说明书

API路由与版本控制

由于指定的路由源文件 (apps/api/src/routes/v0.ts, apps/api/src/routes/v1.ts, apps/api/src/routes/v2.ts, apps/api/src/routes/admin.ts, apps/api/openapi.json) 未出现在当前检索结果中，我无法提供详细的源码级分析。

章节 相关页面

继续阅读本节完整说明和来源证据。

现有文档中的 API 版本信息

根据主 README.md，以下是 v2 API 端点：

API 功能	端点	方法	资料来源
搜索	`/v2/search`	POST	README.md
抓取	`/v2/scrape`	POST	README.md
映射网站	`/v2/map`	POST	README.md
批量抓取	`/v2/batch`	POST	README.md

SDK 支持情况

SDK 语言	仓库路径	支持版本
Python	apps/python-sdk	v1, v2
Node.js	apps/js-sdk	v1, v2
Rust	apps/rust-sdk	v1, v2
Go	apps/go-sdk	v1, v2
Ruby	apps/ruby-sdk	v1, v2
Java	apps/java-sdk	v1, v2
.NET	apps/dot-net-sdk	v1, v2
PHP	apps/php-sdk	v1, v2

建议

要生成完整的 API 路由与版本控制 Wiki 页面，需要检索以下文件：

请提供这些文件的实际内容以继续生成 Wiki 页面。

来源：https://github.com/firecrawl/firecrawl / 项目说明书

抓取引擎

抓取引擎（Scrape Engine）是 Firecrawl 系统中负责实际执行网页内容抓取的核心组件模块。它位于 apps/api/src/scraper/scrapeURL/engines/ 目录下，采用多引擎架构设计，根据不同的内容类型和抓取需求，智能选择最适合的底层抓取实现。

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 整体架构图

继续阅读本节完整说明和来源证据。

章节 引擎类型与职责

继续阅读本节完整说明和来源证据。

章节 Fetch 引擎

继续阅读本节完整说明和来源证据。

概述

抓取引擎（Scrape Engine）是 Firecrawl 系统中负责实际执行网页内容抓取的核心组件模块。它位于 apps/api/src/scraper/scrapeURL/engines/ 目录下，采用多引擎架构设计，根据不同的内容类型和抓取需求，智能选择最适合的底层抓取实现。

Firecrawl 的抓取引擎设计遵循策略模式（Strategy Pattern），每个引擎实现相同的接口契约，但采用不同的技术栈来处理特定类型的内容。这种设计使得系统能够灵活应对静态网页、动态渲染页面、PDF 文档、Office 文档等多种内容源的抓取需求。

抓取引擎与上层的 scrapeURL/index.ts 主模块协同工作，主模块负责接收抓取请求、解析配置参数、路由到合适的引擎，并最终汇总各引擎的输出结果。资料来源：apps/api/src/scraper/scrapeURL/index.ts

架构设计

整体架构图

graph TD
    A[scrapeURL 主模块] --> B[引擎选择器]
    B --> C[Fetch 引擎]
    B --> D[Fire-Engine 引擎]
    B --> E[Playwright 引擎]
    B --> F[PDF 引擎]
    B --> G[Document 引擎]
    
    C --> H[HTTP 请求处理]
    D --> I[浏览器自动化]
    E --> J[Chromium 实例]
    F --> K[PDF 解析库]
    G --> L[文档解析器]
    
    H --> M[HTML 响应]
    I --> N[渲染后 DOM]
    J --> N
    K --> O[PDF 文本/元数据]
    L --> P[文档内容]

引擎类型与职责

引擎名称	技术实现	适用场景	内容类型
Fetch	Node.js 原生 HTTP 请求	静态页面、API 响应	HTML、JSON
Fire-Engine	浏览器自动化框架	动态渲染页面	JavaScript 渲染后的 DOM
Playwright	Chromium 实例控制	复杂交互页面	完整网页快照
PDF	PDF 解析库	PDF 文档	PDF 文本、元数据
Document	文档解析器	Office 文档	DOCX、XLSX、PPTX

核心引擎详解

Fetch 引擎

Fetch 引擎是抓取引擎家族中最轻量的实现，位于 apps/api/src/scraper/scrapeURL/engines/fetch/index.ts。它直接使用 Node.js 原生的 HTTP/HTTPS 模块发起请求，适用于静态网页和 API 接口的数据抓取。

Fetch 引擎的主要特点包括：

零外部依赖：不依赖 Puppeteer、Playwright 等重型库
高性能：异步 I/O 操作，支持高并发请求
可配置性：支持自定义请求头、超时设置、代理配置
Cookie 处理：内置 Cookie 管理和会话保持

该引擎特别适合抓取不依赖 JavaScript 渲染的静态内容，如博客文章、新闻页面、产品列表页等。对于需要登录认证的网站，Fetch 引擎支持通过 Cookie 或 Bearer Token 进行身份验证。

Fire-Engine 引擎

Fire-Engine 引擎是 Firecrawl 自研的浏览器自动化引擎，位于 apps/api/src/scraper/scrapeURL/engines/fire-engine/index.ts。它提供了介于轻量级 Fetch 和完整浏览器自动化之间的抓取能力。

Fire-Engine 的核心优势在于：

轻量级浏览器：相比完整的 Chromium 实例，占用资源更少
JavaScript 渲染：支持执行页面内的 JavaScript 代码
DOM 操作：提供点击、滚动、输入等交互能力
截图功能：支持页面截图和元素截图

该引擎适用于需要部分 JavaScript 渲染但不需要完整浏览器环境的场景，例如单页应用（SPA）的初始内容抓取、无限滚动列表的加载等。

Playwright 引擎

Playwright 引擎是 Firecrawl 中最强大的抓取引擎，位于 apps/api/src/scraper/scrapeURL/engines/playwright/index.ts。它基于 Microsoft 的 Playwright 框架，提供完整的浏览器自动化能力。

Playwright 引擎的核心特性：

多浏览器支持：Chromium、Firefox、WebKit
完整渲染：执行所有 JavaScript，包括框架级别的代码
网络拦截：支持请求/响应拦截，可修改网络流量
元素定位：支持 CSS 选择器、XPath、文本定位
等待策略：智能等待元素出现、网络空闲等条件

对于需要模拟用户行为（如登录、表单填写、点击按钮）的复杂抓取场景，Playwright 引擎是最佳选择。它还支持无头模式（headless）和有头模式（headed），可根据调试或生产环境灵活切换。

PDF 引擎

PDF 引擎专门用于处理 PDF 文档的抓取和解析，位于 apps/api/src/scraper/scrapeURL/engines/pdf/index.ts。

PDF 引擎支持的功能：

直接下载：从 URL 下载 PDF 文件
文本提取：从 PDF 中提取可搜索的文本内容
元数据读取：获取 PDF 的标题、作者、创建日期等元数据
页面拆分：支持按页面维度提取内容
加密处理：处理有密码保护的 PDF 文件

该引擎在处理学术论文、报告、合同等 PDF 格式内容时表现出色。结合 Firecrawl 的 Map 功能，可以自动发现网站上的 PDF 资源并进行批量抓取。

Document 引擎

Document 引擎用于处理 Office 格式的文档，位于 apps/api/src/scraper/scrapeURL/engines/document/index.ts。它与后端原生模块 apps/api/native/src/document/providers/factory.rs 协同工作。

Document 引擎支持的文档格式：

格式	MIME 类型	提取内容
DOCX	application/vnd.openxmlformats-officedocument.wordprocessingml.document	文本、段落、表格、列表
XLSX	application/vnd.openxmlformats-officedocument.spreadsheetml.sheet	表格数据、公式
PPTX	application/vnd.openxmlformats-officedocument.presentationml.presentation	幻灯片文本、备注

Document 引擎的核心优势在于其原生实现方式。通过 Rust 编写的底层解析器（位于 apps/api/native/src/document/providers/factory.rs），能够高效处理大文件和复杂结构的 Office 文档，同时保证内存使用的安全性。

原生文档工厂

apps/api/native/src/document/providers/factory.rs 是 Rust 原生模块中的核心组件，负责创建和管理各种文档格式的解析器实例。

graph LR
    A[Document Request] --> B[Factory]
    B --> C{DocType Detection}
    C -->|DOCX| D[DocxParser]
    C -->|XLSX| E[XlsxParser]
    C -->|PDF| F[PdfParser]
    C -->|Unknown| G[Error Handler]
    
    D --> H[Structured Output]
    E --> H
    F --> H

工厂模式的应用确保了：

类型安全：编译时保证所有支持的文档类型都被处理
可扩展性：新增文档格式只需实现对应的解析 trait
性能优化：根据文档类型预分配内存，减少运行时开销

工作流程

抓取请求处理流程

sequenceDiagram
    participant Client as 客户端
    participant Main as scrapeURL 主模块
    participant Router as 引擎路由器
    participant Engine as 选中的抓取引擎
    participant Output as 结果处理器
    
    Client->>Main: 发送抓取请求 (URL, Options)
    Main->>Main: 验证 URL 和参数
    Main->>Router: 请求引擎选择
    Router->>Router: Content-Type 检测
    Router->>Engine: 路由到合适引擎
    Engine->>Engine: 执行抓取逻辑
    Engine-->>Output: 返回原始内容
    Output->>Output: 格式化与清洗
    Output-->>Main: 结构化结果
    Main-->>Client: 返回 Document 对象

引擎选择策略

抓取引擎根据以下因素自动选择最合适的引擎：

URL 扩展名检测：优先根据 URL 末尾的文件扩展名判断内容类型
Content-Type 响应头：HTTP 响应头中的 Content-Type 字段
配置优先级：用户通过 ScrapeOptions 明确指定的引擎类型
降级策略：主引擎失败时自动降级到备选引擎

配置选项

抓取引擎通过 ScrapeOptions 对象接收配置参数：

参数名	类型	默认值	说明
formats	string[]	["markdown"]	输出格式列表
onlyMainContent	boolean	false	仅提取主体内容
waitFor	number	0	等待渲染的毫秒数
timeout	number	30000	请求超时（毫秒）
engine	string	"auto"	强制指定引擎类型
actions	Action[]	[]	浏览器自动化动作序列

SDK 集成

各语言 SDK 通过统一的接口调用抓取引擎，以 Python SDK 为例：

from firecrawl import Firecrawl
from firecrawl.v2.types import ScrapeOptions

firecrawl = Firecrawl(api_key="fc-YOUR_API_KEY")

# 基础抓取（自动选择引擎）
doc = firecrawl.scrape('https://example.com', formats=['markdown'])

# 指定引擎抓取
doc = firecrawl.scrape(
    'https://example.com',
    formats=['markdown', 'html'],
    options=ScrapeOptions(
        engine='playwright',
        wait_for=3000
    )
)

错误处理机制

抓取引擎实现了多层次的错误处理策略：

错误类型	处理策略	降级引擎
网络超时	重试 3 次，指数退避	Playwright
渲染失败	降级到 Fetch 引擎	Fetch
解析错误	返回原始内容，标记警告	-
资源不存在	返回 404 错误	-
认证失败	返回 401 错误	-

性能优化

并发控制

抓取引擎内置了并发控制机制：

全局并发限制：防止对目标服务器造成过大压力
域名级限速：基于域名的请求速率控制
连接池复用：减少 TCP 连接建立开销

缓存策略

304 响应处理：正确处理 HTTP 条件请求
ETag/Last-Modified：支持服务端缓存验证
本地缓存：对重复请求返回缓存结果

安全考量

抓取引擎在设计时充分考虑了安全因素：

请求来源伪装：模拟真实浏览器请求头
反爬虫规避：内置常用反爬虫策略应对
敏感信息过滤：自动过滤密码、API Key 等敏感数据
沙箱执行：浏览器引擎在隔离环境中运行

扩展开发指南

如需添加新的抓取引擎，可按以下步骤扩展：

在 engines/ 目录下创建新的引擎文件夹
实现统一的引擎接口 BaseEngine
在引擎路由器中注册新引擎
添加对应的配置选项处理逻辑
编写单元测试和集成测试

搜索与爬取功能

Firecrawl 的搜索与爬取功能是平台的核心能力，为 AI 系统提供网页搜索、抓取和交互能力。搜索功能允许用户在整个网络中查找信息，而爬取功能则支持对特定网站的深度遍历和数据提取。资料来源：README.md

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 核心模块关系

继续阅读本节完整说明和来源证据。

章节 搜索子系统架构

继续阅读本节完整说明和来源证据。

章节 功能特性

继续阅读本节完整说明和来源证据。

概述

架构设计

核心模块关系

graph TD
    A[API 入口] --> B[搜索模块 search/]
    A --> C[爬取模块 scraper/]
    B --> D[Fire Engine]
    B --> E[SearXNG 集成]
    C --> F[WebScraper]
    C --> G[Crawler]
    F --> H[Sitemap 解析]
    G --> H
    D --> I[搜索结果]
    H --> J[爬取结果]

搜索子系统架构

搜索功能通过多层抽象实现：

组件	文件路径	职责
搜索入口	`apps/api/src/search/index.ts`	处理 API 请求分发和参数验证
执行引擎	`apps/api/src/search/execute.ts`	协调搜索执行流程
Fire Engine	`apps/api/src/search/fireEngine.ts`	自定义搜索引擎实现
SearXNG 集成	`apps/api/src/search/searxng.ts`	开源搜索引擎后端适配

搜索功能详解

功能特性

搜索功能支持以下核心能力：

网络搜索：在互联网上查找相关信息
结果排序：按相关性对结果进行排序
数量限制：支持限制返回结果数量
来源控制：可指定搜索结果来源资料来源：README.md:45-50

API 端点

POST https://api.firecrawl.dev/v2/search

请求头：

参数	说明	必填
Authorization	Bearer token 认证	是
Content-Type	application/json	是

请求体：

字段	类型	说明
query	string	搜索查询关键词
limit	number	返回结果数量限制

响应格式

{
  "data": [
    {
      "url": "https://firecrawl.dev",
      "title": "Firecrawl",
      "markdown": "Turn websites into..."
    }
  ]
}

爬取功能详解

爬取类型

Firecrawl 支持两种主要的网站爬取方式：

爬取类型	说明	适用场景
sitemap 爬取	通过解析网站的 sitemap.xml 发现页面	静态网站、结构化站点
智能爬取	通过模拟浏览器行为遍历页面	JavaScript 渲染页面、动态内容

Sitemap 解析模块

Sitemap 解析是爬取功能的基础组件：

文件	职责
`apps/api/src/scraper/WebScraper/sitemap.ts`	WebScraper 场景下的 sitemap 解析
`apps/api/src/scraper/crawler/sitemap.ts`	独立爬虫场景下的 sitemap 解析

核心爬取流程

graph TD
    A[开始爬取] --> B{选择爬取模式}
    B -->|Sitemap| C[解析 sitemap.xml]
    B -->|智能爬取| D[启动浏览器实例]
    C --> E[提取 URL 列表]
    D --> F[遍历页面链接]
    E --> G[过滤有效链接]
    F --> G
    G --> H[抓取页面内容]
    H --> I[提取结构化数据]
    I --> J[返回结果]

爬取配置参数

from firecrawl import Firecrawl

app = Firecrawl(api_key="fc-YOUR_API_KEY")

crawl_status = firecrawl.crawl(
    'https://firecrawl.dev', 
    limit=100, 
    scrape_options=ScrapeOptions(formats=['markdown', 'html']),
    poll_interval=30
)

参数	类型	说明
limit	number	最大抓取页面数量
scrape_options	ScrapeOptions	抓取选项配置
poll_interval	number	异步轮询间隔（秒）
exclude_paths	string[]	需要排除的路径

SDK 实现

Python SDK

from firecrawl import Firecrawl

app = Firecrawl(api_key="fc-YOUR_API_KEY")

# 搜索
results = app.search("best AI data tools 2024", limit=10)

# 爬取网站
docs = app.crawl("https://docs.firecrawl.dev", limit=50)
for doc in docs.data:
    print(doc.metadata.source_url, doc.markdown[:100])

Node.js SDK

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

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

// 搜索
const results = await app.search('best AI data tools 2024', { limit: 10 });

// 爬取
const docs = await app.crawl('https://docs.firecrawl.dev', { 
    limit: 50,
    scrapeOptions: { formats: ['markdown', 'html'] }
});

Java SDK

FirecrawlClient client = FirecrawlClient.builder()
    .apiKey("fc-your-api-key")
    .build();

// 爬取
CrawlResponse response = client.crawl("https://example.com", 
    CrawlOptions.builder()
        .limit(50)
        .build());

for (Page page : response.getData()) {
    System.out.println(page.getMetadata().get("sourceURL"));
}

数据模型

搜索结果模型

字段	类型	说明
url	string	页面 URL
title	string	页面标题
description	string	页面描述
markdown	string	页面内容（Markdown 格式）

爬取结果模型

字段	类型	说明
data	Page[]	抓取的页面列表
status	string	爬取状态
credits_used	number	消耗的 credits

Page 模型

字段	类型	说明
metadata	Record	页面元数据
markdown	string	Markdown 格式内容
html	string	原始 HTML
screenshot	string	页面截图（Base64）

配置选项

ScrapeOptions 配置

选项	类型	说明
formats	string[]	输出格式：markdown、html、json
only_main_content	boolean	仅提取主体内容
wait_for	number	等待渲染时间（毫秒）
location	LocationConfig	地理位置配置

CrawlOptions 配置

选项	类型	默认值	说明
limit	number	100	最大页面数
exclude_paths	string[]	[]	排除路径
include_paths	string[]	[]	包含路径
max_depth	number	10	最大递归深度

异步操作处理

异步爬取流程

sequenceDiagram
    participant Client
    participant API
    participant Crawler
    participant Storage
    
    Client->>API: 发起爬取请求
    API->>Crawler: 启动爬取任务
    API-->>Client: 返回 Job ID
    loop 轮询状态
        Client->>API: 查询爬取状态
        API->>Crawler: 获取进度
        Crawler-->>API: 返回状态
        API-->>Client: 返回状态
    end
    Crawler->>Storage: 保存结果
    Client->>API: 获取完整结果
    API->>Storage: 读取结果
    Storage-->>API: 返回数据
    API-->>Client: 返回完整数据

异步爬取示例

// Rust SDK 异步爬取
let crawl_id = app.crawl_url_async("https://mendable.ai", None).await?.id;

// 检查爬取状态
let status = app.check_crawl_status(crawl_id).await?;

if status.status == CrawlStatusTypes::Completed {
    println!("爬取完成: {:#?}", status.data);
}

错误处理

错误类型	说明	处理建议
TIMEOUT	请求超时	增加超时时间或减少页面数量
RATE_LIMIT	请求频率超限	使用轮询间隔或降低请求频率
INVALID_URL	URL 格式错误	检查 URL 格式是否正确
ACCESS_DENIED	访问被拒绝	网站可能禁止爬取

最佳实践

搜索优化

精确查询：使用具体关键词提高搜索准确性
限制数量：设置合理的 limit 值避免资源浪费
结果缓存：考虑对频繁查询的结果进行缓存

爬取优化

路径过滤：使用 exclude_paths 排除无关页面
深度控制：合理设置 max_depth 避免过度爬取
格式选择：根据需求选择合适的输出格式
轮询间隔：使用合适的 poll_interval 减少 API 调用

数据提取系统

数据提取系统（Extract System）是Firecrawl平台的核心组件之一，负责从网页内容中提取结构化数据。该系统支持JSON Schema定义的数据提取，通过大语言模型（LLM）将非结构化的网页内容转换为符合预定义模式的高质量结构化数据。

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 核心能力

继续阅读本节完整说明和来源证据。

章节 核心组件

继续阅读本节完整说明和来源证据。

章节 整体处理流程

继续阅读本节完整说明和来源证据。

系统概述

核心能力

能力	描述
单URL提取	从单个网页提取结构化数据
批量提取	一次处理多个URL，提高效率
Schema验证	使用JSON Schema验证输出数据
智能提示词	自动分析和优化提取提示词
重排序	对提取结果进行相关性排序

资料来源：apps/api/src/lib/extract/extraction-service.ts

系统架构

graph TD
    A[API请求] --> B[提取队列 extract-queue]
    B --> C[提取Worker extract-worker]
    C --> D[提取服务 ExtractionService]
    D --> E[构建文档 build-document]
    D --> F[构建提示 build-prompts]
    E --> G[完成处理 completions]
    F --> G
    G --> H[singleAnswer]
    G --> I[batchExtract]
    G --> J[analyzeSchemaAndPrompt]
    H --> K[重排序 reranker]
    I --> K
    J --> F
    K --> L[返回结构化数据]

核心组件

组件	文件路径	职责
提取服务	extraction-service.ts	核心提取逻辑编排
文档构建	build-document.ts	构建提取结果文档
提示词构建	build-prompts.ts	生成LLM提示词
单答案处理	singleAnswer.ts	处理单个URL提取
批量提取	batchExtract.ts	处理多URL批量提取
Schema分析	analyzeSchemaAndPrompt.ts	分析schema并优化提示词
重排序器	reranker.ts	结果相关性排序

资料来源：apps/api/src/lib/extract/extraction-service.ts

工作流程

整体处理流程

graph LR
    A1[接收请求] --> B1[入队到extract-queue]
    B1 --> C1[Worker获取任务]
    C1 --> D1[调用ExtractionService]
    D1 --> E1[构建提示词]
    E1 --> F1[LLM调用]
    F1 --> G1[Schema验证]
    G1 --> H1[结果重排序]
    H1 --> I1[返回结果]

批量提取流程

当处理多个URL时，系统采用以下流程：

URL分批处理：将URL列表分成小批次
并发LLM调用：对每个批次并行调用LLM
结果聚合：合并所有批次的提取结果
重排序：根据相关性对最终结果排序

资料来源：apps/api/src/lib/extract/completions/batchExtract.ts

核心模块详解

提取服务 (ExtractionService)

提取服务是整个数据提取系统的中枢，协调各组件完成数据提取任务。

主要职责：

管理提取任务的生命周期
协调文档构建和提示词构建
处理LLM调用和结果验证
支持单条和批量提取模式

资料来源：apps/api/src/lib/extract/extraction-service.ts

文档构建 (build-document)

文档构建模块负责将提取的原始数据转换为标准化的文档格式。

功能特点：

规范化提取结果结构
添加元数据信息
处理多种输出格式

资料来源：apps/api/src/lib/extract/build-document.ts

提示词构建 (build-prompts)

提示词构建模块生成用于LLM的结构化提示词，包含必要的上下文和提取指令。

构建要素：

系统指令（System Prompt）
用户提示（User Prompt）
Schema定义嵌入
示例数据（可选）

自适应优化：该模块与analyzeSchemaAndPrompt协同工作，可根据Schema自动调整提示词以提高提取准确性。

资料来源：apps/api/src/lib/extract/build-prompts.ts

完成处理模块 (completions)

#### 单答案处理 (singleAnswer)

处理单个URL的提取请求，返回完整的结构化数据。

处理流程：

graph TD
    A[输入URL和Schema] --> B[构建提示词]
    B --> C[调用LLM]
    C --> D[解析响应]
    D --> E[Schema验证]
    E --> F[返回结果]

资料来源：apps/api/src/lib/extract/completions/singleAnswer.ts

#### 批量提取 (batchExtract)

支持同时处理多个URL的提取任务，适用于大规模数据采集场景。

批处理策略：

动态批次大小调整
并发请求控制
错误重试机制
部分失败容忍

资料来源：apps/api/src/lib/extract/completions/batchExtract.ts

#### Schema分析 (analyzeSchemaAndPrompt)

分析输入的JSON Schema，评估其复杂度并提供优化建议。

分析维度：

维度	描述
字段数量	Schema包含的属性数量
嵌套深度	对象嵌套的层级
数组复杂度	数组类型字段的复杂性
必需字段	必填属性的比例

资料来源：apps/api/src/lib/extract/completions/analyzeSchemaAndPrompt.ts

重排序器 (reranker)

对提取结果进行相关性评分和排序，确保最相关的结果排在前面。

排序依据：

内容相关性评分
字段完整性
数据质量指标

资料来源：apps/api/src/lib/extract/reranker.ts

队列与Worker机制

提取队列 (extract-queue)

提取队列负责管理待处理的提取任务，支持任务的入队、优先级调度和状态追踪。

队列特性：

异步任务处理
可配置并发数
任务状态监控
失败重试机制

资料来源：apps/api/src/services/extract-queue.ts

提取Worker (extract-worker)

Worker进程从队列中获取任务并执行实际的提取操作。

工作流程：

graph TD
    A[启动Worker] --> B[连接队列]
    B --> C[等待任务]
    C --> D{有新任务?}
    D -->|是| E[获取任务]
    E --> F[执行提取]
    F --> G[更新状态]
    G --> H[任务完成]
    H --> C
    D -->|否| C

错误处理：

自动重试机制
死信队列处理
详细的错误日志

资料来源：apps/api/src/services/extract-worker.ts

API使用

基本提取示例

from firecrawl import Firecrawl

app = Firecrawl(api_key="fc-YOUR_API_KEY")

result = app.extract(
    urls=["https://example.com/product/1"],
    prompt="提取产品名称、价格和描述",
    schema={
        "type": "object",
        "properties": {
            "name": {"type": "string"},
            "price": {"type": "number"},
            "description": {"type": "string"}
        }
    }
)

批量提取示例

result = app.extract(
    urls=[
        "https://example.com/products/1",
        "https://example.com/products/2",
        "https://example.com/products/3"
    ],
    prompt="提取所有产品的基本信息",
    schema={...}
)

配置参数

提取选项

参数	类型	默认值	描述
timeout	number	60000	单次请求超时时间（毫秒）
maxRetries	number	3	最大重试次数
batchSize	number	10	批量处理大小
temperature	number	0.0	LLM温度参数

Schema配置

属性	必需	描述
type	是	JSON类型定义
properties	是	属性映射
required	否	必填字段列表
additionalProperties	否	允许额外字段

最佳实践

1. Schema设计

使用清晰的字段命名
合理设置必填字段
避免过深的嵌套结构
提供明确的类型定义

2. 性能优化

批量提取时控制并发数
合理设置超时时间
使用适当的批次大小
启用结果缓存（如适用）

3. 错误处理

实现重试机制处理临时故障
验证Schema格式确保有效性
检查LLM响应格式的正确性
记录详细的错误信息便于调试

监控与Webhook

Firecrawl 的监控（Monitoring）与Webhook系统为用户提供了持续追踪网站变化和接收实时事件通知的能力。监控服务通过定期检查网页内容，自动检测新增、移除、修改的页面以及抓取错误，并通过邮件或Webhook渠道向用户推送变更摘要。该系统由多个子模块组成，包括调度器（Scheduler）、执行器（Runner）、存储层（Store）、差异检测（Diff）、W...

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 整体流程

继续阅读本节完整说明和来源证据。

章节 调度器（Scheduler）

继续阅读本节完整说明和来源证据。

章节 执行器（Runner）

继续阅读本节完整说明和来源证据。

概述

监控模块架构

整体流程

graph TD
    A[调度器 Scheduler] --> B[执行器 Runner]
    B --> C[存储层 Store]
    C --> D[差异检测 Diff]
    D --> E[变更汇总]
    E --> F[通知发送]
    F --> G[邮件通知]
    F --> H[Webhook投递]
    
    B --> I[抓取目标网页]
    I --> J[当前快照]
    C --> K[历史快照]
    D --> J
    D --> K

调度器（Scheduler）

调度器负责管理监控任务的定时触发。系统会根据用户配置的检查间隔自动执行监控检查，确保在设定的时间周期内持续追踪目标网站的变化。调度器需要处理并发调度、避免重复执行、以及处理任务超时等场景。资料来源：apps/api/src/services/monitoring/scheduler.ts

执行器（Runner）

执行器是监控任务的核心执行单元，负责实际执行网页抓取和内容采集。当调度器触发检查任务时，执行器会启动浏览器实例或发送抓取请求，获取目标页面的当前内容。执行器还需要处理抓取过程中的异常情况，如网络超时、页面加载失败、反爬虫机制等，并将错误信息记录到监控结果中。资料来源：apps/api/src/services/monitoring/runner.ts

存储层（Store）

存储层负责持久化管理监控相关的所有数据，包括监控配置、快照历史、检查记录和变更汇总。Store模块提供了数据的读写接口，确保即使在服务重启后也能恢复监控状态。存储的数据模型通常包含以下核心实体：

实体名称	描述	主要字段
Monitor	监控配置	ID、URL、轮询间隔、通知设置、API密钥
MonitorCheck	单次检查记录	ID、监控ID、执行时间、状态、变更统计
PageSnapshot	页面快照	ID、检查ID、页面URL、内容哈希、原始内容
MonitoringEmailPage	变更页面详情	URL、标题、变更类型

资料来源：apps/api/src/services/monitoring/store.ts

差异检测（Diff）

差异检测模块负责对比当前快照与历史快照，识别页面内容的实际变化。该模块采用内容哈希比对和结构化解析相结合的方式，能够区分真正的内容变更与动态元素（如时间戳、广告）的随机变化。Diff模块的输出包括变更类型（新增/移除/修改）、变更位置、以及变更的详细摘要，便于用户快速理解网站发生的变化。资料来源：apps/api/src/services/monitoring/diff.ts

变更统计模型

监控系统的变更统计采用四维计数模型，全面覆盖网站变化的各个方面：

统计类型	字段名	描述
新增页面	`new_count`	在本次检查中新发现的页面
移除页面	`removed_count`	在本次检查中消失的页面
内容变更	`changed_count`	内容发生变化的现有页面
抓取错误	`error_count`	抓取失败的页面数量

当所有统计值均为零时，系统会跳过邮件通知发送，以减少不必要的通知骚扰。资料来源：apps/api/src/services/notification/monitoring_email.ts

Webhook系统架构

Webhook事件类型

Firecrawl的Webhook系统支持多种事件类型，覆盖异步任务的完整生命周期：

事件类型	触发时机	用途
`started`	任务开始执行时	通知任务已启动
`action`	中间操作发生时	报告任务进度或关键步骤
`completed`	任务成功完成时	传递成功结果数据
`failed`	任务执行失败时	返回错误信息和原因
`cancelled`	任务被取消时	通知任务终止状态

资料来源：apps/api/src/controllers/v2/types.ts

Webhook投递流程

graph LR
    A[事件触发] --> B[Webhook队列]
    B --> C{重试次数检查}
    C -->|未超过限制| D[投递请求]
    D --> E{HTTP响应}
    E -->|2xx成功| F[完成]
    E -->|失败| G[指数退避]
    G --> B
    C -->|超过限制| H[标记失败]

投递服务（Delivery）

Webhook投递服务负责将事件负载发送到用户配置的端点。投递服务需要处理HTTPS连接、TLS证书验证、请求签名（用于安全验证）等技术细节。投递服务支持自定义请求头、请求体格式配置，以及不同类型事件的差异化负载结构。资料来源：apps/api/src/services/webhook/delivery.ts

队列管理（Queue）

Webhook队列提供了可靠投递的保障机制。当投递失败时（如网络错误或目标服务器返回非2xx状态码），队列系统会执行指数退避重试策略，在预设的最大重试次数内持续尝试投递。队列还负责管理不同优先级的事件，确保高优先级事件优先处理。资料来源：apps/api/src/services/webhook/queue.ts

邮件通知系统

通知内容结构

邮件通知采用HTML模板格式，包含以下核心信息：

变更汇总：新增页面数、移除页面数、错误页面数、总检查页面数
变更详情列表：列出发生变化的页面URL和标题
检查标识：用于追踪本次检查的检查ID
资源消耗：本次检查使用的积分数量

邮件内容会对特殊字符进行HTML转义处理，防止XSS攻击。资料来源：apps/api/src/services/notification/monitoring_email.ts

发送条件

邮件通知仅在以下条件同时满足时发送：

监控配置中已启用邮件通知（notification.email.enabled === true）
本次检查检测到至少一个变更（任意统计值大于0）

if (
  params.check.changed_count +
    params.check.new_count +
    params.check.removed_count +
    params.check.error_count <= 0
) {
  // 跳过无变更的邮件通知
  return { attempted: false, success: true, recipients: [] };
}

资料来源：apps/api/src/services/notification/monitoring_email.ts

A/B测试对比功能

除了基础的变更检测，Firecrawl还提供了A/B测试对比功能，允许用户对比两个不同版本或不同来源的抓取结果。该功能支持并行执行两个抓取任务，并对结果进行差异分析，适用于SEO对比、竞品分析、版本验证等场景。资料来源：apps/api/src/services/ab-test-comparison.ts

配置选项

监控配置参数

参数名	类型	必填	描述
url	string	是	要监控的目标URL
pollInterval	number	否	轮询间隔（秒），默认根据订阅计划确定
notification.email.enabled	boolean	否	是否启用邮件通知
notification.webhook.url	string	否	Webhook回调URL
notification.webhook.events	string[]	否	订阅的事件类型列表
scrapeOptions	object	否	抓取选项（formats、onlyMainContent等）

Webhook配置参数

参数名	类型	描述
maxRetries	number	最大重试次数，默认3次
backoffFactor	number	指数退避因子（秒），默认0.5
timeout	number	单次投递超时（毫秒）

错误处理机制

监控错误分类

错误类型	处理方式	影响范围
网络超时	记录错误、重试	单次检查标记为失败
页面加载失败	记录错误、跳过内容对比	计入error_count统计
解析异常	记录错误、保留原始内容	可能导致Diff不准确

Webhook投递错误

Webhook投递失败时，系统会根据HTTP响应状态码采取不同策略：

状态码范围	处理策略
2xx	投递成功，任务完成
4xx（除429）	永久失败，不重试
429/5xx	指数退避重试，直到达到最大次数

安全考虑

Webhook安全

请求签名：Webhook请求包含签名头，用于验证消息来源
HTTPS强制：仅支持HTTPS端点，确保传输安全
幂等性设计：Webhook投递设计为幂等操作，允许安全重放

数据保护

敏感信息过滤：邮件通知中的敏感数据经过适当处理
HTML转义：所有用户提供的URL和标题在邮件中经过HTML转义

最佳实践

合理设置轮询间隔：根据网站更新频率调整，避免过度抓取
配置多个通知渠道：同时启用邮件和Webhook，确保重要变更不被遗漏
设置Webhook重试机制：利用指数退避策略提高投递可靠性
利用A/B对比功能：在重要更新前后进行结果对比验证
监控积分消耗：定期检查creditsUsed字段，合理规划监控规模

多语言SDK

Firecrawl 多语言SDK是一组官方支持的客户端库，旨在为开发者提供跨编程语言的统一接口，以便轻松访问Firecrawl的网页搜索、抓取和交互功能。这些SDK自动处理HTTP请求、身份验证、响应解析以及异步操作的轮询机制，使开发者能够在Python、JavaScript、Java、Go、Rust、.NET、Ruby等多种主流编程语言中使用Firecrawl服务。

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 认证方式

继续阅读本节完整说明和来源证据。

章节 自定义API端点

继续阅读本节完整说明和来源证据。

章节 Search 搜索

继续阅读本节完整说明和来源证据。

概述

支持的编程语言

Firecrawl目前官方支持以下编程语言的SDK：

编程语言	包名称	安装命令	主要类/客户端
Python	`firecrawl-py`	`pip install firecrawl-py`	`Firecrawl`
JavaScript/TypeScript	`@mendable/firecrawl-js`	`npm install @mendable/firecrawl-js`	`Firecrawl`
Java	`firecrawl-java`	Maven/Gradle依赖	`FirecrawlClient`
Go	`firecrawl-sdk`	`go get`	`Firecrawl`
Rust	`firecrawl`	Cargo.toml	`Client`
.NET	`firecrawl-sdk`	`dotnet add package firecrawl-sdk`	`FirecrawlClient`
Ruby	`firecrawl-sdk`	`gem install firecrawl-sdk`	`Client`

核心功能

所有SDK都提供一致的核心功能集，确保开发者无论使用何种编程语言都能获得相同的能力：

graph TD
    A[Firecrawl SDK] --> B[Search 搜索]
    A --> C[Scrape 网页抓取]
    A --> D[Crawl 网站爬取]
    A --> E[Parse 文件解析]
    A --> F[Map 站点地图]
    A --> G[Interact 页面交互]
    A --> H[Extract 结构化提取]
    
    B --> I[返回搜索结果]
    C --> J[返回文档内容]
    D --> K[批量页面抓取]
    E --> L[支持HTML/PDF/DOCX]
    F --> M[URL列表生成]
    G --> N[浏览器自动化]
    H --> O[JSON Schema提取]

客户端初始化

认证方式

所有SDK支持两种API密钥配置方式：

方式一：通过构造函数直接传入

# Python
from firecrawl import Firecrawl
app = Firecrawl(api_key="fc-YOUR_API_KEY")

// JavaScript/TypeScript
import Firecrawl from '@mendable/firecrawl-js';
const app = new Firecrawl({ apiKey: 'fc-YOUR_API_KEY' });

// Java
FirecrawlClient client = FirecrawlClient.builder()
    .apiKey("fc-your-api-key")
    .build();

// .NET
var client = new FirecrawlClient("fc-your-api-key");

方式二：通过环境变量自动加载

各SDK会优先读取环境变量FIRECRAWL_API_KEY：

# Python - 无需传入API key，自动从环境变量读取
app = Firecrawl.from_env()

// Java - 默认从FIRECRAWL_API_KEY环境变量读取
FirecrawlClient client = FirecrawlClient.fromEnv();

# Ruby
client = Firecrawl::Client.from_env

// Go
client := firecrawl.NewClient(os.Getenv("FIRECRAWL_API_KEY"), "")

自定义API端点

对于自托管的Firecrawl实例，部分SDK支持自定义API URL：

// .NET - 自定义API URL
var client = new FirecrawlClient(
    apiKey: "fc-your-api-key",
    apiUrl: "https://your-firecrawl-instance.com");

// JavaScript/TypeScript - 可在初始化时配置
const app = new Firecrawl({ 
    apiKey: "fc-your-api-key",
    apiUrl: "https://your-firecrawl-instance.com"
});

核心API

Search 搜索

在网络上搜索相关内容，返回与查询匹配的URL和摘要：

# Python
results = app.search("best AI data tools 2024", limit=10)

// JavaScript
const results = await app.search('firecrawl', { limit: 5 });

// Rust
let response = client.search("best web scraping tools 2024", None).await?;

Scrape 网页抓取

从单个URL提取内容，支持多种输出格式：

参数	类型	说明
`url`	string	目标网页URL
`formats`	array	输出格式：`markdown`, `html`, `json`, `screenshot`等
`onlyMainContent`	boolean	仅提取主要内容
`waitFor`	number	等待渲染的毫秒数

# Python
doc = app.scrape('https://firecrawl.dev', formats=['markdown', 'html'])
print(doc.markdown)

// Java
Document doc = client.scrape("https://example.com",
    ScrapeOptions.builder()
        .formats(List.of("markdown"))
        .build());

// .NET
var doc = await client.ScrapeAsync("https://example.com",
    new ScrapeOptions { Formats = new List<object> { "markdown" } });

Crawl 网站爬取

批量爬取网站页面，支持自动轮询等待完成：

# Python - 自动等待爬取完成
docs = app.crawl('https://docs.firecrawl.dev', limit=50)
for doc in docs.data:
    print(doc.metadata.source_url)

# Ruby - 自动轮询模式
job = client.crawl("https://example.com",
  Firecrawl::Models::CrawlOptions.new(limit: 50))
job.data.each { |doc| puts doc.markdown }

// Rust
let options = CrawlOptions {
    limit: Some(50),
    ..Default::default()
};
let result = client.crawl("https://docs.firecrawl.dev", options).await?;

Map 站点地图

生成网站的URL列表，用于了解站点结构：

// JavaScript
const mapResult = await app.map('https://example.com');
console.log(mapResult);

Interact 页面交互

在抓取页面后执行浏览器自动化操作：

# Python
result = app.scrape("https://amazon.com")
scrape_id = result.metadata.scrape_id
app.interact(scrape_id, prompt="Search for 'mechanical keyboard'")

// Java
Document doc = client.scrape("https://example.com");
String scrapeId = String.valueOf(doc.getMetadata().get("scrapeId"));
BrowserExecuteResponse exec = client.interact(scrapeId, "console.log(await page.title());");

Extract 结构化提取

根据prompt和schema从页面提取结构化数据：

// JavaScript - 支持Zod schema
const schema = z.object({
  title: z.string(),
});
const result = await app.extract({
  urls: ['https://firecrawl.dev'],
  prompt: 'Extract the page title',
  schema,
});

Batch Scrape 批量抓取

一次性抓取多个URL：

# Python
job = app.batch_scrape([
    "https://firecrawl.dev",
    "https://docs.firecrawl.dev",
], formats=["markdown"])
for doc in job.data:
    print(doc.metadata.source_url)

Parse 文件解析

解析上传的本地文件（HTML、PDF、DOCX等）：

# Python
doc = firecrawl.parse(
  b"<!DOCTYPE html><html><body><h1>Content</h1></body></html>",
  filename="upload.html",
  content_type="text/html",
  options=ParseOptions(formats=["markdown"]),
)

// Java
ParseFile file = ParseFile.builder()
    .filename("upload.html")
    .content("<!DOCTYPE html>...".getBytes())
    .contentType("text/html")
    .build();
Document parsed = client.parse(file,
    ParseOptions.builder()
        .formats(List.of("markdown"))
        .build());

异步操作

异步爬取工作流

sequenceDiagram
    participant 客户端
    participant Firecrawl API
    participant 用户
    
    客户端->>Firecrawl API: start_crawl/startCrawl
    Firecrawl API-->>客户端: 返回job_id
    客户端->>Firecrawl API: get_crawl_status(job_id)
    Firecrawl API-->>客户端: status: in_progress
    客户端->>Firecrawl API: get_crawl_status(job_id)
    Firecrawl API-->>客户端: status: completed, data: [...]

异步爬取示例

// JavaScript/TypeScript - 开始异步爬取
const start = await app.startCrawl('https://mendable.ai', {
  excludePaths: ['blog/*'],
  limit: 5,
});

// 检查爬取状态
const status = await app.getCrawlStatus(start.id);
console.log(status.status);

# Ruby - 异步爬取
response = client.start_crawl("https://example.com",
  Firecrawl::Models::CrawlOptions.new(limit: 10))
puts response.id

# 检查状态
status = client.get_crawl_status(response.id)
puts status.status

# 取消爬取
client.cancel_crawl(response.id)

数据模型

Document 文档对象

SDK返回的文档对象通常包含以下属性：

属性	类型	说明
`markdown`	string	页面内容的Markdown格式
`html`	string	原始HTML内容
`metadata`	object	元数据（标题、描述、来源URL等）
`raw`	object	原始响应数据
`json`	object	提取的JSON数据（当使用json格式时）

# Python - 访问文档属性
doc = app.scrape('https://example.com')
print(doc.markdown)       # Markdown内容
print(doc.metadata.title) # 页面标题
print(doc.metadata.source_url) # 来源URL

ScrapeOptions 抓取选项

选项	类型	说明
`formats`	array	输出格式列表
`onlyMainContent`	boolean	仅提取主要内容，移除噪音
`waitFor`	number	等待JavaScript渲染的毫秒数
`headers`	object	自定义HTTP头
`proxy`	string	代理设置

错误处理

各SDK使用各自语言的原生错误处理机制：

# Python - 使用异常处理
try:
    doc = app.scrape('https://example.com')
except Exception as e:
    print(f"抓取失败: {e}")

// Rust - 使用Result类型
match scrape_result {
    Ok(data) => println!("{}", data.markdown),
    Err(e) => eprintln!("抓取失败: {}", e),
}

// Java - 异常处理
try {
    Document doc = client.scrape("https://example.com", options);
} catch (FirecrawlException e) {
    System.err.println("API错误: " + e.getMessage());
}

SDK架构对比

graph LR
    subgraph Python
        P1[Firecrawl类]
        P2[v2.Client]
    end
    
    subgraph JavaScript
        J1[Firecrawl类]
        J2[v2.Client]
    end
    
    subgraph Java
        K1[FirecrawlClient]
        K2[Builder模式]
    end
    
    subgraph Rust
        R1[Client结构体]
        R2[异步方法]
    end
    
    P1 --> P2
    J1 --> J2
    K1 --> K2
    R1 --> R2

依赖要求

SDK	最低版本要求	额外依赖
Python	Python 3.8+	`requests`
JavaScript	Node.js兼容	-
Java	JDK 11+	-
Go	Go 1.16+	-
Rust	Rust最新稳定版	`tokio` (异步运行时)
.NET	.NET Core 6.0+	-
Ruby	Ruby 3.0+	-

最佳实践

1. 环境变量管理

建议在生产环境中使用环境变量存储API密钥：

# 设置环境变量
export FIRECRAWL_API_KEY="fc-your-api-key"

2. 异步操作处理

对于大量页面的爬取任务，使用异步方法并实现适当的重试机制：

# Python - 配置重试和超时
from firecrawl import Firecrawl
app = Firecrawl(api_key="fc-YOUR_API_KEY")
docs = app.crawl('https://example.com', limit=100, poll_interval=30)

3. 错误重试

# Python - 实现重试逻辑
import time
def scrape_with_retry(url, max_retries=3):
    for i in range(max_retries):
        try:
            return app.scrape(url)
        except Exception as e:
            if i == max_retries - 1:
                raise
            time.sleep(2 ** i)

部署与基础设施

Firecrawl 的部署与基础设施体系支持多种部署模式，包括本地开发、Docker 容器化部署、Kubernetes 集群部署以及云原生架构。该项目采用微服务架构，主要包含 API 服务、Playwright 渲染服务、Redis 缓存层和数据库存储层等核心组件。通过 Helm Chart 和 Docker Compose 两种主流编排工具，开发者可以灵活选择适合自身环境...

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 整体架构图

继续阅读本节完整说明和来源证据。

章节 核心组件

继续阅读本节完整说明和来源证据。

章节 多架构镜像构建

继续阅读本节完整说明和来源证据。

概述

Firecrawl 的基础设施设计遵循以下核心原则：可扩展性支持水平扩展以应对高并发场景；多架构支持涵盖 x86 和 ARM64 平台；环境隔离通过容器化实现开发与生产环境的统一；可观测性内置日志、监控和追踪能力。

系统架构

整体架构图

graph TD
    A[客户端请求] --> B[API 网关 / 负载均衡]
    B --> C[Firecrawl API 服务]
    C --> D[Redis 缓存层]
    C --> E[PostgreSQL 数据库]
    C --> F[Playwright 服务]
    F --> G[浏览器实例池]
    G --> H[渲染后的页面内容]
    H --> C
    C --> I[返回 LLM 可用的数据格式]

核心组件

组件名称	技术栈	功能描述
Firecrawl API	Node.js/TypeScript	核心 REST API 服务，处理爬取、搜索、交互请求
Playwright 服务	TypeScript + Playwright	浏览器自动化渲染，支持截图和 JavaScript 执行
Redis	Redis	任务队列、缓存、会话存储
PostgreSQL	PostgreSQL	持久化存储爬取任务、文档数据、用户信息
多语言 SDK	Python/JS/Ruby/PHP/Go/Rust/.NET/Java	官方客户端库，简化 API 集成

资料来源：README.md:1-50

Docker 容器化部署

多架构镜像构建

Firecrawl 支持同时构建适用于 x86_64 (amd64) 和 ARM64 (arm64) 架构的 Docker 镜像。这对于在 Apple Silicon Mac 或基于 ARM 的云服务器上运行的场景尤为重要。

# 创建并使用 docker buildx 构建器
docker buildx create --name multiarch --use --bootstrap

# 构建并推送多架构镜像
docker buildx build --platform linux/amd64,linux/arm64 --push \
  -t docker.io/winkkgmbh/firecrawl:latest \
  ../../../apps/api

资料来源：examples/kubernetes/firecrawl-helm/README.md:45-55

官方镜像仓库

Firecrawl 维护以下官方容器镜像：

镜像名称	用途	仓库地址
firecrawl	主 API 服务	ghcr.io/firecrawl/firecrawl
playwright-service	浏览器渲染服务	ghcr.io/firecrawl/playwright-service
nuq-postgres	数据库服务	ghcr.io/firecrawl/nuq-postgres

开发者可以使用这些官方镜像快速部署，或通过 docker-compose.yaml 进行本地开发环境搭建。

Kubernetes 部署

Helm Chart 架构

Firecrawl 提供完整的 Helm Chart 用于 Kubernetes 集群部署，支持通过 values.yaml 进行灵活配置。Chart 遵循 Kubernetes 最佳实践，包括健康检查探针、资源限制、环境变量配置和持久化存储。

# 基础部署命令
HELM_NO_PLUGINS=1 helm upgrade firecrawl . \
  -f values.yaml \
  -f overlays/prod/values.yaml \
  -n firecrawl \
  --install \
  --create-namespace

资料来源：examples/kubernetes/firecrawl-helm/README.md:25-35

生产环境配置

生产环境部署通常需要合并多层配置文件：

# 生产环境覆盖配置示例
replicaCount: 3
image:
  repository: ghcr.io/firecrawl/firecrawl
resources:
  requests:
    memory: "512Mi"
    cpu: "250m"
  limits:
    memory: "2Gi"
    cpu: "1000m"

使用官方镜像

对于纯 x86 架构的集群，可以直接使用官方预构建镜像：

HELM_NO_PLUGINS=1 helm upgrade firecrawl . \
  -f values.yaml \
  --set image.repository=ghcr.io/firecrawl/firecrawl \
  --set playwright.repository=ghcr.io/firecrawl/playwright-service \
  --set nuqPostgres.image.repository=ghcr.io/firecrawl/nuq-postgres \
  -n firecrawl \
  --install \
  --create-namespace

资料来源：examples/kubernetes/firecrawl-helm/README.md:36-48

环境变量配置

必需配置项

环境变量	说明	示例值
`FIRECRAWL_API_KEY`	API 认证密钥	`fc-your-api-key-here`
`DATABASE_URL`	PostgreSQL 连接字符串	`postgresql://user:pass@host:5432/db`
`REDIS_URL`	Redis 连接字符串	`redis://localhost:6379`

SDK 环境配置

各语言 SDK 均支持从环境变量自动读取配置：

# Python SDK
from firecrawl import Firecrawl
app = Firecrawl()  # 自动读取 FIRECRAWL_API_KEY

# JavaScript SDK
const app = new Firecrawl({ apiKey: process.env.FIRECRAWL_API_KEY });

# Ruby SDK
client = Firecrawl::Client.from_env  # 读取 FIRECRAWL_API_KEY

# PHP SDK
$client = FirecrawlClient::fromEnv();

# Shell 环境配置
export FIRECRAWL_API_KEY="fc-your-api-key-here"
# 可选：自定义 API URL（用于自托管实例）
export FIRECRAWL_API_URL="http://localhost:3002"

资料来源：apps/python-sdk/README.md:1-30, apps/js-sdk/firecrawl/README.md:1-25, apps/ruby-sdk/README.md:1-20, apps/php-sdk/README.md:1-20

服务发现与网络

服务间通信

graph LR
    A[SDK 客户端] -->|HTTPS| B[API 服务 :3000]
    B -->|内部通信| C[Playwright 服务 :3001]
    B -->|TCP| D[Redis :6379]
    B -->|TCP| E[PostgreSQL :5432]

API 服务默认监听 3000 端口，Playwright 渲染服务默认监听 3001 端口。服务间通过内部网络通信，无需对外暴露。

自托管实例配置

对于自托管部署，可以通过环境变量指定自定义 API 地址：

// .NET SDK
var client = new FirecrawlClient(
    apiKey: "fc-your-api-key",
    apiUrl: "https://your-firecrawl-instance.com"
);

// Java SDK
FirecrawlClient client = FirecrawlClient.builder()
    .apiUrl("https://your-firecrawl-instance.com")
    .apiKey("fc-your-api-key")
    .build();

资源规划

健康检查配置

Kubernetes 部署中包含以下健康检查：

存活探针 (Liveness Probe)：检测服务是否存活，失败时重启容器
就绪探针 (Readiness Probe)：检测服务是否就绪，失败时停止接收流量
启动探针 (Startup Probe)：给予服务足够时间完成初始化

安全考虑

网络策略

生产环境建议配置 Kubernetes NetworkPolicy，限制以下流量：

API 服务仅接收来自负载均衡器的流量
Playwright 服务仅接收来自 API 服务的内部流量
数据库仅接收来自 API 服务的流量
Redis 仅接收来自 API 服务的流量

密钥管理

API 密钥应通过 Kubernetes Secret 或外部密钥管理服务（如 AWS Secrets Manager、HashiCorp Vault）存储，避免在 values.yaml 中明文配置。

监控与日志

日志聚合

Firecrawl API 服务输出结构化日志，建议通过以下方式收集：

标准输出/标准错误：Kubernetes 默认收集方式
日志聚合器：如 Fluentd、Filebeat 收集到 Elasticsearch/Loki
云原生方案：CloudWatch Logs、Azure Monitor、Google Cloud Logging

关键指标

指标名称	说明	告警阈值建议
请求延迟 P99	API 响应时间	> 10s
错误率	5xx 错误占比	> 5%
队列深度	Redis 待处理任务数	> 1000
浏览器实例数	Playwright 活跃实例	< 2（表示可能泄漏）

备份与恢复

数据库备份

PostgreSQL 数据库应配置以下备份策略：

自动全量备份：每日执行，保留 30 天
增量备份：每 6 小时执行
点时间恢复 (PITR)：启用 Write-Ahead Log (WAL) 归档

灾难恢复

灾难恢复计划应包含：

RTO（恢复时间目标）：< 4 小时
RPO（恢复点目标）：< 1 小时
恢复流程文档化：包含步骤验证清单
定期演练：每季度执行恢复演练

部署最佳实践

CI/CD 集成

# 示例 GitHub Actions 部署流程
deploy:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - name: Build and push images
      run: |
        docker buildx build \
          --platform linux/amd64,linux/arm64 \
          --push \
          -t ${{ env.REGISTRY }}/firecrawl:${{ github.sha }} .
    - name: Deploy to Kubernetes
      run: |
        helm upgrade firecrawl ./charts/firecrawl \
          --set image.tag=${{ github.sha }}

滚动更新策略

建议使用 RollingUpdate 策略配置蓝绿部署或滚动更新：

strategy:
  type: RollingUpdate
  rollingUpdate:
    maxSurge: 1
    maxUnavailable: 0

开发指南

本文档为 Firecrawl 项目提供全面的开发指南，涵盖开发环境配置、代码规范、测试策略、多语言 SDK 开发等内容。

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 环境要求

继续阅读本节完整说明和来源证据。

章节 项目结构

继续阅读本节完整说明和来源证据。

章节 代码质量工具

继续阅读本节完整说明和来源证据。

项目概述

Firecrawl 是一个用于搜索、抓取网页内容并将其转换为 LLM 可用格式的 web scraping 工具。项目采用多语言 SDK 架构，核心 API 服务使用 TypeScript/Node.js 开发，同时提供 Python、JavaScript/TypeScript、Rust、Go、Java、Ruby、.NET 等多语言 SDK。

graph TB
    subgraph 核心服务
        A[API Server<br/>TypeScript/Node.js]
        B[Playwright Service]
        C[数据库服务]
    end
    
    subgraph SDK层
        D[Python SDK]
        E[JS/TS SDK]
        F[Rust SDK]
        G[Go SDK]
        H[Java SDK]
        I[Ruby SDK]
        J[.NET SDK]
    end
    
    K[外部用户]
    
    A --> B
    A --> C
    K --> D
    K --> E
    K --> F
    K --> G
    K --> H
    K --> I
    K --> J
    D --> A
    E --> A
    F --> A
    G --> A

开发环境配置

环境要求

根据不同开发任务，需要安装以下环境：

组件	版本要求	用途
Node.js	18+	API 服务开发
Python	3.9+	Python SDK 开发
Rust	1.70+	Rust SDK 开发
Java	11+	Java SDK 开发
Go	1.20+	Go SDK 开发
Ruby	3.0+	Ruby SDK 开发
.NET	6.0+	.NET SDK 开发
Gradle	8+	Java SDK 构建

项目结构

firecrawl/
├── apps/
│   ├── api/                    # 核心 API 服务 (TypeScript)
│   ├── playwright-service-ts/   # Playwright 浏览器服务
│   ├── python-sdk/              # Python SDK
│   ├── js-sdk/                  # JavaScript/TypeScript SDK
│   ├── rust-sdk/                # Rust SDK
│   ├── go-sdk/                  # Go SDK
│   ├── java-sdk/                # Java SDK
│   ├── ruby-sdk/                # Ruby SDK
│   ├── dot-net-sdk/             # .NET SDK
│   └── test-suite/              # 测试套件
├── examples/                    # 使用示例
│   └── kubernetes/              # Kubernetes 部署配置
└── sharedLibs/                  # 共享库
    └── go-html-to-md/           # Go HTML 转 Markdown 库

代码规范与工具链

代码质量工具

Firecrawl 项目使用 Knip 进行代码质量检查和未使用依赖分析。配置文件位于 apps/api/knip.config.ts：

// apps/api/knip.config.ts
import type { KnipConfig } from "knip";
const config: KnipConfig = {
  // 入口文件和项目结构配置
  project: ["**/*.{ts,tsx,js,jsx}"],
  // 忽略的文件
  ignore: ["**/*.test.ts", "**/node_modules/**"],
};
export default config;

代码检查命令

# 运行 Knip 检查
npx knip

# 或添加自定义配置
npx knip --config knip.config.ts

Linting 配置

项目采用标准的 ESLint 配置，建议在提交前运行 lint 检查确保代码风格一致。

测试策略

测试框架

Firecrawl 使用 Jest 作为主要的测试框架。API 服务和测试套件分别有不同的配置文件。

#### API 服务测试配置

// apps/api/jest.config.ts
import type { Config } from "jest";

const config: Config = {
  preset: "ts-jest",
  testEnvironment: "node",
  roots: ["<rootDir>/src"],
  testMatch: ["**/*.test.ts"],
  transform: {
    "^.+\\.tsx?$": ["ts-jest", {
      tsconfig: "tsconfig.json",
    }],
  },
  moduleNameMapper: {
    "^@/(.*)$": "<rootDir>/src/$1",
  },
};

export default config;

#### 测试套件配置

// apps/test-suite/jest.config.js
module.exports = {
  testEnvironment: "node",
  testMatch: ["**/*.test.{js,ts}"],
  // 测试超时设置
  testTimeout: 30000,
};

编写测试用例

#### URL 验证测试示例

// apps/api/src/lib/validateUrl.test.ts
import { validateUrl } from "./validateUrl";

describe("URL Validation", () => {
  it("should validate correct URLs", () => {
    expect(validateUrl("https://example.com")).toBe(true);
    expect(validateUrl("http://test.org/path")).toBe(true);
  });

  it("should reject invalid URLs", () => {
    expect(validateUrl("not-a-url")).toBe(false);
    expect(validateUrl("ftp://invalid-protocol.com")).toBe(false);
  });
});

#### 抓取功能测试示例

// apps/api/src/scraper/scrapeURL/scrapeURL.test.ts
import { scrapeURL } from "./scrapeURL";
import { FirecrawlDocument } from "../../../models/firecrawl-document";

describe("scrapeURL", () => {
  const mockUrl = "https://example.com";
  const mockOptions = {
    formats: ["markdown", "html"] as const,
    onlyMainContent: true,
  };

  it("should scrape a URL and return markdown", async () => {
    const result: FirecrawlDocument = await scrapeURL(mockUrl, mockOptions);
    
    expect(result.markdown).toBeDefined();
    expect(result.markdown).not.toBeEmpty();
  });

  it("should respect onlyMainContent option", async () => {
    const result = await scrapeURL(mockUrl, mockOptions);
    
    expect(result.markdown).not.toContain("<nav>");
    expect(result.markdown).not.toContain("<header>");
  });
});

运行测试

# 运行所有测试
npm test

# 运行特定测试文件
npm test -- validateUrl.test.ts

# 运行测试并生成覆盖率报告
npm test -- --coverage

# 运行测试套件
cd apps/test-suite && npm test

测试最佳实践

实践	说明	资料来源
测试文件命名	使用 `.test.ts` 后缀	`apps/api/jest.config.ts:6`
测试环境隔离	每个测试独立运行	`apps/api/jest.config.ts:5`
模拟外部依赖	使用 Jest mocks	`apps/api/src/scraper/scrapeURL/scrapeURL.test.ts`
异步测试	使用 async/await	`apps/api/src/scraper/scrapeURL/scrapeURL.test.ts:12`
超时配置	复杂测试设置超时	`apps/test-suite/jest.config.js:6`

多语言 SDK 开发

Python SDK

#### 环境配置

# 使用虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/Mac
# 或
.\venv\Scripts\activate   # Windows

# 安装依赖
pip install firecrawl

#### 快速开始

# apps/python-sdk/README.md
from firecrawl import Firecrawl

# 创建客户端
firecrawl = Firecrawl(api_key="fc-YOUR_API_KEY")

# 抓取网页
scrape_result = firecrawl.scrape(
    'https://firecrawl.dev', 
    formats=['markdown', 'html']
)
print(scrape_result)

# 爬取网站
crawl_status = firecrawl.crawl(
    'https://firecrawl.dev', 
    limit=100, 
    scrape_options=ScrapeOptions(formats=['markdown', 'html']),
    poll_interval=30
)

#### SDK 包结构

模块	功能
`firecrawl`	主客户端类
`firecrawl.v2.types`	类型定义 (ParseOptions, ScrapeOptions)

JavaScript/TypeScript SDK

#### 环境配置

npm install @mendable/firecrawl-js

#### 快速开始

// apps/js-sdk/firecrawl/README.md
import Firecrawl from '@mendable/firecrawl-js';

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

// 搜索
const searchResult = await app.search("firecrawl", { limit: 5 });

// 抓取
const scrapeResult = await app.scrape('https://example.com', {
  formats: ['markdown', 'html'],
  onlyMainContent: true,
});

// 爬取
const crawlResult = await app.crawl('https://firecrawl.dev', {
  limit: 100,
  scrapeOptions: { formats: ['markdown', 'html'] },
});

#### 异步爬取

// 启动异步爬取任务
const start = await app.startCrawl('https://mendable.ai', {
  excludePaths: ['blog/*'],
  limit: 5,
});

// 检查爬取状态
const status = await app.getCrawlStatus(start.jobId);

Rust SDK

#### 环境配置

# apps/rust-sdk/README.md
[dependencies]
firecrawl = "2.1.0"
tokio = { version = "^1", features = ["full"] }

#### 快速开始

use firecrawl::{Client, ScrapeOptions, Format, CrawlOptions};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new("fc-YOUR_API_KEY")?;

    // 抓取 URL
    let document = client.scrape("https://firecrawl.dev", None).await?;
    println!("{:?}", document.markdown);

    // 爬取网站
    let options = CrawlOptions {
        limit: Some(50),
        ..Default::default()
    };
    let result = client.crawl("https://docs.firecrawl.dev", options).await?;

    // 搜索
    let response = client.search("best web scraping tools 2024", None).await?;

    Ok(())
}

Java SDK

#### 环境配置

// apps/java-sdk/README.md
repositories {
    mavenCentral()
}

dependencies {
    implementation 'com.firecrawl:firecrawl-java:1.1.1'
}

#### 快速开始

import com.firecrawl.client.FirecrawlClient;
import com.firecrawl.models.*;
import java.util.List;

// 创建客户端
FirecrawlClient client = FirecrawlClient.builder()
    .apiKey("fc-your-api-key")
    .build();

// 抓取网页
Document doc = client.scrape("https://example.com",
    ScrapeOptions.builder()
        .formats(List.of("markdown"))
        .build());

System.out.println(doc.getMarkdown());

.NET SDK

#### 环境配置

dotnet add package firecrawl-sdk

#### 快速开始

// apps/dotnet-sdk/README.md
using Firecrawl;
using Firecrawl.Models;

var client = new FirecrawlClient("fc-your-api-key");

// 抓取单个页面
var doc = await client.ScrapeAsync("https://example.com",
    new ScrapeOptions { Formats = new List<object> { "markdown" } });

Console.WriteLine(doc.Markdown);

Go SDK

Go SDK 位于 apps/go-sdk，提供与 Firecrawl API 交互的 Go 语言接口。

Ruby SDK

#### 环境配置

# apps/ruby-sdk/README.md
gem "firecrawl-sdk", "~> 1.0"

#### 快速开始

require "firecrawl"

# 创建客户端
client = Firecrawl::Client.new(api_key: "fc-your-api-key")

# 抓取单个页面
doc = client.scrape("https://example.com")
puts doc.markdown

贡献指南

提交流程

``bash git checkout -b feature/your-feature-name ``

Fork 仓库 - 从主仓库创建个人分支
创建分支 - 使用描述性的分支名称
编写代码 - 遵循项目的代码规范
添加测试 - 确保新功能有对应的测试用例
运行测试 - 提交前确保所有测试通过
提交更改 - 编写清晰的提交信息
创建 Pull Request - 描述更改内容和动机

代码审查要点

审查项	要求	资料来源
代码风格	通过 lint 检查	`apps/api/knip.config.ts`
测试覆盖	新功能必须包含测试	`apps/api/jest.config.ts`
文档更新	更新相关 README	`CONTRIBUTING.md`
向后兼容	不破坏现有 API	多语言 SDK 文档

开发工作流

graph LR
    A[创建分支] --> B[编写代码]
    B --> C[添加测试]
    C --> D[运行测试]
    D --> E{测试通过?}
    E -->|否| F[修复问题]
    F --> D
    E -->|是| G[提交代码]
    G --> H[创建 PR]
    H --> I[代码审查]
    I --> J{审查通过?}
    J -->|否| K[修改代码]
    K --> I
    J -->|是| L[合并到主分支]

调试与问题排查

常见问题

#### 1. 测试失败

# 查看详细错误信息
npm test -- --verbose

# 运行单个测试
npm test -- validateUrl.test.ts --verbose

# 调试模式
npm test -- --inspect-brk

#### 2. API 连接问题

检查以下配置：

FIRECRAWL_API_KEY 环境变量是否设置
API 端点是否可访问
网络代理配置是否正确

#### 3. SDK 导入错误

确保安装了正确版本的 SDK：

SDK	最低版本
Python	firecrawl 2.x
JavaScript	@mendable/firecrawl-js 0.x
Rust	firecrawl 2.1.0
Java	firecrawl-java 1.1.1

高级配置

自定义 API 端点

对于自托管实例，可以指定自定义 API URL：

// JavaScript SDK
const app = new Firecrawl({ 
  apiKey: "fc-your-key",
  apiUrl: "https://your-firecrawl-instance.com"
});

# Python SDK
firecrawl = Firecrawl(
    api_key="fc-your-key",
    api_url="https://your-firecrawl-instance.com"
)

// .NET SDK
var client = new FirecrawlClient(
    apiKey: "fc-your-key",
    apiUrl: "https://your-firecrawl-instance.com"
);

自定义 HTTP 客户端

// .NET SDK - 自定义 HttpClient
var httpClient = new HttpClient { Timeout = TimeSpan.FromSeconds(60) };
var client = new FirecrawlClient(
    apiKey: "fc-your-api-key",
    httpClient: httpClient);

环境变量配置

变量名	说明	用途
`FIRECRAWL_API_KEY`	API 密钥	认证
`FIRECRAWL_API_URL`	API 端点 (可选)	自托管实例
`FIRECRAWL_RATE_LIMIT`	请求限速	避免 API 限流

失败模式与踩坑日记

保留 Doramagic 在发现、验证和编译中沉淀的项目专属风险，不把社区讨论只当作装饰信息。

high 来源证据：RFC: Lightweight External Memory Capsule Pattern for Firecrawl Agent Workflows

可能影响升级、迁移或版本选择。

medium 来源证据：v2.4.0

可能增加新用户试用和生产接入成本。

medium 来源证据：[Bug] /interact with language="python" flakily fails with TargetClosedError on scrape-bound sessions

可能增加新用户试用和生产接入成本。

medium 能力判断依赖假设

假设不成立时，用户拿不到承诺的能力。

Pitfall Log / 踩坑日志

项目：firecrawl/firecrawl

摘要：发现 21 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：RFC: Lightweight External Memory Capsule Pattern for Firecrawl Agent Workflows。

1. 安全/权限坑 · 来源证据：RFC: Lightweight External Memory Capsule Pattern for Firecrawl Agent Workflows

严重度：high
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：RFC: Lightweight External Memory Capsule Pattern for Firecrawl Agent Workflows
对用户的影响：可能影响升级、迁移或版本选择。
建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
证据：community_evidence:github | cevd_0bf31b0e8c3b45fb8da04cebb259c8a4 | https://github.com/firecrawl/firecrawl/issues/3500 | 来源类型 github_issue 暴露的待验证使用条件。

2. 安装坑 · 来源证据：v2.4.0

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v2.4.0
对用户的影响：可能增加新用户试用和生产接入成本。
建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
证据：community_evidence:github | cevd_e1e417d6cea44fb79118e4daeac083a0 | https://github.com/firecrawl/firecrawl/releases/tag/v2.4.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

3. 配置坑 · 来源证据：[Bug] /interact with language="python" flakily fails with TargetClosedError on scrape-bound sessions

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Bug] /interact with language="python" flakily fails with TargetClosedError on scrape-bound sessions
对用户的影响：可能增加新用户试用和生产接入成本。
建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
证据：community_evidence:github | cevd_aa487261676d400197da5f3646baff2f | https://github.com/firecrawl/firecrawl/issues/3498 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

4. 能力坑 · 能力判断依赖假设

严重度：medium
证据强度：source_linked
发现：README/documentation is current enough for a first validation pass.
对用户的影响：假设不成立时，用户拿不到承诺的能力。
建议检查：将假设转成下游验证清单。
防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
证据：capability.assumptions | github_repo:787076358 | https://github.com/firecrawl/firecrawl | README/documentation is current enough for a first validation pass.

5. 运行坑 · 来源证据：[Feat] Emit batch scrape failures of each page to webhook

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：[Feat] Emit batch scrape failures of each page to webhook
对用户的影响：可能增加新用户试用和生产接入成本。
建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
证据：community_evidence:github | cevd_80c638d597cc432b9a74e7e336b043ee | https://github.com/firecrawl/firecrawl/issues/2576 | 来源类型 github_issue 暴露的待验证使用条件。

6. 维护坑 · 维护活跃度未知

严重度：medium
证据强度：source_linked
发现：未记录 last_activity_observed。
对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
防护动作：维护活跃度未知时，推荐强度不能标为高信任。
证据：evidence.maintainer_signals | github_repo:787076358 | https://github.com/firecrawl/firecrawl | last_activity_observed missing

7. 安全/权限坑 · 下游验证发现风险项

严重度：medium
证据强度：source_linked
发现：no_demo
对用户的影响：下游已经要求复核，不能在页面中弱化。
建议检查：进入安全/权限治理复核队列。
防护动作：下游风险存在时必须保持 review/recommendation 降级。
证据：downstream_validation.risk_items | github_repo:787076358 | https://github.com/firecrawl/firecrawl | no_demo; severity=medium

8. 安全/权限坑 · 存在安全注意事项

严重度：medium
证据强度：source_linked
发现：No sandbox install has been executed yet; downstream must verify before user use.
对用户的影响：用户安装前需要知道权限边界和敏感操作。
建议检查：转成明确权限清单和安全审查提示。
防护动作：安全注意事项必须面向用户前置展示。
证据：risks.safety_notes | github_repo:787076358 | https://github.com/firecrawl/firecrawl | No sandbox install has been executed yet; downstream must verify before user use.

9. 安全/权限坑 · 存在评分风险

严重度：medium
证据强度：source_linked
发现：no_demo
对用户的影响：风险会影响是否适合普通用户安装。
建议检查：把风险写入边界卡，并确认是否需要人工复核。
防护动作：评分风险必须进入边界卡，不能只作为内部分数。
证据：risks.scoring_risks | github_repo:787076358 | https://github.com/firecrawl/firecrawl | no_demo; severity=medium

10. 安全/权限坑 · 来源证据：[Feat] Support custom HTTP headers in Node.js SDK for self-hosted instances behind reverse proxies

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Feat] Support custom HTTP headers in Node.js SDK for self-hosted instances behind reverse proxies
对用户的影响：可能影响授权、密钥配置或安全边界。
建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
证据：community_evidence:github | cevd_ef6deffa53c147b29e617225612e55b0 | https://github.com/firecrawl/firecrawl/issues/2814 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

11. 安全/权限坑 · 来源证据：v2.0.1

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.0.1
对用户的影响：可能增加新用户试用和生产接入成本。
建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
证据：community_evidence:github | cevd_0334c6a4c3284763a02c66ac96ce9c0c | https://github.com/firecrawl/firecrawl/releases/tag/v2.0.1 | 来源类型 github_release 暴露的待验证使用条件。

12. 安全/权限坑 · 来源证据：v2.1.0

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.1.0
对用户的影响：可能增加新用户试用和生产接入成本。
建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
证据：community_evidence:github | cevd_360eac170b12452583bb9b7072acc4e3 | https://github.com/firecrawl/firecrawl/releases/tag/v2.1.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

13. 安全/权限坑 · 来源证据：v2.2.0

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.2.0
对用户的影响：可能影响授权、密钥配置或安全边界。
建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
证据：community_evidence:github | cevd_749e0e1b86ba455585d343764588f00e | https://github.com/firecrawl/firecrawl/releases/tag/v2.2.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

14. 安全/权限坑 · 来源证据：v2.3.0

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.3.0
对用户的影响：可能增加新用户试用和生产接入成本。
建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
证据：community_evidence:github | cevd_e6f1735e34a34eacb7b77e7bb21644a6 | https://github.com/firecrawl/firecrawl/releases/tag/v2.3.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

15. 安全/权限坑 · 来源证据：v2.5.0 - The World's Best Web Data API

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.5.0 - The World's Best Web Data API
对用户的影响：可能影响授权、密钥配置或安全边界。
建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
证据：community_evidence:github | cevd_4f928a2f370b4186ba4031bc4830020c | https://github.com/firecrawl/firecrawl/releases/tag/v2.5.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

16. 安全/权限坑 · 来源证据：v2.6.0

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.6.0
对用户的影响：可能影响授权、密钥配置或安全边界。
建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
证据：community_evidence:github | cevd_38343ea51e374e86a5081e46c837468c | https://github.com/firecrawl/firecrawl/releases/tag/v2.6.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

17. 安全/权限坑 · 来源证据：v2.7.0

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.7.0
对用户的影响：可能影响授权、密钥配置或安全边界。
建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
证据：community_evidence:github | cevd_4e1fdfc9cb714147a228b5ae01d273f2 | https://github.com/firecrawl/firecrawl/releases/tag/v2.7.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

18. 安全/权限坑 · 来源证据：v2.8.0

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.8.0
对用户的影响：可能影响授权、密钥配置或安全边界。
建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
证据：community_evidence:github | cevd_dd78eff5694c40cba109ef1230e1dc77 | https://github.com/firecrawl/firecrawl/releases/tag/v2.8.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

19. 安全/权限坑 · 来源证据：v2.9.0

严重度：medium
证据强度：source_linked
发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.9.0
对用户的影响：可能阻塞安装或首次运行。
建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
证据：community_evidence:github | cevd_a6219f53b7de4f31bb8ca1c7109fd49d | https://github.com/firecrawl/firecrawl/releases/tag/v2.9.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

20. 维护坑 · issue/PR 响应质量未知

严重度：low
证据强度：source_linked
发现：issue_or_pr_quality=unknown。
对用户的影响：用户无法判断遇到问题后是否有人维护。
建议检查：抽样最近 issue/PR，判断是否长期无人处理。
防护动作：issue/PR 响应未知时，必须提示维护风险。
证据：evidence.maintainer_signals | github_repo:787076358 | https://github.com/firecrawl/firecrawl | issue_or_pr_quality=unknown

21. 维护坑 · 发布节奏不明确

严重度：low
证据强度：source_linked
发现：release_recency=unknown。
对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
建议检查：确认最近 release/tag 和 README 安装命令是否一致。
防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
证据：evidence.maintainer_signals | github_repo:787076358 | https://github.com/firecrawl/firecrawl | release_recency=unknown

来源：Doramagic 发现、验证与编译记录

环境规模	API副本	Playwright副本	Redis	PostgreSQL
开发/测试	1	1	1GB	10GB
小规模生产	2	2	4GB	50GB
中等规模	5	5	8GB	200GB
大规模	10+	10+	16GB+	500GB+