crawl4ai

Crawl4AI

已针对 crawl4ai VERSION 验证。scripts/*.py 和 tests/*.py 中的 PEP 723 固定版本均不低于该版本。

概述

Crawl4AI 封装了一个无头浏览器（Playwright）以及支持 Markdown 的内容处理流水线。当 defuddle/curl 无法获取内容时，可使用它——例如 JavaScript 渲染的页面、需要登录的内容、无限滚动、多 URL 并发，以及基于架构的可重复提取。

此技能提供底层库的两种接口：

• CLI（crwl）——快速、可编写脚本的命令：CLI 指南
• Python SDK——完整的编程控制：SDK 指南

使用 URL 参数调用

当用户运行 /crawl4ai <url>，只提供一个 URL，且没有进一步限定时，将其视为需要获取 JavaScript 密集型页面的情况，并默认使用：

crwl <url> -c "wait_until=networkidle,page_timeout=60000" -o markdown

wait_until=networkidle 会等待网络在页面加载后安静约 500 毫秒；当用户没有指定 JavaScript 渲染页面上的特定元素时，这是合适的默认设置。（避免使用 wait_for=css:body：每个 HTML 响应中的 <body> 都会在 t=0 时存在，因此在 JavaScript 渲染内容之前就会满足条件。）然后将 Markdown 返回到 Agent 上下文中。如果用户指定了特定元素，则调整为 wait_for=css:<selector>。如果任务涉及提取、批量／多 URL、登录／会话、截图／PDF 或 URL 发现，则跳过默认设置，转到下方相关部分——这些任务各自有专用的处理流水线。如果 URL 显然是静态页面（文档页、博客文章），则按照下方“何时不使用”部分的说明，引导用户改用 /fetch-web。

何时不使用此技能

• 静态 HTML 页面（大多数文档网站、博客文章、新闻文章、推文）——直接使用 /fetch-web 或 defuddle。静态提取的冷启动约为 0 毫秒；crawl4ai 则需要额外支付约 2 秒的浏览器启动开销。
• 本地文件转换（.pdf、.docx、.pptx、.epub）——使用 /markdown-convert。
• 读取单个 URL 并放入 Agent 上下文（Agent 只需读取此页面）——使用 /fetch-web，并让它转交给 defuddle。
• 会修改页面的 UI 流程（填写表单、多步点击、登录并导航）——使用 /browse（gstack 的持久无头 Chromium），它专为此类操作构建。

遇到问题时

对于参考文档未涵盖的未知 crwl/SDK 标志、抓取失败或提取边缘情况，请参阅 references/escalation.md，了解查询顺序（qmd 解决方案 → 上游文档 → GitHub 问题 → 询问用户）和示例。

---

快速入门

安装

pip install crawl4ai
crawl4ai-setup

# Verify installation
crawl4ai-doctor

CLI（推荐）

# Basic crawling - returns markdown
crwl https://example.com

# Get markdown output
crwl https://example.com -o markdown

# JSON output with cache bypass
crwl https://example.com -o json -v --bypass-cache

# See more examples
crwl --example

Python SDK

import asyncio
from crawl4ai import AsyncWebCrawler

async def main():
    async with AsyncWebCrawler() as crawler:
        result = await crawler.arun("https://example.com")
        print(result.markdown[:500])

asyncio.run(main())

SDK 配置详情请参阅：SDK 指南 - 配置。

---

核心概念

配置层

CLI 和 SDK 使用相同的底层配置：

概念	CLI	SDK
浏览器设置	-B browser.yml 或 -b "param=value"	BrowserConfig(...)
爬取设置	-C crawler.yml 或 -c "param=value"	CrawlerRunConfig(...)
提取	-e extract.yml -s schema.json	extraction_strategy=...
内容筛选器	-f filter.yml	markdown_generator=...

关键参数

浏览器配置：

• headless：使用或不使用 GUI 运行
• viewport_width/height：浏览器尺寸
• user_agent：自定义用户代理
• proxy_config：代理设置

爬虫配置：

• page_timeout：页面加载最长时间（毫秒）
• wait_for：要等待的 CSS 选择器或 JS 条件
• cache_mode：绕过、启用、禁用
• js_code：要执行的 JavaScript
• css_selector：聚焦于特定元素

完整参数请参阅：CLI 配置 | SDK 配置

输出内容

每次爬取都会返回：

• markdown - 整洁、格式规范的 Markdown
• html - 原始 HTML
• links - 发现的内部和外部链接
• media - 找到的图片、视频和音频
• extracted_content - 结构化数据（如果配置了提取功能）

---

Markdown 生成（主要用例）

Crawl4AI 擅长生成整洁、格式规范的 Markdown。

CLI

crwl https://docs.example.com -o markdown                              # raw markdown
crwl https://docs.example.com -o markdown-fit                          # filtered (noise removed)
crwl https://docs.example.com -f templates/filter_bm25.yml -o markdown-fit   # BM25-relevance filter
crwl https://docs.example.com -f templates/filter_pruning.yml -o markdown-fit # quality-based filter

筛选模板：templates/filter_bm25.yml（根据查询进行相关性评分）， templates/filter_pruning.yml（无需查询，可剪除低质量内容块）。

Python SDK

from crawl4ai.content_filter_strategy import BM25ContentFilter
from crawl4ai.markdown_generation_strategy import DefaultMarkdownGenerator

bm25_filter = BM25ContentFilter(user_query="machine learning", bm25_threshold=1.0)
md_generator = DefaultMarkdownGenerator(content_filter=bm25_filter)

config = CrawlerRunConfig(markdown_generator=md_generator)
result = await crawler.arun(url, config=config)

print(result.markdown.fit_markdown)  # Filtered
print(result.markdown.raw_markdown)  # Original

有关筛选器选择和配置字段的参考，请参阅内容筛选器。

---

数据提取

1. 基于 Schema 的 CSS 提取（效率最高）

提取时无需 LLM——速度快、结果确定且不产生费用。仅需一次性支付 LLM 费用来生成 Schema，之后即可 无限次复用。随附的脚本按职责拆分了整个流程：

./scripts/generate_schema.py https://shop.example.com "products with name, price, image" shop_schema.json
./scripts/extract_with_schema.py https://shop.example.com shop_schema.json products.json

也可以通过 CLI 使用 YAML 策略模板和已保存的 Schema：

crwl https://shop.example.com -e templates/extract_css.yml -s shop_schema.json -o json

Schema 框架：templates/css_schema.json。策略 YAML： templates/extract_css.yml。

2. 基于 LLM 的提取

适用于一次性或不规则的内容提取，这类场景中 CSS Schema 过于脆弱：

./scripts/extract_with_llm.py https://news.example.com "Extract headlines, dates, summaries" news.json

也可以通过 CLI 使用策略模板：

crwl https://news.example.com -e templates/extract_llm.yml -o json

策略 YAML：templates/extract_llm.yml。每个 URL 都会产生一次 LLM 调用费用——如需重复 提取，建议优先使用上述 Schema 流程。

有关提取策略的参考，请参阅：提取策略。

---

高级模式

动态内容（JavaScript 密集型网站）

crwl https://example.com -c "wait_for=css:.ajax-content,scan_full_page=true,page_timeout=60000"
crwl https://example.com -C templates/crawler.yml                          # all options in a YAML file

爬虫配置模板：templates/crawler.yml。

多 URL 处理

./scripts/batch_crawl.py urls.txt --max-concurrent 5 --out batch_markdown/
./scripts/batch_extract.py urls.txt shop_schema.json --max-concurrent 5 --out products.json

这两个脚本按职责拆分：batch_crawl.py 会返回每个 URL 对应的 Markdown；batch_extract.py 会返回每个 URL 对应的 Schema 提取 JSON。Python 中的等效用法是 arun_many()：

urls = ["https://site1.com", "https://site2.com", "https://site3.com"]
results = await crawler.arun_many(urls, config=config)

有关批处理的参考，请参阅：arun_many() 参考。

爬取前发现 URL

如果 URL 列表来自站点地图或域名，而不是已知列表，请先进行发现，再将结果传入 batch_crawl.py / batch_extract.py。完整功能说明请参阅 URL 发现；简要示例如下：

from crawl4ai import AsyncUrlSeeder, SeedingConfig
seeds = await AsyncUrlSeeder().urls("example.com", SeedingConfig(
    source="sitemap+cc", pattern="*/blog/*", query="machine learning", score_threshold=0.3, live_check=True,
))
urls = [s["url"] for s in seeds]

如果要根据查询进行 BM25 评分筛选，AsyncUrlSeeder 最合适；如果要最大限度覆盖某个域名，DomainMapper 最合适。

会话与身份验证

填写登录模板，然后在后续爬取中复用会话 ID：

crwl https://site.com/login -C templates/login_crawler.yml
crwl https://site.com/protected -c "session_id=user_session"

登录模板：templates/login_crawler.yml（使用前需填写字段 ID 选择器和登录后的等待条件）。

有关会话管理的参考，请参阅：高级功能。

反检测与代理

crwl https://example.com -B templates/browser.yml

浏览器配置模板：templates/browser.yml（按需取消 proxy_config 和 init_scripts 的注释）。如需在页面加载前注入脚本（必须在任何网站脚本之前运行的指纹补丁），请填写 init_scripts:，而非 js_code:（后者会在页面加载后运行）。proxy_config 既适用于浏览器策略，也适用于非浏览器的 HTTPCrawlerStrategy——对于通过企业代理获取静态内容，后者是低成本方案。

完整功能说明（CDP 连接、未检测模式、初始化脚本模式）：反检测。

渲染缓存的 HTML（raw: / file://）

如果 Agent 已有 HTML（例如来自 defuddle 或之前的爬取），只需要截图、PDF 或 MHTML 渲染，则可跳过网络获取，直接传入 HTML。base_url 用于控制相对链接解析：

result = await crawler.arun(
    url="raw:" + html_string,
    config=CrawlerRunConfig(base_url="https://example.com", screenshot=True, pdf=True),
)

result = await crawler.arun(
    url="file:///path/to/page.html",
    config=CrawlerRunConfig(screenshot=True),
)

---

常见用例

Recipes 中提供了 8 个端到端实用流程（文档页面、JS 密集型 SPA、电商产品提取、新闻聚合、限定主题的域名爬取、需要登录的内容、渲染现有 HTML、问答）。选择最接近当前任务的流程并加以调整。

---

资源

提供的脚本

脚本	职责
scripts/basic_crawler.py <url>	单个 URL → Markdown + 截图
scripts/batch_crawl.py <urls.txt>	多个 URL → Markdown 文件
scripts/batch_extract.py <urls.txt> <schema.json>	多个 URL + 架构 → JSON
scripts/generate_schema.py <url> "<instruction>"	推导可复用的 CSS 架构（一次性 LLM 调用）
scripts/extract_with_schema.py <url> <schema.json>	应用已保存的架构（不调用 LLM）
scripts/extract_with_llm.py <url> "<instruction>"	按请求使用 LLM 提取（成本高；仅用于一次性任务）

模板

供用户复制并填写的 YAML 和 JSON 框架。全部位于技能根目录下的 templates/ 中：

模板	用途
templates/browser.yml	BrowserConfig（无头模式、代理、用户代理、初始化脚本）
templates/crawler.yml	CrawlerRunConfig（缓存、等待、超时、JS）
templates/extract_css.yml	JsonCssExtractionStrategy 声明
templates/extract_llm.yml	LLMExtractionStrategy 声明
templates/filter_bm25.yml	BM25 内容过滤器（按相关性评分）
templates/filter_pruning.yml	剪枝内容过滤器（基于质量，不需要查询）
templates/login_crawler.yml	建立会话的登录流程
templates/css_schema.json	CSS 架构框架

参考文档

文档	用途
CLI 指南	命令行界面参考
SDK 指南	Python SDK 快速参考
Recipes	8 个端到端实用流程
URL 发现	AsyncUrlSeeder、SeedingConfig、DomainMapper
内容过滤器	BM25、Pruning 与 LLMContentFilter——何时使用哪一种
反检测	init_scripts、proxy_config、隐身模式、CDP 附加
故障排除	症状、原因、解决方法；升级处理前可尝试的操作
完整 SDK 参考	完整 API 文档（5900 多行）
升级处理	查询顺序、铁律、暂停与继续、实用示例

---

最佳实践

1. 从 CLI 开始，适合快速执行任务；自动化场景使用 SDK
2. 使用基于 schema 的提取，效率比大模型高 10–100 倍
3. 开发期间启用缓存，仅在需要时使用 --bypass-cache
4. 设置适当的超时时间，常规情况为 30s，JavaScript 较多的网站为 60s 或更长
5. 使用内容过滤器，生成更简洁、聚焦的 Markdown
6. 遵守速率限制，在请求之间添加延迟

---

故障排除

如需查看症状 → 原因 → 修复表（涵盖 JavaScript 未加载、机器人检测、提取内容为空、会话未持久化、爬取缓慢、schema 生成结果异常、升级后出现回归问题），请参阅故障排除。对于参考资料未涵盖的未知情况，请遵循升级处理流程。

---

如需完整的 API 文档，请参阅完整 SDK 参考。

许可证

采用 MIT 或 Apache-2.0 双重许可，您可以自行选择（SPDX：MIT OR Apache-2.0）。说明以及对上游镜像文件 references/complete-sdk-reference.md 的例外条款，请参阅 LICENSE。