Firecrawl 完整教學

從 API 呼叫到 Self-Host 部署：如何用 Firecrawl 將整個 Web 轉換成 LLM-ready 的乾淨資料。

1. 專案定位

這是什麼？

Firecrawl 是一個開源 web scraping API（網頁抓取 API）平台，核心使命是：將網頁轉換成 AI agent 可直接使用的乾淨 Markdown 或 structured data（結構化資料）。

它不只是一個 scraper（爬蟲）— 它是一個完整的 web data infrastructure（網頁資料基礎設施），處理了所有困難的部分：rotating proxy（輪替代理）、JavaScript rendering（渲染）、rate limit（速率限制）、anti-bot detection（反機器人偵測）等。

核心數據

7 大核心能力

2. 安裝指南

方式 A：雲端 API（最快）

1. 註冊 firecrawl.dev
2. 取得 API key（格式 fc-YOUR_API_KEY）
3. 安裝 SDK

Python：

1pip install firecrawl-py

Node.js：

1npm install firecrawl

Rust：

1[dependencies]
2firecrawl = "2"

方式 B：Self-Host（Docker Compose）

 1git clone https://github.com/firecrawl/firecrawl.git
 2cd firecrawl
 3
 4# 建立 .env 檔案（必要環境變數）
 5cat > .env << 'EOF'
 6NUM_WORKERS_PER_QUEUE=8
 7CRAWL_CONCURRENT_REQUESTS=10
 8MAX_CONCURRENT_JOBS=5
 9BROWSER_POOL_SIZE=5
10PORT=3002
11HOST=0.0.0.0
12EOF
13
14# 啟動所有服務
15docker compose up -d

Self-host 會啟動 5 個服務：API、Playwright Service、Redis、RabbitMQ、NuQ-PostgreSQL。

方式 C：Agent Skill / MCP（一行接入）

1# 安裝 Skill + MCP（Claude Code / Codex / 任何 MCP client）
2npx -y firecrawl-cli@latest init --all --browser

方式 D：CLI

1# 直接使用 CLI
2npx firecrawl-cli search "firecrawl"
3npx firecrawl-cli scrape https://example.com

3. 核心架構解析

3.1 系統架構總覽

flowchart TD
    Client["Client（SDK / CLI / MCP / Agent）"] --> API["API Server
TypeScript / Node.js"]
    API --> Queue["RabbitMQ
Job Queue"]
    Queue --> Worker["Worker
Scrape / Crawl / Extract"]
    Worker --> PW["Playwright Service
JS Rendering + Actions"]
    Worker --> Proxy["Proxy Pool
IP Rotation"]
    API --> Redis["Redis
Rate Limit + Cache"]
    API --> PG["NuQ-PostgreSQL
Job State + Auth"]
    Worker --> Output["Output Formats"]
    Output --> MD["Markdown"]
    Output --> JSON["Structured JSON"]
    Output --> SS["Screenshot"]
    Output --> HTML["Raw HTML"]

3.2 API Endpoint 資料流

flowchart LR
    A[使用者請求] --> B{Endpoint?}
    B -->|/v2/search| C[Web Search
SearXNG]
    B -->|/v2/scrape| D[Single Page
Scrape + Actions]
    B -->|/v2/agent| E[AI Agent
Spark Model]
    B -->|/v2/crawl| F[Site Crawl
BFS/DFS]
    B -->|/v2/map| G[URL Discovery
Sitemap + Links]
    B -->|/v2/batch/scrape| H[Multi-URL
Parallel Scrape]
    C --> I[Clean Markdown
+ Metadata]
    D --> I
    E --> I
    F --> I
    G --> J[URL List]
    H --> I

3.3 Self-Host Docker Compose 元件

4. 核心功能詳解

4.1 Search — 搜尋 web

1from firecrawl import Firecrawl
2
3app = Firecrawl(api_key="fc-YOUR_API_KEY")
4results = app.search("firecrawl web scraping", limit=5)
5
6for r in results:
7    print(f"{r['title']}: {r['url']}")
8    print(r['markdown'][:200])

4.2 Scrape — 抓取單一頁面

1result = app.scrape("https://firecrawl.dev", formats=["markdown"])
2print(result.markdown)

支援的 format（格式）：

• markdown — 乾淨 Markdown（預設）
• html — 原始 HTML
• rawHtml — 未處理的 HTML
• screenshot — 頁面截圖
• links — 頁面上所有連結
• extract — AI 結構化提取

4.3 Interact — 網頁互動操作

在抓取前先執行操作（click / scroll / type / wait / screenshot）：

1result = app.scrape("https://example.com/login", actions=[
2    {"type": "wait", "milliseconds": 2000},
3    {"type": "click", "selector": "#accept-cookies"},
4    {"type": "write", "selector": "#search-input", "text": "firecrawl"},
5    {"type": "click", "selector": "#search-button"},
6    {"type": "wait", "milliseconds": 3000},
7    {"type": "scrape"}
8])

4.4 Agent — AI 自主資料收集

最強大的功能 — 描述需求，AI 自動搜尋、導航、提取：

 1# 基本用法
 2result = app.agent(prompt="Find the pricing plans for Notion")
 3print(result.data)
 4
 5# 帶 schema 的結構化輸出
 6from pydantic import BaseModel, Field
 7from typing import List, Optional
 8
 9class Founder(BaseModel):
10    name: str = Field(description="Full name")
11    role: Optional[str] = Field(None, description="Role or position")
12
13class FoundersSchema(BaseModel):
14    founders: List[Founder]
15
16result = app.agent(
17    prompt="Find the founders of Firecrawl",
18    schema=FoundersSchema
19)

Agent Model 選擇：

4.5 Crawl — 整站爬取

1docs = app.crawl("https://docs.firecrawl.dev", limit=50)
2for doc in docs.data:
3    print(doc.metadata.source_url, doc.markdown[:100])

4.6 Map — URL 發現

1links = app.map("https://firecrawl.dev")
2print(f"Found {len(links)} URLs")

4.7 Batch Scrape — 批次抓取

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

5. 應用場景

場景 A：AI Agent 的 Web 資料層

Firecrawl 最常見的使用場景是作為 AI agent 的「眼睛」— 讓 agent 能看到和理解 web 內容。透過 MCP 或 Agent Skill 一行接入：

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

接入後 agent 可直接呼叫 search、scrape、crawl 等功能。

場景 B：知識庫建構

用 Crawl 整站爬取文件網站，轉成 Markdown 後建構 RAG（Retrieval-Augmented Generation）知識庫：

1docs = app.crawl("https://docs.example.com", limit=500)
2for doc in docs.data:
3    save_to_vector_db(doc.markdown, metadata=doc.metadata)

場景 C：競品監控與市場研究

用 Agent endpoint 自動收集競品資訊：

1result = app.agent(
2    prompt="Compare enterprise features across Firecrawl, Apify, and ScrapingBee",
3    model="spark-1-pro"
4)

場景 D：網站變更監控

Firecrawl 提供 Monitor 功能，可偵測頁面內容變更並觸發 webhook。

場景 E：自動化資料提取

用 structured extraction 從網頁中提取結構化資料（如價格、聯絡資訊、產品規格），取代人工複製。

6. 資安掃描報告

掃描範圍

掃描結論

🟡 中風險 — 這是一個 web scraping 工具，本質上需要進行大量網路請求。需注意的項目：

1. AGPL-3.0 License — 若修改後用於 SaaS 服務，需開源修改部分
2. Self-host 環境變數 — docker-compose.yaml 列出大量環境變數（Redis / PostgreSQL / Proxy / API key），部署時需妥善管理
3. Proxy 設定 — Self-host 需自行設定 proxy，否則可能暴露伺服器 IP
4. Fire-engine 限制 — Self-host 無法使用 Fire-engine（進階反偵測功能），僅限 fetch + Playwright
5. Agent 模式 — Agent endpoint 讓 AI 自主瀏覽 web，需注意 credit 消耗與 scope 控制

Self-Host 安全建議

• 設定 USE_DB_AUTHENTICATION=true 啟用認證
• 不要在 production 使用預設 PostgreSQL 密碼
• 設定防火牆限制 API port 存取
• 定期更新容器映像

7. FAQ

Q1：Firecrawl 跟 Puppeteer / Playwright / Selenium 有什麼不同？

A： Firecrawl 是更高層次的抽象。Puppeteer 等是 browser automation（瀏覽器自動化）工具，你需要自己處理 proxy、rate limit、anti-bot、JS rendering、output parsing。Firecrawl 把這些全部封裝成 API，直接輸出乾淨的 Markdown / JSON。

Q2：Self-host 和雲端版有什麼差異？

A： Self-host 是免費的 AGPL-3.0 版本，但無法使用 Fire-engine（進階反偵測、IP rotation 等）。雲端版包含 Fire-engine + managed proxy pool + 更高的可靠性。Self-host 適合內部使用、資料敏感場景；雲端版適合需要高覆蓋率的 production 用途。

Q3：支援哪些 SDK？

A： 8 個官方 SDK：Python、Node.js、Java、Rust、Go（社群）、Ruby、PHP、Elixir、.NET。全部支援 Search / Scrape / Crawl / Agent 等核心功能，且自動處理 async polling。

Q4：Agent endpoint 的 credit 怎麼計算？

A： Agent 使用 Spark model（spark-1-mini 或 spark-1-pro）。spark-1-mini 比 spark-1-pro 便宜 60%，適合大多數任務。credit 根據 model 使用量 + scrape 次數計算。

Q5：可以抓取需要登入的頁面嗎？

A： 可以。使用 Interact 功能的 actions 參數，可以在抓取前執行 click / type / wait 等操作來完成登入流程。

8. 進階技巧

8.1 Scrape 搭配 Actions 抓取 SPA

對於 Single Page Application（SPA）或需要 JavaScript 互動的頁面：

1result = app.scrape("https://example.com/dashboard", actions=[
2    {"type": "wait", "milliseconds": 3000},
3    {"type": "scroll", "direction": "down", "amount": 3},
4    {"type": "screenshot"},
5    {"type": "scrape"}
6])

8.2 MCP + Claude Code 整合

在 Claude Code 中加入 Firecrawl MCP：

 1{
 2  "mcpServers": {
 3    "firecrawl-mcp": {
 4      "command": "npx",
 5      "args": ["-y", "firecrawl-mcp"],
 6      "env": {
 7        "FIRECRAWL_API_KEY": "fc-YOUR_API_KEY"
 8      }
 9    }
10  }
11}

8.3 Self-Host 性能調校

1# .env 調校參數
2NUM_WORKERS_PER_QUEUE=16      # 每個 queue 的 worker 數
3CRAWL_CONCURRENT_REQUESTS=20  # 並行爬取請求數
4MAX_CONCURRENT_JOBS=10        # 最大並行 job 數
5BROWSER_POOL_SIZE=10          # Playwright 瀏覽器池大小

8.4 Kubernetes 部署

Firecrawl 支援 Kubernetes 部署，examples/kubernetes/ 目錄有範例，也支援 Helm chart。

9. 整合進其他工作流

與 AI Agent 框架整合

Firecrawl 已與主要 AI 工具整合：

與 RAG Pipeline 整合

1# Crawl → Vector DB → RAG
2docs = app.crawl("https://docs.company.com", limit=200)
3for doc in docs.data:
4    chunks = split_markdown(doc.markdown)
5    embeddings = embed(chunks)
6    vector_db.upsert(embeddings, metadata=doc.metadata)

與本知識管理系統整合

Firecrawl 的 Markdown 輸出可直接進入 AI-knowledge_template 的 inbox/，再走 quarkdown / graphify / paper-qa-lite 等 layer 進一步處理。

10. 重點摘要 Checklist

• 理解定位：Firecrawl = Web Data API（不只是 scraper）
• 掌握 7 大能力：Search / Scrape / Interact / Agent / Crawl / Map / Batch
• 選擇部署方式：雲端 API（快速）vs Self-Host（資料控制）
• SDK 選擇：8 個官方 SDK，自動處理 async polling
• Agent endpoint：最強大的功能，描述需求即可自動完成
• MCP 整合：一行接入 Claude Code / 任何 MCP client
• Self-Host 安全：啟用認證、管理環境變數、設定 proxy
• License 注意：AGPL-3.0，修改後的 SaaS 服務需開源
• Actions 功能：click / scroll / type / wait → 處理 SPA 和登入頁
• Monitor 功能：頁面變更監控 + webhook

11. 進一步閱讀

官方資源

• Documentation
• API Reference
• Playground
• Changelog
• Self-Host Guide

SDK 文件

• Python SDK
• Node.js SDK
• Java SDK
• Rust SDK
• CLI Documentation

整合

• Firecrawl MCP Server
• Firecrawl Workflows
• 50+ Examples

社群

• Discord
• Twitter/X