在这里插入代码片> 调研对象：unclecode/crawl4ai — 开源 LLM 友好的网页爬虫与抓取库

调研时间：2026-08-12 | 整理：Hermes Agent
数据来源：GitHub REST API（api.github.com/repos/unclecode/crawl4ai，实时抓取）、官方文档 docs.crawl4ai.com（40+ 页面）、项目 README（v0.9.2）

目录

  1. 项目概述
  2. 核心功能
  3. 架构原理
  4. 安装与使用
  5. 与 Scrapling / Playwright 的核心差异对比
  6. 优缺点与适用场景
  7. 数据来源

1. 项目概述

1.1 项目速览

维度 数据（2026-08-12 实时抓取）
GitHub Stars ⭐ 77,878（GitHub 上星标最多的开源爬虫之一）
GitHub Forks 8,057
编程语言 Python（Python >= 3.10）
许可证 Apache-2.0（完全开源，仅要求署名）
创建时间 2024-05-09
最后推送 2026-08-11（活跃维护，几乎每日提交）
Open Issues 143（相对 77.8K stars 而言极少）
Watchers 403
仓库体积 约 150 MB
官网 https://crawl4ai.com
最新版本 v0.9.2（2026-07-15）
定位 把网页变成干净、LLM 就绪的 Markdown，服务 RAG / AI Agent / 数据管道

一句话定位：Crawl4AI 是「以 LLM 消费为目标」的开源网页爬虫——它不满足于拿到 HTML，而是直接产出干净的 Markdown（含原始版 raw 与去噪版 fit 两种），并内置 CSS/XPath/LLM 三种结构化提取管线，帮助 RAG、Agent 与数据管道直接使用抓取结果。

1.2 版本演进

Crawl4AI 采用 MAJOR.MINOR.PATCH（PEP 440）版本号，自 2024 年 5 月发布以来迭代极快，半年内从 0.4 冲到 0.9：

版本 发布时间 里程碑内容
v0.4.x 2024 中 早期版本：AsyncWebCrawler 雏形、基础 Markdown 生成
v0.5.0 2024 末 缓存系统重构：废弃 4 个布尔开关（bypass_cache 等），引入 CacheMode 枚举（ENABLED/DISABLED/READ_ONLY/WRITE_ONLY/BYPASS）
v0.6.0 2025 初 提取与分块策略体系成型（Chunking、CosineStrategy）
v0.7.0 2025 中 自适应智能更新：AdaptiveCrawler、虚拟滚动 VirtualScroll、链接智能评分、AsyncUrlSeeder
v0.7.3 2025 Undetected Browser 支持（绕过 Cloudflare/Akamai）、多 URL 差异化配置、内存监控
v0.7.4 2025 LLMTableExtraction 智能表格提取、调度器并发修复
v0.7.5 2025 Docker Hooks 系统：8 个关键节点可注入 Python 函数、函数式 Hooks API
v0.7.7 2025-11-14 自托管与监控：实时监控面板、WebSocket 流式、三级浏览器池（permanent/hot/cold）
v0.7.8 2025-12-09 稳定性修复：LLM 提取限流退避、HTML 输入格式、URL 处理修复
v0.8.0 2026-01-16 崩溃恢复 + Prefetch 模式：deep crawl resume_state 断点续爬、prefetch=True 提速 5-10 倍
v0.8.5 2026-03-18 反爬检测与代理升级链、Shadow DOM 展平、deep crawl 取消、60+ bug 修复
v0.8.6 2026 安全热修复：因 PyPI 供应链投毒事件将 litellm 依赖替换为 unclecode-litellm
v0.8.7 2026-06-01 安全加固：修复 Docker API 多个 RCE/SSRF/认证绕过漏洞、新增 DomainMapper（域名全量 URL 发现）
v0.9.0 2026-06-18 Docker 服务默认安全：默认开启认证、默认回环绑定
v0.9.1 2026-07-08 PruningContentFilter 白名单（preserve_classes/preserve_tags）、12 个 bug 修复
v0.9.2 2026-07-15 维护版：MemoryAdaptiveDispatcher 流式爬取内存泄漏修复、GPU Docker 构建修复

演进主线：底层引擎稳定（Playwright + asyncio）→ 上层能力不断外扩：缓存枚举化 → 提取策略化 → 反爬/身份体系 → 深度爬取工程化（断点续爬/取消/prefetch）→ 安全与部署（Docker 默认安全、监控面板）。

1.3 社区与生态

  • 社区规模：Discord、X（@crawl4ai）、GitHub Sponsors 四档赞助（$5~$2000/月），战略伙伴含 Massive（全球代理网络）等；
  • Crawl4AI Cloud API：官方云服务 Closed Beta 中（主打"远低于现有方案的提取成本"），开源版仍完全免费；
  • 周边工具：crwl CLI、C4A-Script（声明式爬取脚本语言）、Docker 服务（监控面板 + Playground + MCP 集成）、Ask AI 文档问答。

2. 核心功能

2.1 LLM 友好的 Markdown 输出

这是 Crawl4AI 的立身之本。它不返回"一坨 HTML"，而是分三层产出：

输出 说明
result.markdown.raw_markdown 完整转换的 Markdown（保留标题、代码块、表格、列表）
result.markdown.fit_markdown 去噪版 Markdown：经内容过滤器（Pruning/BM25）修剪后的"核心内容"，专供 LLM
引用/参考列表 链接自动转为 [text][1] 引用编号，文末附参考链接表（适合研究类工作流）

转换内核是自研/改造的 html2text 类转换器（README 描述为 forked & modified），支持 ignore_links、ignore_images、escape_html、body_width、skip_internal_links、include_sup_sub 等细粒度选项，并可通过 content_source 选择转换输入源：raw_html（原始 HTML）/ cleaned_html（默认，清洗后）/ fit_html（过滤后）。

配合内容过滤器（见 3.4），可产出面向查询的精准内容：

from crawl4ai import AsyncWebCrawler, CrawlerRunConfig, CacheMode
from crawl4ai.markdown_generation_strategy import DefaultMarkdownGenerator
from crawl4ai.content_filter_strategy import BM25ContentFilter

config = CrawlerRunConfig(
    cache_mode=CacheMode.ENABLED,
    markdown_generator=DefaultMarkdownGenerator(
        content_filter=BM25ContentFilter(user_query="crawl4ai 架构", bm25_threshold=1.0)
    ),
)
async with AsyncWebCrawler() as crawler:
    result = await crawler.arun(url="https://docs.crawl4ai.com/", config=config)
    print(len(result.markdown.raw_markdown))  # 完整版
    print(len(result.markdown.fit_markdown))  # 去噪版

2.2 自适应抓取 AsyncWebCrawler

核心类是 AsyncWebCrawler（异步、基于 asyncio + Playwright）：

  • arun(url, config=...)：单 URL 抓取，返回 CrawlResult（含 html/cleaned_html/markdown/extracted_content/links/media/tables/screenshot/ssl_certificate 等）。
  • arun_many(urls, config=...)：批量抓取，支持调度器（Dispatcher）：
    • MemoryAdaptiveDispatcher（默认）：按内存/网络状况自适应并发；
    • SemaphoreDispatcher：固定信号量并发控制；
    • 可配 RateLimiter（速率限制）与 CrawlerMonitor（监控）。
  • 一次创建、多次复用：浏览器实例在 crawler 生命周期内复用，同一实例的缓存命中可达毫秒级（实测第二次抓取 0.08s vs 首次 2.1s，加速约 26x）。
  • URL 输入前缀：https:// 网页、file:// 本地文件、raw: 原始 HTML 字符串（无需浏览器，直接解析）。

2.3 多策略结构化提取

策略类 类型 适用场景 特点
JsonCssExtractionStrategy 无 LLM 结构化、重复模式（列表页） JSON schema 描述 baseSelector + fields，支持 nested/nested_list 嵌套，毫秒级
JsonXPathExtractionStrategy 无 LLM 同上但更适合 XPath 定位 与 CSS 版同 schema，仅 baseSelector 换 XPath 语法
RegexExtractionStrategy 无 LLM 快速模式匹配（邮箱/电话/价格） 内置常见实体模式，可 LLM 辅助生成自定义正则
LLMExtractionStrategy LLM 非结构化、需语义理解的内容 LiteLLM 接入任意模型，自动分块合并（详见 3.4）
CosineStrategy 无 LLM 按查询语义召回相关块 TF-IDF + 余弦相似度对 chunk 打分（需 sklearn）
LLMTableExtraction LLM 巨型/复杂表格 智能分块（chunk_token_threshold/overlap_threshold），分块处理再合并

CSS 无 LLM 提取示例：

from crawl4ai import AsyncWebCrawler, CrawlerRunConfig, JsonCssExtractionStrategy
import json

schema = {
    "name": "Crypto Prices",
    "baseSelector": "div.crypto-row",          # 重复元素
    "fields": [
        {"name": "coin", "selector": "h2", "type": "text"},
        {"name": "price", "selector": ".price", "type": "text"},
    ],
}
config = CrawlerRunConfig(extraction_strategy=JsonCssExtractionStrategy(schema))
async with AsyncWebCrawler() as crawler:
    result = await crawler.arun("https://example.com/prices", config=config)
    print(json.loads(result.extracted_content))  # [{coin, price}, ...]

2.4 动态页面 Playwright 集成

Playwright 是底层渲染引擎，Crawl4AI 在其上封装了完整的动态页面处理能力：

  • JS 执行：js_code=["..."] 按序执行任意 JS（点击 Tab、展开折叠）；等待条件：wait_for="css:.loaded" 或 JS 表达式；
  • 滚动加载：scan_full_page=True 全页滚动、VirtualScrollConfig 处理虚拟滚动列表（如 Twitter 时间线）；
  • Shadow DOM 展平（flatten_shadow_dom=True）、iframe 处理（process_iframes=True）、懒加载图片（wait_for_images）；
  • Hooks 钩子：on_page_context_created / before_goto / after_goto / before_retrieve_html 等 8+ 个生命周期节点可注入自定义 Python 函数（如拦截图片请求加速）；
  • 会话管理：session_id 复用浏览器上下文，配合 storage_state 持久化登录态，支持多步爬取（登录 → 操作 → 抓取）。

2.5 深度爬取 DeepCrawl

在 CrawlerRunConfig 中挂 deep_crawl_strategy 即可从单页升级为整站爬取：

策略 遍历方式 适用场景
BFSDeepCrawlStrategy 广度优先 全面覆盖（默认推荐入门）
DFSDeepCrawlStrategy 深度优先 分支深入的站点
BestFirstCrawlingStrategy ⭐ 评分优先 官方推荐：按 url_scorer 打分优先爬最相关页面，如 KeywordRelevanceScorer(keywords=[...])

工程化能力（v0.8.0 起）：

  • FilterChain 过滤链：URLPatternFilter、DomainFilter、ContentTypeFilter、ContentRelevanceFilter 等组合使用，只爬目标 URL 模式；
  • 流式/非流式：stream=True 边爬边出结果（配合 on_state_change 回调），默认收集完统一返回；
  • 崩溃恢复：resume_state + on_state_change 断点续爬（状态 JSON 可存 Redis/数据库），适合长任务；
  • 取消：cancel() 或 should_cancel 回调优雅停止；
  • Prefetch 模式：prefetch=True 只发现 URL（跳过 Markdown/提取/媒体处理），URL 发现提速 5-10x，配合两阶段"先发现、后精抓"。
from crawl4ai import AsyncWebCrawler, CrawlerRunConfig
from crawl4ai.deep_crawling import BestFirstCrawlingStrategy
from crawl4ai.deep_crawling.scorers import KeywordRelevanceScorer

config = CrawlerRunConfig(
    deep_crawl_strategy=BestFirstCrawlingStrategy(
        max_depth=3,
        max_pages=50,
        url_scorer=KeywordRelevanceScorer(keywords=["python", "tutorial"], weight=0.7),
    ),
)
async with AsyncWebCrawler() as crawler:
    results = await crawler.arun("https://example.com", config=config)
    print(f"共爬取 {len(results)} 页")

2.6 缓存

v0.5.0 起用 CacheMode 枚举统一控制（取代旧的 bypass_cache 布尔参数）：

模式 行为 典型用途
CacheMode.ENABLED 正常读写缓存 默认，重复抓取加速
CacheMode.DISABLED 完全不用缓存 需要绝对新鲜的数据
CacheMode.READ_ONLY 只读缓存，不写 回放历史抓取
CacheMode.WRITE_ONLY 只写缓存，不读 预热缓存
CacheMode.BYPASS 本次请求跳过缓存 单次强制刷新（README 示例常用）

缓存按 URL 键控，位于 crawler 的 base_directory；缓存是实例级/目录级——复用同一 AsyncWebCrawler 实例时二次抓取可达到 0.07~0.08s 的极速（实测 26x 加速，见 crawl4ai_smart_scraper 项目实测）。

2.7 代理支持

  • 配置方式：CrawlerRunConfig(proxy_config=ProxyConfig(...)) 请求级配置（官方推荐，便于轮换），也支持 dict 与纯字符串；
  • 格式：ProxyConfig.from_string() 支持 HTTP/HTTPS/SOCKS5、user:pass@host:port、ip:port:user:pass 等多种格式；
  • 认证：ProxyConfig(server=..., username=..., password=...)；
  • 环境变量：PROXIES="ip1:port1:user1:pass1,ip2:port2,..." + ProxyConfig.from_env() 批量加载；
  • 轮换策略：RoundRobinProxyStrategy(proxies) 挂到 proxy_rotation_strategy，每请求自动轮换 IP；
  • 反爬升级链：proxy_config 可传代理列表（含 ProxyConfig.DIRECT 直连占位），配合 max_retries 与 fallback_fetch_function 实现"直连 → 代理1 → 代理2 → 备用抓取函数"的自动升级（见 3.5）；
  • SSL 证书分析：fetch_ssl_certificate=True 可抓取并导出证书（issuer/subject/有效期/指纹），用于安全审计。

2.8 Chunking 分块策略

分块是 LLM 提取与语义检索的基石，Crawl4AI 提供 5 种内置策略（crawl4ai.chunking_strategy）：

策略 切分逻辑 适用
RegexChunking 正则切分（默认按 \n\n 段落） 粗粒度快速切分
NlpSentenceChunking NLTK 句子级切分 提取完整语句
TopicSegmentationChunking TextTiling 主题分段 主题连贯的章节
FixedLengthWordChunking 固定词数切块 简单均匀切分
SlidingWindowChunking 滑窗 + 重叠（window_size/step） 保持上下文连贯性

分块后可与 CosineStrategy 组合做"按查询取相关块"的语义提取；在 LLM 管线中则由 chunk_token_threshold + overlap_rate 自动控制（见 3.4）。设计上直接对接 RAG：分块 → 向量化 → 检索。

3. 架构原理

3.1 总体架构

用户代码 (Python / CLI / Docker API)
   │
AsyncWebCrawler (asyncio 编排核心)
   ├─ arun() 单页抓取
   ├─ arun_many() + Dispatcher (内存自适应/信号量)
   └─ DeepCrawl (BFS / DFS / BestFirst + FilterChain + Scorer)
   │
   └─ 浏览器层: Playwright 无头 / 托管浏览器(CDP) / 系统浏览器
      BrowserProfiler 身份档案 · Hooks 钩子 · 会话/代理/反爬
   │
内容处理管线 (Pipeline)
   ① ScrapingStrategy (LXML) 清洗 HTML
   ② content_filter 过滤 (Pruning / BM25 / LLM) → fit_html / fit_markdown
   ③ DefaultMarkdownGenerator → raw / fit markdown
   ④ Chunking 分块 → ⑤ ExtractionStrategy (JsonCss / JsonXPath / Regex / LLM / Cosine)

3.2 Crawler 生命周期

创建 BrowserConfig（浏览器级配置，全局一次）
   ↓
创建 AsyncWebCrawler(config=browser_config)
   ↓
start()  ── 启动 Playwright 浏览器（首次约 1.5~2.5s）
   ↓
arun(url, config=CrawlerRunConfig)  × N 次   ← 每次抓取独立配置
   ├─ 1. 查缓存 → 命中则直接返回
   ├─ 2. 浏览器加载页面（goto）→ 等待条件 → 执行 js_code → 滚动
   ├─ 3. 抓取 HTML → LXML 清洗 → Markdown 生成 → 过滤 → 提取
   └─ 4. 写缓存 → 返回 CrawlResult
   ↓
close() ── 关闭浏览器、释放资源（async with 自动完成）

要点：

  • 推荐 async with AsyncWebCrawler(...) as crawler:，上下文管理器自动 start/close；
  • 长驻进程可用手动 await crawler.start() / await crawler.close()；
  • 浏览器级配置（BrowserConfig）与运行级配置（CrawlerRunConfig）分离：一个 crawler 实例可对不同 URL 使用不同 run 配置（甚至 URL 匹配器自动选配置）；
  • 核心参数：browser_type（chromium/firefox/webkit）、headless、browser_mode（dedicated/builtin/custom/docker）、use_managed_browser、cdp_url、viewport、text_mode（纯文本加速）、light_mode（轻量启动）、enable_stealth。

3.3 双爬虫模式：Playwright 无头 vs 系统/托管浏览器

Crawl4AI 支持两条浏览器路线，这是它区别于普通 Playwright 封装的关键设计：

维度 内置 Playwright 无头浏览器 托管浏览器 / 系统浏览器（Managed Browser）
浏览器来源 自装 Chromium（crawl4ai-setup） 用户自己的 Chrome/Edge 用户数据目录
身份 全新匿名档案，无任何登录态 真实用户身份：保留 cookies/localStorage/登录态
启动方式 browser_type="chromium", headless=True use_managed_browser=True + user_data_dir=...
外部控制 无 可连 CDP：cdp_url="ws://localhost:9222/devtools/browser/"（browser_mode="custom"）
反爬表现 易被检测（需 stealth/magic 辅助） 最接近真人，登录墙网站（如私域后台）直接通过
适用 通用抓取、无需登录 登录后才能访问的内容、强反爬站点

身份档案管理（BrowserProfiler）：

from crawl4ai import BrowserProfiler

profiler = BrowserProfiler()
# 交互式创建档案：弹出浏览器窗口，手动登录后按 q 保存
profile_path = await profiler.create_profile(profile_name="my-login-profile")
# 支持列出/删除档案，档案存于 ~/.crawl4ai/profiles/<name>/

或用 CLI 交互式管理：crwl profiles → “Create new profile” → 登录 → 保存。之后：

browser_config = BrowserConfig(
    headless=True,
    use_managed_browser=True,
    user_data_dir="/home/you/.crawl4ai/profiles/my-login-profile",
)

Magic 模式（轻量替代）：CrawlerRunConfig(magic=True) 一行开启——随机化 User-Agent/navigator、随机化交互与时间、掩盖自动化特征、自动处理弹窗。适合不想维护档案的简单反爬场景；但官方明确指出它不是真实身份，复杂登录场景仍应使用托管浏览器。

Stealth 与 Undetected：

  • enable_stealth=True：基于 playwright-stealth 修改浏览器指纹（WebGL/UA/权限 API 等）；
  • UndetectedAdapter()：更强反检测的浏览器适配器，可 enable_stealth=True 叠加使用；
  • 官方推荐"渐进增强"：普通浏览器 + stealth → 仍被拦截再上 undetected → 最终托管浏览器真实身份。

3.4 LLM 提取管线：content filtering → chunking → extraction strategy

LLM 提取不是"把整页塞给模型"，而是经过一条完整管线：

抓取的 HTML / Markdown
   │
   ▼ ① Content Filtering（可选，先瘦身）
PruningContentFilter（启发式密度修剪，无需查询词）
  或 BM25ContentFilter（按 user_query 相关性排名，bm25_threshold 过滤）
  或 LLMContentFilter（LLM 摘要式过滤）
   │  → fit_markdown
   ▼ ② Chunking（超长内容自动分块）
chunk_token_threshold（如 1200 tokens）+ overlap_rate（如 0.1 重叠）
   │
   ▼ ③ LLM Inference（每块独立推理）
LLMExtractionStrategy(llm_config=LLMConfig(provider="openai/gpt-4o", ...),
                      schema=PydanticModel.model_json_schema(),
                      extraction_type="schema" | "block",
                      instruction="...")
   │  并行/顺序调用 LiteLLM 支持的任意模型（OpenAI/Claude/Ollama/...）
   ▼ ④ Combining（合并各块结果 → JSON）
result.extracted_content

关键参数：

  • input_format：喂给 LLM 的内容格式——markdown（默认）/ fit_markdown（先用过滤器瘦身再提取，省 token）/ html；
  • extraction_type="schema"：按 Pydantic schema 输出严格 JSON；"block"：自由文本/小块 JSON 收集；
  • chunk_token_threshold + overlap_rate：控制分块大小与上下文重叠，apply_chunking=True 自动开启；
  • 限流退避：LLMConfig(backoff_base_delay=5, backoff_max_attempts=5, backoff_exponential_factor=3)（v0.7.8 起）；
  • show_usage()：打印每块 token 用量与成本。

官方建议：页面结构规整时优先用 JsonCss/JsonXPath（无 LLM），LLM 提取更慢更贵，留给非结构化/需语义理解的场景。

3.5 反爬降级链（Anti-Bot & Fallback）

v0.8.5 引入的三层检测 + 自动升级机制：

检测（3 层，基于结构特征而非关键词，降低误报）：
  ① 已知反爬厂商特征（Cloudflare/Akamai/DataDome/PerimeterX/Imperva）
  ② 通用拦截特征（403、验证码页面结构）
  ③ 页面结构完整性检查（关键内容缺失）

升级链 Escalation（每轮重试依次尝试所有代理）：
  第 1 轮: 直连（或 proxy_config[0]）
    ↓ 被拦截
  第 2 轮: proxy_config[1] → proxy_config[2] ...
    ↓ 全部代理用完仍被拦截
  最后手段: fallback_fetch_function(url)（自定义抓取函数，如第三方解锁服务）
  
总尝试次数 = (1 + max_retries) × len(proxy_config)

config = CrawlerRunConfig(
    proxy_config=[ProxyConfig.DIRECT, ProxyConfig(server="http://my-proxy:8080")],
    max_retries=2,
    fallback_fetch_function=my_web_unlocker,
)

每次尝试记录在 crawl_stats（proxy 用了哪个、状态码、拦截原因、由谁解决：direct/proxy/fallback_fetch），便于观测调优。

4. 安装与使用

4.1 安装

# 1) 安装 Python 包（默认异步版，基于 Playwright）
pip install -U crawl4ai

# 预发布版
pip install crawl4ai --pre

# 2) 安装浏览器（关键步骤！国内网络下载 Chromium 可能困难，见下方提示）
crawl4ai-setup

# 3) 验证安装
crawl4ai-doctor
  • 可选增强：pip install crawl4ai[torch]（余弦相似度/语义分块）、[transformer]（HF 摘要）、[cosine]、[all]；[sync]（Selenium 同步版，已废弃，未来移除）。
  • 浏览器手动安装兜底：python -m playwright install --with-deps chromium。
  • Docker 部署：docker pull unclecode/crawl4ai:latest && docker run -d -p 11235:11235 --shm-size=1g unclecode/crawl4ai:latest，自带监控面板（/dashboard）、Playground、MCP 集成，v0.9.0 起默认开启认证。

⚠️ 国内网络提示：Playwright Chromium 二进制下载困难时，可用纯 HTTP 直连模式跑通核心功能（raw markdown），系统检测到浏览器后自动升级为完整渲染模式。

4.2 CLI（crwl）

CLI 随库安装，无需额外配置：

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

# JSON 输出 + 绕过缓存 + 详细日志
crwl https://example.com -o json -v --bypass-cache

# 深度爬取：BFS 策略，最多 10 页
crwl https://docs.crawl4ai.com --deep-crawl bfs --max-pages 10

# LLM 提问式提取
crwl https://www.example.com/products -q "Extract all product prices"

# 结构化提取（CSS schema 文件 + 提取配置 YAML）
crwl "https://www.infoq.com/ai-ml-data-eng/" -e extract_css.yml -s css_schema.json -o json

# 浏览器/爬虫配置走 YAML
crwl https://example.com -B browser.yml -C crawler.yml

# 交互式浏览器档案管理
crwl profiles

CLI 配置支持 -B browser.yml（headless/viewport/user_agent_mode 等）、-C crawler.yml（cache_mode/wait_until/scan_full_page/magic 等）；首次 -q 会引导配置 LLM provider 与 token，存于 ~/.crawl4ai/global.yml。

4.3 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（字符串或对象，依版本）

asyncio.run(main())

② 完整配置（缓存 + Fit Markdown + JS 执行）：

import asyncio
from crawl4ai import AsyncWebCrawler, BrowserConfig, CrawlerRunConfig, CacheMode
from crawl4ai.markdown_generation_strategy import DefaultMarkdownGenerator
from crawl4ai.content_filter_strategy import PruningContentFilter

async def main():
    browser_config = BrowserConfig(headless=True, verbose=True)
    run_config = CrawlerRunConfig(
        cache_mode=CacheMode.ENABLED,
        excluded_tags=["nav", "footer", "header", "aside"],
        word_count_threshold=10,
        exclude_external_links=True,
        js_code=["window.scrollTo(0, document.body.scrollHeight);"],
        wait_for="css:main",
        markdown_generator=DefaultMarkdownGenerator(
            content_filter=PruningContentFilter(threshold=0.48, threshold_type="dynamic")
        ),
    )
    async with AsyncWebCrawler(config=browser_config) as crawler:
        result = await crawler.arun(url="https://example.com/docs", config=run_config)
        if result.success:
            print(result.markdown.fit_markdown[:2000])  # 去噪版，适合喂 LLM
        else:
            print("失败:", result.error_message)

asyncio.run(main())

③ LLM 结构化提取（Pydantic schema）：

import asyncio, os, json
from crawl4ai import AsyncWebCrawler, CrawlerRunConfig, CacheMode, LLMConfig, LLMExtractionStrategy
from pydantic import BaseModel, Field

class OpenAIModelFee(BaseModel):
    model_name: str = Field(..., description="模型名")
    input_fee: str = Field(..., description="输入 token 费用")

async def main():
    run_config = CrawlerRunConfig(
        word_count_threshold=1,
        extraction_strategy=LLMExtractionStrategy(
            llm_config=LLMConfig(provider="openai/gpt-4o", api_token=os.getenv("OPENAI_API_KEY")),
            schema=OpenAIModelFee.model_json_schema(),
            extraction_type="schema",
            instruction="从页面中提取所有模型名及输入费用",
        ),
        cache_mode=CacheMode.BYPASS,
    )
    async with AsyncWebCrawler() as crawler:
        result = await crawler.arun(url="https://openai.com/api/pricing/", config=run_config)
        print(result.extracted_content)

asyncio.run(main())

④ 深度爬取 + 断点续爬：

from crawl4ai import AsyncWebCrawler, CrawlerRunConfig
from crawl4ai.deep_crawling import BFSDeepCrawlStrategy

strategy = BFSDeepCrawlStrategy(
    max_depth=3,
    max_pages=50,
    resume_state=saved_state,          # 断点续爬
    on_state_change=save_to_redis,     # 每爬一页回调持久化
)
config = CrawlerRunConfig(deep_crawl_strategy=strategy, stream=True)
async with AsyncWebCrawler() as crawler:
    async for result in await crawler.arun("https://example.com", config=config):
        print(result.url, result.metadata.get("depth"))

4.4 项目集成参考

社区项目对 Crawl4AI 的实际落地封装，其设计值得参考：

  • 四层去噪模型（对应官方能力）：L1 HTML 层切除（excluded_tags + word_count_threshold + exclude_external_links）；L2 Fit 过滤（PruningContentFilter 启发式 / BM25ContentFilter 查询相关）；L3 自定义过滤器（继承 RelevantContentFilter 注入）；L4 结构化提取（JsonCssExtractionStrategy / LLMExtractionStrategy）；
  • 浏览器可用性探测：检查 ~/Library/Caches/ms-playwright/ 下是否有真实 chromium 可执行文件，有则走 Playwright 全链路，无则降级 urllib 纯 HTTP 直连（解决国内浏览器下载难题）；
  • 结果回退链：fit_markdown → raw_markdown → HTML 转文本，保证有内容返回；
  • 版本兼容处理：result.markdown 在旧版是字符串、新版是对象（含 .fit_markdown），代码做了 isinstance 双分支兼容。

5. 与 Scrapling / Playwright 的核心差异对比

详细三方对比见同目录 CRAWL4AI_VS_SCRAPLING_VS_FIRECRAWL.md；本节聚焦 Crawl4AI 与最常被拿来对比的两个库。

5.1 定位差异

维度 Crawl4AI Scrapling Playwright（裸用）
定位 LLM 友好爬虫框架（抓取+清洗+提取一体） 全栈自适应爬虫（HTTP 层反爬见长） 浏览器自动化 SDK（底层工具）
抽象层级 高层：一个 arun() 走完 抓取→Markdown→提取 中高层：Fetcher/StealthyFetcher + 解析器 低层：page.goto + 手写解析
输出形态 直接给 raw/fit Markdown + 结构化 JSON HTML + 手动/库内解析为文本 原始 HTML/DOM，需自建管道
LLM 集成 一等公民：LLMExtractionStrategy、LLM 过滤、LiteLLM 全模型 无内置 LLM 提取（可自行组合） 无
浏览器依赖 必须 Playwright 浏览器（可托管用户浏览器） 可选：底层用 curl_cffi（HTTP 层），不强制浏览器 本身就是浏览器驱动
反爬思路 Playwright 无头 + stealth/undetected + 托管浏览器身份 + 代理升级链 curl_cffi TLS 指纹（HTTP 层模拟 Chrome）+ stealthy_headers，速度快 需自己写 stealth 方案

5.2 关键能力对比表

能力 Crawl4AI Scrapling Playwright
Markdown 生成 ⭐⭐ 最强（raw/fit 双版、引用列表、BM25/Pruning 过滤） 一般（markdownify/html2text 手动接） ❌ 无，需第三方库
结构化提取 ⭐ CSS/XPath/Regex/LLM/Cosine 五策略 CSS Selector 手动（SmartPageFetcher 有选择器封装） ❌ 需自己写
动态页面渲染 ⭐ Playwright 封装（js_code/wait/scroll/hooks） 有 Dynamic/Stealth fetcher 但能力较薄 ⭐⭐ 最底层最灵活
批量/深度爬取 ⭐⭐ BFS/DFS/BestFirst + 调度器 + 断点续爬 无内置深爬 需自建
缓存 ⭐ 内置 CacheMode（实测二次命中 0.08s） 无内置（需自建） 无
反爬 中上（stealth/magic/undetected/托管身份） ⭐⭐ HTTP 层 TLS 指纹伪装，静态站极快且稳 弱（裸用易被检测）
代理轮换 ⭐ 内置 RoundRobin + 升级链 支持（HTTP fetcher 配代理） 手动
静态页速度 首次 ~1.5-2.5s（含浏览器启动），缓存后 ~0.07s 0.2-0.6s（纯 HTTP，无浏览器开销） 1-3s（浏览器启动）
学习成本 中（需理解 BrowserConfig/CrawlerRunConfig/策略） 低-中 中（但需自建所有管道）
部署 库 / CLI / Docker（FastAPI + 监控 + MCP） 库 库（无服务化方案）

5.3 选择建议

  • 给 LLM 喂内容（RAG/Agent/摘要） → 选 Crawl4AI：Markdown 质量、fit 过滤、LLM 提取是现成的，且免费开源无 token 限制；
  • 高频抓取静态/半静态站、或反爬严格但 HTTP 层可过（如微信公众号文章） → 选 Scrapling：curl_cffi 的 Chrome TLS 指纹在 HTTP 层就能 200 通过，单次请求 2s 内拿到 3.37MB 完整正文，无需浏览器；
  • 需要精确控制浏览器交互（自动化测试、复杂点击流、截图像素级控制） → 用 Playwright 裸库，或把 Crawl4AI 的 hooks/托管浏览器当作上层封装；
  • 微信（mp.weixin.qq.com）等对 Playwright 无头浏览器 302 到验证页的站点 → 实测 Crawl4AI 四策略会全部 anti_bot_detected 误判，优先用 Scrapling。

6. 优缺点与适用场景

6.1 优点

  1. LLM 友好是贯穿性设计：raw/fit 双版 Markdown、引用列表、BM25/Pruning 内容过滤、LLM 提取与分块管线——不是"能输出 Markdown"，而是"为 LLM 消费而优化"；
  2. 开箱即用的一体化：抓取 → 清洗 → Markdown → 结构化提取 → 缓存，一条 arun() 全搞定，附带 CLI 与 Docker 服务；
  3. 生态完整：DeepCrawl（3 策略 + 断点续爬 + 流式 + prefetch）、URL Seeding（sitemap/Common Crawl/Wayback/证书透明日志 8 大发现源）、DomainMapper、调度器、监控面板、MCP 集成；
  4. 反爬手段丰富且有层次：stealth → undetected → 托管浏览器真实身份 → 代理升级链 → 备用抓取函数，可渐进增强；
  5. 性能工程到位：实例级缓存（实测 26x 加速）、prefetch 模式（URL 发现 5-10x）、text_mode/light_mode 加速启动、浏览器池；
  6. 活跃与安全：77.8K stars、几乎日更；对 Docker RCE/供应链投毒等安全问题响应快（0.8.5~0.9.0 连续安全版本）。

6.2 缺点与局限

  1. Playwright 浏览器依赖重：国内网络下载 Chromium 二进制困难；无浏览器时只能降级纯 HTTP（功能缩水）；Docker 镜像较大；
  2. 首次调用慢：浏览器启动 1.5~2.5s（相对 Scrapling 纯 HTTP 的 0.2~0.6s），必须复用实例 + 缓存才能获得毫秒级体验；
  3. 强反爬站仍可能失败：无头浏览器特征明显，对微信/小红书/抖音等重机器人检测站点易误判（需 Scrapling 等 HTTP 层方案兜底）；
  4. 版本演进快、API 变动大：result.markdown 从字符串变为对象、缓存布尔参数废弃、配置迁移到 CrawlerRunConfig——老教程/老代码容易踩坑（官方迁移指南已给出双分支兼容写法）；
  5. LLM 提取成本/延迟：语义提取慢且贵，官方也建议规整数据优先无 LLM 策略；
  6. Docker 历史安全问题：0.8.7 前存在 RCE/SSRF 等漏洞，自托管必须升级到最新版并开启认证；
  7. Python 3.10+ 限定，同步版（Selenium）已废弃。

6.3 适用场景

场景 推荐度 说明
RAG / LLM 知识库构建 ⭐⭐⭐ fit Markdown + 引用 + 分块，直接对接向量化
AI Agent 网页工具 ⭐⭐⭐ 结构化提取 + Ask AI + MCP 集成
文档站/新闻/博客批量抓取 ⭐⭐⭐ DeepCrawl + 缓存 + 断点续爬
登录后内容抓取 ⭐⭐⭐ 托管浏览器身份档案（BrowserProfiler）
电商/价格监控 ⭐⭐ JsonCssExtractionStrategy 秒级提取 + 代理轮换
强反爬（微信/小红书等） ⭐ 需 Scrapling 或第三方解锁兜底
纯静态站超高频抓取 ⭐ Scrapling 更快（无浏览器开销）
浏览器自动化/测试 ⭐ 直接上 Playwright 裸库更合适

7. 数据来源

来源 内容 获取时间
GitHub REST API api.github.com/repos/unclecode/crawl4ai stars/forks/license/语言/创建时间/推送时间 2026-08-12
GitHub Releases API v0.4.0 ~ v0.9.2 版本历史与发布时间 2026-08-12
官方文档 docs.crawl4ai.com（40+ 页面） 安装/快速开始/配置/Markdown/Fit/DeepCrawl/缓存/代理/反爬/Chunking/LLM 提取/CLI/API 参考 2026-08-12
本地 README（/tmp/scraper_research/crawl4ai_README.md，1295 行） 功能清单、版本亮点、Docker、赞助 本地已抓取
社区集成示例 实际集成模式、去噪分层、降级策略 参考
社区实测 性能数据（首次 2.1s / 缓存 0.08s）、微信反爬踩坑 本地

报告完 · Happy Crawling! 🕸️🚀

Logo
龙虾开发者社区

小龙虾开发者社区是 CSDN 旗下专注 OpenClaw 生态的官方阵地，聚焦技能开发、插件实践与部署教程，为开发者提供可直接落地的方案、工具与交流平台，助力高效构建与落地 AI 应用

更多推荐

cover

大模型安全实战】智能体安全的攻防二元性：同一种能力，为什么既是防线也是攻击面？（第4期）

avatar 龙虾开发者社区
cover

SparkSQL 之 Hive On Spark 原理分析

avatar 龙虾开发者社区

RL训练Agentic模型实现并行多轮上下文检索：匹配前沿模型且快10倍

基于RL的Agentic检索模型正在成为AI Agent效率革命的关键驱动力。并行化：从串行单次调用转向多轮高并行调用自编辑：模型在检索过程中主动裁剪不相关信息迭代优化：检索器与Agent在RL训练中双向迭代当Agentic检索的速度提升10倍以上、成本大幅下降，AI系统将能在数秒内完成以往需要数分钟的复杂信息收集——这是Agent从“对话助手”走向“行动执行者”的关键一步。参考文献：, ACL

avatar 龙虾开发者社区