unclecode/crawl4ai · 上手攻略

仓库：unclecode/crawl4ai
链接：https://github.com/unclecode/crawl4ai
分类：数据采集 / RAG / AI 工程工具
作者：Tom
更新：2026-08-17

这是什么

Crawl4AI 是 GitHub Star 数最多的开源网页爬虫（75,960 ★，数据截至 2026-08-17），专为将网页转化为 LLM 可直接消费的 Markdown 而设计。相比传统爬虫输出 HTML 碎片，Crawl4AI 输出结构清晰、噪音少、带引用标注的 Markdown，特别适合 RAG pipeline、Agent 数据摄取和大规模数据采集。

核心特点： - LLM ready output：智能 Markdown，保留标题、表格、代码块、引用关系 - 自适应爬取：自动判断"何时停止"，不盲目抓全站 - 零门槛：pip 安装，CLI 开箱即用，不需要 API Key - 安全加固：v0.8.0+ 后 Hooks 默认关闭，file:// URL 在 Docker API 层被屏蔽，反序列化 RCE 漏洞已修复

⚠️ GitHub README 标记最新版本为 v0.9.2，官方文档博客标记 v0.8.5（2026-03）为最新稳定版，两者可能存在发布节奏差异。

解决什么问题

传统爬虫方案面临三重困境： 1. 输出不友好：抓回来的是 HTML 碎片，需要额外清洗才能喂给 LLM 2. Bot 检测严：Cloudflare、Akamai 等动不动封 IP，全靠代理池硬抗 3. 成本高：第三方爬虫服务按请求计费，大规模采集费用惊人

Crawl4AI 用浏览器级别的爬取引擎 + LLM 友好的输出格式 + 完全本地化的方案一次性解决。

快速安装

pip 安装（推荐）

# 安装核心包
pip install -U crawl4ai

# 安装 pre-release 版本（最新特性）
pip install crawl4ai --pre

# 运行安装引导（下载 Playwright 浏览器等）
crawl4ai-setup

# 验证安装
crawl4ai-doctor

# 如遇浏览器问题，手动安装 Playwright Chromium：
python -m playwright install --with-deps chromium

Docker 安装（无需本地 Python 环境）

# 拉取最新镜像
docker pull unclecode/crawl4ai:latest

# 运行交互式爬虫
docker run -it unclecode/crawl4ai:latest crawl4ai

# 或者用 Docker 运行单次爬取
docker run --rm -v $(pwd):/data unclecode/crawl4ai:latest \
  crawl4ai https://example.com -o markdown

CLI 快速使用

# 基本爬取，输出 Markdown
crwl https://www.nbcnews.com/business -o markdown

# 深度爬取（广度优先，最多 10 页）
crwl https://docs.crawl4ai.com --deep-crawl bfs --max-pages 10

# 用 LLM 提取特定信息
crwl https://www.example.com/products -q "Extract all product prices"

核心用法

Python API：基本爬取

import asyncio
from crawl4ai import AsyncWebCrawler

async def main():
    async with AsyncWebCrawler() as crawler:
        result = await crawler.arun(url="https://www.nbcnews.com/business")
        print(result.markdown)          # 干净 Markdown
        print(result.html)              # 原始 HTML
        print(result.links)             # 页面链接
        print(result.metadata)          # 元数据

asyncio.run(main())

Python API：LLM 驱动的结构化提取

import asyncio
from crawl4ai import AsyncWebCrawler

async def main():
    async with AsyncWebCrawler(verbose=True) as crawler:
        result = await crawler.arun(
            url="https://www.example.com/products",
            llm_extraction=True,  # 启用 LLM 提取
            extraction_prompt="Extract all product names, prices, and ratings",
            extraction_type="json"
        )
        print(result.extracted_content)  # 结构化 JSON

asyncio.run(main())

Python API：深度爬取 + 断点恢复

import asyncio
from crawl4ai import AsyncWebCrawler

async def main():
    async with AsyncWebCrawler() as crawler:
        # 深度爬取，自动探索相关链接
        result = await crawler.arun(
            url="https://docs.crawl4ai.com",
            deep_crawl=True,
            max_pages=50,
            # 断点恢复：从上次状态继续（crash-safe）
            resume_state=True,
            on_state_change=lambda state: print(f"Visited: {len(state.visited)} pages")
        )
        print(f"Total pages: {len(result.visited)}")
        print(result.markdown)

自定义 CSS/XPath 提取

async with AsyncWebCrawler() as crawler:
    result = await crawler.arun(
        url="https://news.ycombinator.com/",
        css_selector=".titleline",      # 提取特定元素
        bypass_cache=True,
        session_id="hacker-news-session"
    )

代理配置

async with AsyncWebCrawler(
    proxy="http://username:password@proxy.example.com:8080"
) as crawler:
    result = await crawler.arun(url="https://example.com")

典型适用场景

RAG Pipeline 数据摄取：直接爬取网页 → Markdown → 向量数据库，省去 HTML 清洗步骤
Agent 工具：LLM 需要实时查询网页信息，作为 tool_call 接入 Agent
大规模舆情监控：自适应爬取 + 并发控制，抓取数百个新闻源
学术数据采集：抓取 arXiv、PubMed 等论文页面，提取结构化信息
竞品分析：抓取多个电商/产品页面，提取价格、评价等结构化数据
Deep Research：与 DeepResearch_AI 等工具配合，提供可信的网络信息来源

坑与注意

坑	说明
v0.9.2 vs v0.8.5 版本混乱	⚠️ GitHub README 标记 v0.9.2，官方文档博客标记 v0.8.5（2026-03）最新；以 GitHub Releases 为准
Playwright 浏览器依赖	首次运行需下载 Chromium，`crawl4ai-setup` 或手动 `playwright install --with-deps`
Docker 安全默认值	v0.9.0+ Docker API 默认开启认证，不绑定公网端口；生产环境部署务必检查安全配置
内存占用	深度爬取大量页面时内存消耗较大，注意 `MemoryAdaptiveDispatcher` 在 v0.9.2 前的 leak 问题（已修复）
反爬虫网站	虽然有 anti-bot 检测 + 代理支持，但强反爬网站（Cloudflare 高级版等）仍有概率失败
冷启动慢	首次爬取需要启动 Playwright 浏览器，约 3-5 秒，后续请求复用浏览器池
LLM 提取成本	开启 `llm_extraction=True` 会额外消耗 LLM token，页面多时费用需注意

与同类对比

项目	输出格式	LLM 友好度	API Key	Bot 检测对抗	适用规模
Crawl4AI	Markdown + HTML + JSON	⭐⭐⭐⭐⭐	不需要	⭐⭐⭐⭐	中大型
Firecrawl	Markdown	⭐⭐⭐⭐	需要	⭐⭐⭐⭐	中型
ScrapeGraphAI	Markdown	⭐⭐⭐⭐	可选	⭐⭐⭐	中型
Playwright + 手动解析	HTML	⭐⭐	不需要	⭐⭐	小型
第三方爬虫 API（Jina 等）	Markdown	⭐⭐⭐⭐	需要	⭐⭐⭐⭐	按需

Crawl4AI 的核心优势是完全本地化 + LLM 原生输出 + 零 API 成本，在 75k+ Stars 的社区验证下稳定性有保障，是目前开源爬虫领域的事实标准。

一句话推荐结论

需要将网页内容喂给 LLM（无论是 RAG、Agent 还是数据管道），Crawl4AI 是目前最省心、性能最强、零成本的方案；重度生产级部署建议用 Docker + 认证 + 代理池，并关注 GitHub Releases 的最新版本。