1. BrowserConfig – 控制浏览器

关注浏览器的启动和行为方式。这包括无头模式、代理、用户代理和其他环境调整。

from crawl4ai import AsyncWebCrawler, BrowserConfig

browser_cfg = BrowserConfig(
    browser_type="chromium",
    headless=True,
    viewport_width=1280,
    viewport_height=720,
    proxy="http://user:pass@proxy:8080",
    user_agent="Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 Chrome/116.0.0.0 Safari/537.36",
)

1.1 参数亮点

范围	类型/默认	它的作用
	，`"firefox"` ，`"webkit"` （默认：`"chromium"` )	使用哪种浏览器引擎。`"chromium"`对许多网站来说都是典型的，`"firefox"`或者`"webkit"`用于专门的测试。
	（默认：`True` )	无头意味着没有可见的用户界面。`False`方便调试。
	（默认：`1080` )	初始页面宽度（单位：px）。用于测试响应式布局。
	（默认：`600` )	初始页面高度（以 px 为单位）。
	（默认：`None` )	如果您希望所有流量都通过单代理 URL，例如`"http://user:pass@proxy:8080"`。
	（默认：`None` )	对于高级或多代理需求，请指定如下详细信息`{"server": "...", "username": "...", ...}`。
	（默认：`False` )	如果`True`，使用持久浏览器上下文（在运行期间保留 Cookie 和会话）。还设置`use_managed_browser=True`。
	（默认：`None` )	存储用户数据（配置文件、Cookie）的目录。如果您希望保持会话永久有效，则必须设置此目录。
	（默认：`True` )	如果`True`，尽管证书无效（在 dev/staging 中很常见），但仍继续。
	（默认：`True` )	如果您不想有 JS 开销，或者只需要静态内容，请禁用。
	（默认：`[]` )	预设的 cookies，每个都是一个字典，例如`{"name": "session", "value": "...", "url": "..."}`。
	（默认：`{}` )	每个请求的额外 HTTP 标头，例如`{"Accept-Language": "en-US"}`。
	（默认：基于 Chrome 的 UA）	您的自定义或随机用户代理。`user_agent_mode="random"`可以将其洗牌。
	（默认：`False` )	禁用一些后台功能以提高性能。
	（默认：`False` )	如果`True`，尝试禁用图像/其他重要内容以提高速度。
	（默认：`False` )	用于高级“托管”交互（调试、CDP 使用）。如果持久上下文已启用，通常会自动设置。
	（默认：`[]` )	底层浏览器进程的附加标志，例如`["--disable-extensions"]`。

提示：- 设置headless=False直观地调试页面加载方式或交互过程。 - 如果您需要身份验证存储或重复会话，请考虑use_persistent_context=True并指定user_data_dir. - 对于大页面，您可能需要更大的viewport_width和viewport_height处理动态内容。

2. CrawlerRunConfig – 控制每次爬取

尽管BrowserConfig设置环境，CrawlerRunConfig详细说明每个抓取操作的行为方式：缓存、内容过滤、链接或域名阻止、超时、JavaScript 代码等。

from crawl4ai import AsyncWebCrawler, CrawlerRunConfig

run_cfg = CrawlerRunConfig(
    wait_for="css:.main-content",
    word_count_threshold=15,
    excluded_tags=["nav", "footer"],
    exclude_external_links=True,
    stream=True,  # Enable streaming for arun_many()
)

2.1 参数亮点

我们按类别对它们进行分组。

A）内容处理

范围	类型/默认	它的作用
	（默认值：~200）	跳过 X 个单词以下的文本块。有助于忽略无关紧要的部分。
	（默认值：无）	如果设置，则提取结构化数据（基于 CSS、基于 LLM 等）。
	（没有任何）	如果您需要特殊的 Markdown 输出（引用、筛选、分块等），可以使用以下选项进行自定义：`content_source`参数来选择 HTML 输入源（'cleaned_html'、'raw_html' 或 'fit_html'）。
	（没有任何）	仅保留与此选择器匹配的页面部分。影响整个提取过程。
	（没有任何）	用于 Markdown 生成和数据提取的 CSS 选择器列表，同时仍处理整个页面的链接、媒体等。提供比`css_selector`。
	（没有任何）	删除整个标签（例如`["script", "style"]`）。
	（没有任何）	喜欢`css_selector`但要排除。例如`"#ads, .tracker"`。
	（错误的）	如果`True`，尝试提取纯文本内容。
	（错误的）	如果`True`，美化最终的 HTML（较慢，纯粹是装饰性的）。
	（错误的）	如果`True`，保存`data-*`清理后的 HTML 中的属性。
	（错误的）	如果`True`，删除所有`<form>`元素。

B）缓存和会话

范围	类型/默认	它的作用
	`CacheMode or None`	控制如何处理缓存（`ENABLED` ，`BYPASS` ，`DISABLED`等）。如果`None`，通常默认为`ENABLED`。
	`str or None`	分配唯一 ID 以在多个浏览器之间重复使用单个浏览器会话`arun()`呼叫。
	（错误的）	如果`True`，就像`CacheMode.BYPASS`。
	（错误的）	如果`True`，就像`CacheMode.DISABLED`。
	（错误的）	如果`True`，就像`CacheMode.WRITE_ONLY`（写入缓存但从不读取）。
	（错误的）	如果`True`，就像`CacheMode.READ_ONLY`（读取缓存但从不写入）。

使用这些来控制是否从本地内容缓存读取或写入。对于大批量爬取或重复访问网站非常有用。

范围	类型/默认	它的作用
	（domcontentloaded）	导航“完成”的条件。通常`"networkidle"`或者`"domcontentloaded"`。
	（60000 毫秒）	页面导航或 JS 步骤的超时时间。如果网站速度较慢，请增加此值。
	`str or None`	等待 CSS (`"css:selector"` ) 或 JS (`"js:() => bool"` ) 内容提取前的条件。
	（错误的）	等待图片加载完成。如果只想加载文本，加载速度会比较慢。
	(0.1)	在捕获最终 HTML 之前会额外暂停（秒）。适合最后一秒的更新。
	（错误的）	是否在抓取前检查并遵守 robots.txt 规则。如果设置为 True，则缓存 robots.txt 以提高效率。
和`max_range`	(0.1, 0.3)	如果你打电话`arun_many()`，这些定义了爬网之间的随机延迟间隔，有助于避免检测或速率限制。
	（5）	最大并发数`arun_many()`. 如果您有并行爬网的资源，请增加。

D）页面交互

范围	类型/默认	它的作用
	（没有任何）	加载后运行的 JavaScript。例如`"document.querySelector('button')?.click();"`。
	（错误的）	如果`True`，表示我们正在重用现有会话并仅应用 JS。无需完全重新加载。
	（真的）	跳过检查`<body>`可见。通常最好保留`True`。
	（错误的）	如果`True`，自动滚动页面以加载动态内容（无限滚动）。
	(0.2)	如果滚动步骤之间有延迟`scan_full_page=True`。
	（错误的）	内联 iframe 内容以进行单页提取。
	（错误的）	删除阻碍主要内容的潜在模式/弹出窗口。
	（错误的）	模拟用户交互（鼠标移动）以避免被机器人检测到。
	（错误的）	覆盖`navigator`JS 中的隐身属性。
	（错误的）	自动处理弹出窗口/同意横幅。实验性。
	（错误的）	调整视口大小以匹配页面内容高度。

如果您的页面是单页应用，且 JS 重复更新，请设置js_only=True在后续调用中，加上session_id重复使用同一个标签。

E) 媒体处理

范围	类型/默认	它的作用
	（错误的）	截取屏幕截图（base64）`result.screenshot` 。
	`float or None`	截图前需额外等待一段时间。
	（约20000）	如果页面高度高于此值，则使用替代的屏幕截图策略。
	（错误的）	如果`True`，返回 PDF 格式`result.pdf`。
	（错误的）	如果`True`，捕获页面的 MHTML 快照`result.mhtml`。MHTML 将所有页面资源（CSS、图像等）包含在一个文件中。
	（约50）	图像替代文本或描述的最少字数才被视为有效。
	（约3）	过滤掉得分低的图片。爬虫会根据相关性（大小、上下文等）对图片进行评分。
	（错误的）	排除来自其他域的图像。

F）链接/域名处理

范围	类型/默认	它的作用
	（例如 Facebook/Twitter）	默认列表可以扩展。任何指向这些域的链接都将从最终输出中删除。
	（错误的）	删除指向当前域之外的所有链接。
	（错误的）	删除指向社交网站（如 Facebook 或 Twitter）的链接。
	（[]）	提供要排除的域名的自定义列表（例如`["ads.com", "trackers.io"]`）。

使用这些进行链接级内容过滤（通常是为了保持抓取“内部”或删除垃圾域）。

G）调试和日志记录

范围	类型/默认	它的作用
	（真的）	打印详细记录爬行、交互或错误的每个步骤的日志。
	（错误的）	如果您想要进行更深入的 JS 调试，请记录页面的 JavaScript 控制台输出。

H) 虚拟涡旋配置

范围	类型/默认	它的作用
	（没有任何）	用于处理 Twitter/Instagram 等网站上的虚拟化滚动的配置，其中内容被替换而不是附加。

当网站使用虚拟滚动（滚动时内容会替换）时，使用VirtualScrollConfig：

from crawl4ai import VirtualScrollConfig

virtual_config = VirtualScrollConfig(
    container_selector="#timeline",    # CSS selector for scrollable container
    scroll_count=30,                   # Number of times to scroll
    scroll_by="container_height",      # How much to scroll: "container_height", "page_height", or pixels (e.g. 500)
    wait_after_scroll=0.5             # Seconds to wait after each scroll for content to load
)

config = CrawlerRunConfig(
    virtual_scroll_config=virtual_config
)

VirtualScrollConfig 参数：

范围	类型/默认	它的作用
	（必需的）	可滚动容器的 CSS 选择器（例如，`"#feed"` ，`".timeline"` )
	（10）	执行的最大滚动次数
	（“容器高度”）	滚动量：`"container_height"` ，`"page_height"`或像素（例如，`500` )
	(0.5)	每次滚动后等待加载新内容的时间（秒）

何时使用虚拟滚动与 scan_full_page： - 使用virtual_scroll_config当滚动过程中内容被替换时（Twitter，Instagram） - 使用scan_full_page在滚动过程中附加内容时（传统无限滚动）

有关详细示例，请参阅虚拟滚动文档。

---## 2.2 辅助方法

两个都BrowserConfig和CrawlerRunConfig提供一个clone()创建修改副本的方法：

# Create a base configuration
base_config = CrawlerRunConfig(
    cache_mode=CacheMode.ENABLED,
    word_count_threshold=200
)

# Create variations using clone()
stream_config = base_config.clone(stream=True)
no_cache_config = base_config.clone(
    cache_mode=CacheMode.BYPASS,
    stream=True
)

这clone()当您需要针对不同的用例使用稍微不同的配置，而无需修改原始配置时，此方法特别有用。

2.3 示例用法

import asyncio
from crawl4ai import AsyncWebCrawler, BrowserConfig, CrawlerRunConfig, CacheMode

async def main():
    # Configure the browser
    browser_cfg = BrowserConfig(
        headless=False,
        viewport_width=1280,
        viewport_height=720,
        proxy="http://user:pass@myproxy:8080",
        text_mode=True
    )

    # Configure the run
    run_cfg = CrawlerRunConfig(
        cache_mode=CacheMode.BYPASS,
        session_id="my_session",
        css_selector="main.article",
        excluded_tags=["script", "style"],
        exclude_external_links=True,
        wait_for="css:.article-loaded",
        screenshot=True,
        stream=True
    )

    async with AsyncWebCrawler(config=browser_cfg) as crawler:
        result = await crawler.arun(
            url="https://example.com/news",
            config=run_cfg
        )
        if result.success:
            print("Final cleaned_html length:", len(result.cleaned_html))
            if result.screenshot:
                print("Screenshot captured (base64, length):", len(result.screenshot))
        else:
            print("Crawl failed:", result.error_message)

if __name__ == "__main__":
    asyncio.run(main())

2.4 合规与道德

范围	类型/默认	它的作用
	（错误的）	设置为 True 时，抓取前会检查并遵守 robots.txt 规则。使用 SQLite 后端的高效缓存。
	（没有任何）	用于识别您的爬虫程序的用户代理字符串。启用后，用于 robots.txt 检查。

run_config = CrawlerRunConfig(
    check_robots_txt=True,  # Enable robots.txt compliance
    user_agent="MyBot/1.0"  # Identify your crawler
)

3. LLMConfig - 设置 LLM 提供程序

LLMConfig 可用于将 LLM 提供程序配置传递给依赖 LLM 进行提取、过滤、模式生成等操作的策略和函数。目前，它可以用于以下用途 -

法学硕士提取策略
LLM内容过滤器
JsonCssExtractionStrategy.generate_schema
JsonXPathExtractionStrategy.generate_schema

3.1 参数

范围	类型/默认	它的作用
	（默认：`"openai/gpt-4o-mini"` )	使用哪个 LLM 提供商。
	1.可选。如果未明确提供，api_token 将根据提供商从环境变量中读取。例如：如果将 gemini 模型作为提供商传递，则`"GEMINI_API_KEY"`将从环境变量中读取 2. LLM 提供商的 API 令牌，例如：`api_token = "gsk_1ClHGGJ7Lpn4WGybR7vNWGdyb3FY7zXEw3SCiy0BAVM9lL8CQv"` 3.环境变量-使用前缀“env：”例如：`api_token = "env: GROQ_API_KEY"`	用于给定提供商的 API 令牌
	可选。自定义 API 端点	如果您的提供商有自定义端点

3.2 示例用法

llm_config = LLMConfig(provider="openai/gpt-4o-mini", api_token=os.getenv("OPENAI_API_KEY"))

4. 整合

使用BrowserConfig用于全局浏览器设置：引擎、无头、代理、用户代理。
使用CrawlerRunConfig对于每个抓取的上下文：如何过滤内容、处理缓存、等待动态元素或运行 JS。
将两个配置传递给AsyncWebCrawler（这BrowserConfig）然后arun()（这CrawlerRunConfig）。
使用LLMConfig适用于所有提取、过滤和模式生成任务的 LLM 提供程序配置。可用于：LLMExtractionStrategy ，LLMContentFilter ，JsonCssExtractionStrategy.generate_schema &JsonXPathExtractionStrategy.generate_schema

# Create a modified copy with the clone() method
stream_cfg = run_cfg.clone(
    stream=True,
    cache_mode=CacheMode.BYPASS
)