## 项目概述

Firecrawl 是一个开源的 Web 上下文 API，旨在帮助 AI 代理和开发者大规模地搜索、抓取和交互网页内容。它能够将网页转换为干净的 Markdown 或结构化数据，支持 JavaScript 渲染的页面，并提供高可靠性和低延迟。项目采用 TypeScript 编写，遵循 AGPL-3.0 许可证，同时提供托管服务和自托管选项。

## 核心功能

- **搜索 (Search)**：搜索网页并获取结果的完整页面内容。
- **抓取 (Scrape)**：将任意 URL 转换为 Markdown、HTML、截图或结构化 JSON。
- **交互 (Interact)**：抓取页面后，通过 AI 提示或代码与页面进行交互（如点击、滚动、输入）。
- **代理 (Agent)**：通过自然语言描述需求，自动完成数据收集任务。
- **爬取 (Crawl)**：通过单个请求抓取网站的所有 URL。
- **地图 (Map)**：快速发现网站上的所有 URL。
- **批量抓取 (Batch Scrape)**：异步抓取数千个 URL。
- **媒体解析**：解析并提取网页托管的 PDF、DOCX 等文件内容。
- **动作 (Actions)**：在提取内容前执行点击、滚动、写入、等待等操作。

## 适用与不适用场景

**适用场景：**
- 为 AI 代理或 LLM 应用提供实时网页数据。
- 需要从复杂或 JavaScript 渲染的网站提取结构化数据。
- 大规模数据采集和内容聚合。
- 构建需要网页搜索和抓取能力的智能体。

**不适用场景：**
- 需要绕过网站访问控制或违反 robots.txt 的抓取行为。
- 对实时性要求极高且无法容忍 3.4 秒 P95 延迟的场景。
- 需要完全离线运行且不依赖外部服务的场景（自托管仍需基础设施）。

## 技术架构与依赖

- **语言**：TypeScript
- **许可证**：AGPL-3.0（SDK 和部分 UI 组件为 MIT）
- **主要依赖**：Node.js 22、pnpm 11.4.0、Redis、PostgreSQL、RabbitMQ（用于本地开发和自托管）
- **SDK 支持**：Python、Node.js、Go、Java、Elixir、Rust、Ruby、.NET、PHP
- **集成**：支持 MCP（Model Context Protocol）、Claude Code、Antigravity、OpenCode 等 AI 代理工具。

## 安装与快速开始

### 获取 API 密钥

在 [firecrawl.dev](https://firecrawl.dev) 注册并获取 API 密钥。

### 使用托管服务（推荐）

通过 SDK 或 REST API 直接调用，无需本地安装。

### 自托管

参考 [Self-Hosting Guide](https://docs.firecrawl.dev/contributing/self-host) 进行部署。需要 Node.js 22、pnpm、Redis、PostgreSQL 和 RabbitMQ。

### 本地开发

```bash
cd apps/api
pnpm install
pnpm start
```

## 典型使用方法

### 搜索

```python
from firecrawl import Firecrawl

app = Firecrawl(api_key="fc-YOUR_API_KEY")
search_result = app.search("firecrawl", limit=5)
```

### 抓取

```python
result = app.scrape('firecrawl.dev')
```

### 交互

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

### 代理（Agent）

```python
result = app.agent(prompt="Find the pricing plans for Notion")
```

### 爬取整个网站

```python
docs = app.crawl("https://docs.firecrawl.dev", limit=50)
```

## 配置与部署要点

- **API 密钥**：所有请求需在 Authorization 头中携带 Bearer 令牌。
- **环境变量**：自托管时需配置数据库、消息队列和 Redis 连接。
- **异步任务**：Crawl 和 Batch Scrape 为异步操作，SDK 会自动轮询状态。
- **模型选择**：Agent 功能支持 `spark-1-mini`（默认，成本低）和 `spark-1-pro`（复杂任务）。
- **合规性**：默认遵守 robots.txt，用户需自行确保抓取行为符合目标网站政策。

## 限制、风险与许可证

- **许可证**：AGPL-3.0（主项目），SDK 和部分 UI 组件为 MIT。
- **风险**：抓取行为可能违反网站服务条款，用户需自行承担风险。
- **限制**：托管服务有速率限制和配额；自托管需要维护基础设施。
- **数据合规**：用户应遵守适用的隐私政策和法律法规。

## 官方链接

- [GitHub 仓库](https://github.com/firecrawl/firecrawl)
- [官方文档](https://docs.firecrawl.dev)
- [API 参考](https://docs.firecrawl.dev/api-reference/introduction)
- [Playground](https://firecrawl.dev/playground)
- [Changelog](https://firecrawl.dev/changelog)
- [Discord 社区](https://discord.gg/firecrawl)

## 信息来源和分析时间

- **信息来源**：GitHub 仓库 README、CONTRIBUTING.md、最新发布信息（v2.11.0）。
- **分析时间**：2026年6月19日（基于最新发布信息）。