尧图网站建设 
Crawl4AI 配置系统实战BrowserConfig、CrawlerRunConfig 与 LLMConfig 三层协作详解【免费下载链接】crawl4ai Crawl4AI: Open-source LLM Friendly Web Crawler Scraper. Dont be shy, join here: https://discord.gg/jP8KfhDhyN项目地址: https://gitcode.com/GitHub_Trending/craw/crawl4aiCrawl4AI 的灵活性来自三个配置类BrowserConfig决定浏览器如何启动与运行CrawlerRunConfig决定每一次爬取如何执行LLMConfig决定LLM 供应商如何接入。典型用法是为整个爬虫会话创建一个BrowserConfig再在每次调用arun()时传入一个新建或复用的CrawlerRunConfig按需搭配LLMConfig。读完本篇你将掌握这三类配置的全部常用参数、取值范围与默认值以及clone()、set_defaults()等辅助机制的源码级实现能够独立编写可运行、可维护的抓取配置代码。三大配置类的职责划分从 crawl4ai/async_configs.py 的源码结构看三类配置各自独立、按需组合BrowserConfig定义位置——控制浏览器引擎类型、headless 与否、代理、User-Agent、视口、持久化上下文等作用于浏览器/上下文生命周期通常在整个会话中只创建一次。CrawlerRunConfig定义位置——控制缓存、内容抽取、等待条件、JS 注入、截图/PDF 等作用于单次爬取操作每次arun()都可传入不同的配置。LLMConfig定义位置——控制 LLM 供应商、API Token、base URL 与重试退避策略供LLMExtractionStrategy、LLMContentFilter等策略对象消费。需要高级或冷门字段时可查阅完整参数参考 Configuration Parameters。BrowserConfig控制浏览器如何启动构造函数与核心参数速览BrowserConfig.__init__的完整签名crawl4ai/async_configs.py涵盖数十个参数以下按“浏览器类型 → 运行模式 → 网络身份 → 渲染性能”的顺序梳理最常用的字段class BrowserConfig: def __init__( browser_typechromium, headlessTrue, browser_modededicated, use_managed_browserFalse, cdp_urlNone, debugging_port9222, hostlocalhost, proxy_configNone, viewport_width1080, viewport_height600, verboseTrue, use_persistent_contextFalse, user_data_dirNone, cookiesNone, headersNone, user_agent( Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 Chrome/116.0.0.0 Safari/537.36 ), user_agent_mode, text_modeFalse, light_modeFalse, extra_argsNone, enable_stealthFalse, # ... 其他高级参数省略 ): ...关键字段逐项说明1.browser_type可选值chromium、firefox、webkit默认chromium。需要其他渲染引擎时在此指定。源码中当类型为firefox/webkit时会清空channel/chrome_channelL849-L851因为 Chrome 渠道参数只适用于 chromium 系浏览器。2.headlessTrue无头模式不可见浏览器False可视化模式方便调试。3.browser_mode决定浏览器初始化方式取值dedicated默认每次创建新的浏览器实例builtin使用后台常驻的内置 CDP 浏览器custom使用cdp_url提供的显式 CDP 连接也可用docker模式运行容器化隔离浏览器。从源码看L911-L929browser_mode会联动改写use_managed_browserbuiltin、docker、以及带cdp_url的custom模式都会自动置为Trueuse_persistent_contextTrue时同样强制use_managed_browserTrue。因此多数场景只需设置browser_mode一个字段。4.use_managed_browser与cdp_urluse_managed_browserTrue通过 Chrome DevTools ProtocolCDP启动/接管浏览器便于高级控制cdp_urlCDP 端点地址例如ws://localhost:9222/devtools/browser/两者由browser_mode自动协调一般不必手工同时设置。5.debugging_port与hostdebugging_port调试协议端口默认9222host浏览器连接主机默认localhost。6.proxy_config接受ProxyConfig对象、字符串或字典例如{ server: http://proxy.example.com:8080, username: ..., password: ... }不需要代理时保持None。源码会自动把 dict/str 归一化为ProxyConfigL856-L867旧的proxy字符串参数已被标记弃用传入时会产生UserWarning提示改用proxy_configL852-L853。7.viewport_width与viewport_height初始窗口尺寸默认1080×600。部分网站在不同视口下行为不同响应式布局、懒加载触发等。另有一个viewport字典参数设置后会覆盖两个宽度/高度字段L872-L874。8.device_scale_factor控制渲染的设备像素比DPR默认1.0。设为2.0可获得 Retina 级截图质量例如1920×1080视口产出3840×2160图像数值越高截图体积与渲染耗时按比例增长。9.verboseTrue时打印额外日志便于调试默认True。10.use_persistent_contextTrue时使用持久化浏览器配置档跨运行保留 cookies / localStorage通常配合user_data_dir指定目录。11.cookies与headers在上下文创建时注入初始 cookies 或全局 HTTP 头例如cookies[{name: session, value: abc123, domain: example.com}]。源码还会根据user_agent自动生成 client hints 并写入sec-ch-ua响应头L908-L909避免 UA 与指纹不一致被识别。12.user_agent与user_agent_modeuser_agent自定义 UA 字符串user_agent_moderandom从内置合法 UA 库随机生成源码中由ValidUAGenerator实现L900-L906可配合user_agent_generator_config细化生成条件有助于降低被反爬识别的概率。13.text_mode与light_modetext_modeTrue禁用图片等富媒体加载适合纯文本抓取提速light_modeTrue关闭部分后台特性以换取性能。14.avoid_ads与avoid_cssavoid_adsTrue在浏览器上下文层面拦截常见广告与追踪域Google Analytics、DoubleClick、Facebook、Hotjar 等降低网络开销与内存占用avoid_cssTrue拦截 CSS 文件.css、.less、.scss、.sass加载只取文本内容时更轻快两者默认均为Falseopt-in可互相组合也可与text_mode叠加。15.extra_args透传给底层浏览器的额外命令行参数如[--disable-extensions]。16.enable_stealthTrue时启用基于 playwright-stealth 的隐身模式修改浏览器指纹以规避基础机器人检测默认False推荐用于有反爬保护的站点。注意源码中的约束enable_stealth与browser_modebuiltin不能同时使用否则抛出ValueError——隐身模式要求独占的浏览器实例L931-L936。最小可运行示例from crawl4ai import AsyncWebCrawler, BrowserConfig browser_conf BrowserConfig( browser_typefirefox, headlessFalse, text_modeTrue ) async with AsyncWebCrawler(configbrowser_conf) as crawler: result await crawler.arun(https://example.com) print(result.markdown[:300])CrawlerRunConfig控制单次爬取如何执行构造函数与核心参数速览class CrawlerRunConfig: def __init__( word_count_threshold200, extraction_strategyNone, chunking_strategyRegexChunking(), markdown_generatorNone, cache_modeCacheMode.BYPASS, js_codeNone, c4a_scriptNone, wait_forNone, screenshotFalse, pdfFalse, capture_mhtmlFalse, # 位置与身份参数 localeNone, # e.g. en-US, fr-FR timezone_idNone, # e.g. America/New_York geolocationNone, # GeolocationConfig 对象 # 代理配置 proxy_configNone, proxy_rotation_strategyNone, # 页面交互参数 scan_full_pageFalse, scroll_delay0.2, wait_untildomcontentloaded, page_timeout60000, delay_before_return_html0.1, # URL 匹配参数 url_matcherNone, # 用于 URL 级差异化配置 match_modeMatchMode.OR, verboseTrue, streamFalse, # 为 arun_many() 启用流式处理 # ... 其他高级参数省略 ): ...当前源码中该构造函数实际包含 100 个参数crawl4ai/async_configs.py以下只聚焦高频字段。关键字段逐项说明1.word_count_threshold一个内容块进入后续处理前的最小单词数。注意默认值以当前版本为准源码签名为word_count_threshold: int MIN_WORD_THRESHOLD而 crawl4ai/config.py 中MIN_WORD_THRESHOLD 1。也就是说当前版本默认几乎不过滤短块若希望达到上文示例中 200 词的阈值效果应显式传入word_count_threshold200。站点存在大量短段落/短条目时可调低。2.extraction_strategy挂载结构化抽取策略的入口CSS、XPath、LLM 等若为None则不做结构化抽取只返回原始/清洗后的 HTML 与 Markdown。传入时会做类型校验非ExtractionStrategy实例直接抛出ValueErrorL1838-L1843。3.chunking_strategy抽取前对内容做切块的策略默认RegexChunking()同样会做类型校验。4.markdown_generator例如DefaultMarkdownGenerator(...)控制 HTML→Markdown 的转换方式。当前源码的默认值就是一个DefaultMarkdownGenerator()实例L1592传None也会回落到默认行为。5.cache_mode控制缓存行为ENABLED、BYPASS、DISABLED等枚举定义于 crawl4ai/cache_context.py默认CacheMode.BYPASS。旧的bypass_cache/disable_cache/no_cache_read/no_cache_write布尔参数仍可用但源码中已标注为 legacy 并建议使用cache_mode表达L1579-L1584。6.js_code、js_code_before_wait与c4a_scriptjs_code在wait_for完成之后、对完全加载的页面执行 JavaScriptjs_code_before_wait在wait_for之前执行用于触发wait_for随后要检测的加载行为c4a_script编译为 JavaScript 的 C4A 脚本三者都适合实现“Load More”按钮、点击展开等页面交互。7.wait_for抽取前等待的 CSS 或 JS 表达式常见写法wait_forcss:.main-loaded或wait_forjs:() window.loaded true。可配合wait_for_timeout指定等待超时缺省使用page_timeout。8.flatten_shadow_domTrue时在捕获 HTML 前把 Shadow DOM 内容展平进 light DOM并对 closed shadow root 强制打开对基于 Web ComponentsStencil、Lit、Shoelace 等构建的站点必不可少原理详见 Flattening Shadow DOM。9.screenshot、pdf与capture_mhtml分别为True时页面完全加载后捕获截图、PDF 或 MHTML 快照结果位于result.screenshotbase64、result.pdfbytes、result.mhtml字符串配合force_viewport_screenshotTrue只截取可视视口而非整页速度更快、图片更小。10. 位置参数Location Parameterslocale浏览器区域设置如en-US、fr-FR影响语言偏好timezone_id时区如America/New_York、Europe/Parisgeolocation通过GeolocationConfig(latitude48.8566, longitude2.3522, accuracy0.0)注入 GPS 坐标定义位置完整用法参见 Identity Based Crawling。11. 代理配置Proxy Configurationproxy_config单个ProxyConfig或list[ProxyConfig]——列表会按顺序尝试天然支持自动升级escalationproxy_rotation_strategy爬取过程中轮换代理的策略对象。12. 反机器人重试与兜底Anti-Bot Retry Fallbackmax_retries检测到拦截时的重试轮数默认0每轮会遍历proxy_config中的全部代理fallback_fetch_function最后手段的异步函数接收 URL、返回原始 HTML。完整机制见 Anti-Bot Fallback。13. 页面交互参数Page Interaction Parametersscan_full_pageTrue时滚动整页以触发全部懒加载内容scroll_delay滚动步长之间的延时秒默认0.2wait_until导航时的等待条件domcontentloaded、networkidle等默认domcontentloadedpage_timeout页面操作超时毫秒默认60000来自 config.py 的PAGE_TIMEOUTdelay_before_return_html获取最终 HTML 前的延时秒默认0.1。14.url_matcher与match_mode与arun_many()配合实现 URL 级差异化配置url_matcher可设为 glob 模式、函数或它们的列表match_modeMatchMode.OR/MatchMode.AND定义位置控制多个模式的组合方式示例见 URL-Specific Configurations。15.verbose记录额外运行时细节若在BrowserConfig中也设为True两者日志会叠加。16.streamTrue时为arun_many()启用流式模式URL 完成即处理结果无需等待全部 URL 结束便于增量处理大批量任务。clone()低成本派生配置变体CrawlerRunConfig提供clone(**kwargs)实现位置来创建配置变体# 创建基础配置 base_config CrawlerRunConfig( cache_modeCacheMode.ENABLED, word_count_threshold200, wait_untilnetworkidle ) # 派生不同用途的变体 stream_config base_config.clone( streamTrue, # 启用流式模式 cache_modeCacheMode.BYPASS ) debug_config base_config.clone( page_timeout120000, # 调试时用更长超时 verboseTrue )clone()的语义生成一个保留全部原设置的新实例仅更新传入的参数原配置保持不变——适合“一份基础配置 多个场景变体”的写法避免在每个调用点重复罗列全部参数。LLMConfig接入 LLM 供应商LLMConfig的字段较少但每条都影响面很大实现位置provider指定 LLM 供应商/模型。当前源码支持的取值定义在 crawl4ai/config.py 的PROVIDER_MODELS中包括ollama/llama3、groq/llama3-70b-8192、groq/llama3-8b-8192、openai/gpt-4o-mini、openai/gpt-4o、openai/o1-mini、openai/o1-preview、openai/o3-mini、openai/o3-mini-high、anthropic/claude-3-haiku-20240307、anthropic/claude-3-opus-20240229、anthropic/claude-3-sonnet-20240229、anthropic/claude-3-5-sonnet-20240620、gemini/gemini-pro、gemini/gemini-1.5-pro、gemini/gemini-2.0-flash、gemini/gemini-2.0-flash-exp、gemini/gemini-2.0-flash-lite-preview-02-05、deepseek/deepseek-chat。当前源码的兜底默认值是DEFAULT_PROVIDER openai/gpt-4oconfig.py若传入的 provider 前缀不在已知列表中会回退到该默认值。api_token可选项。三种提供方式显式传字符串如api_tokensk-...使用env:前缀从环境变量读取源码逻辑是截取前 4 个字符后调用os.getenv()L2264-L2265因此推荐写成api_tokenenv:GROQ_API_KEYenv:后紧跟变量名完全不传源码按 provider 前缀匹配PROVIDER_MODELS_PREFIXESopenai→OPENAI_API_KEY、gemini→GEMINI_API_KEY、groq→GROQ_API_KEY等config.py自动从对应环境变量取 Key。base_url供应商存在自定义端点自建网关、兼容 API 等时指定。重试/退避控制可选backoff_base_delay默认2秒供应商返回限流响应后、首次重试前的基础延迟backoff_max_attempts默认3总尝试次数首次调用 重试超过后请求以错误形式上抛backoff_exponential_factor默认2重试延迟的增长因子delay base_delay * factor^attempt这些值会转发给共享的perform_completion_with_backoff辅助函数保证所有消费LLMConfig的策略遵循同一套限流策略。llm_config LLMConfig( provideropenai/gpt-4o-mini, api_tokenos.getenv(OPENAI_API_KEY), backoff_base_delay1, # 可选 backoff_max_attempts5, # 可选 backoff_exponential_factor3, # 可选 )除上述字段外LLMConfig还支持temperature、max_tokens、top_p、frequency_penalty、presence_penalty、stop、n等采样参数签名位置默认均为None交给供应商默认值。类级默认值set_defaults() 机制BrowserConfig与CrawlerRunConfig均支持通过set_defaults()设置类级默认覆盖由_with_defaults装饰器实现crawl4ai/async_configs.py。这在服务端/云部署中非常有用所有实例共享同一组基础设置时只需在启动时设置一次而不是在每个调用点重复。参数解析优先级为显式传参 类级用户默认值 硬编码默认值L43-L50。from crawl4ai import BrowserConfig, CrawlerRunConfig # 应用启动时 —— 只需一次 BrowserConfig.set_defaults( cache_cdp_connectionTrue, cdp_close_delay0, create_isolated_contextTrue, ) CrawlerRunConfig.set_defaults(verboseFalse) # 之后新建的实例自动继承这些默认值 cfg BrowserConfig(cdp_urlws://localhost:9222) # → cache_cdp_connectionTrue, cdp_close_delay0, create_isolated_contextTrue # 显式值仍然优先 cfg BrowserConfig(cdp_urlws://localhost:9222, cache_cdp_connectionFalse) # → cache_cdp_connectionFalse显式值覆盖类级默认值两个类都提供以下方法方法说明set_defaults(**kwargs)设置类级默认值。参数名无效时抛出ValueError装饰器会用__init__签名校验L85-L89get_defaults()返回当前类级默认值的深拷贝reset_defaults()清除全部类级默认值reset_defaults(param1, param2)只清除指定名称的默认值注意类级默认值按类相互独立——BrowserConfig.set_defaults()不影响CrawlerRunConfig反之亦然。默认值保存在内存中作用于进程生命周期。组合使用一个完整示例典型场景是为爬虫会话定义一个BrowserConfig再按每次调用的需要创建一个或多个CrawlerRunConfig与LLMConfigimport asyncio from crawl4ai import AsyncWebCrawler, BrowserConfig, CrawlerRunConfig, CacheMode, LLMConfig, LLMContentFilter, DefaultMarkdownGenerator from crawl4ai import JsonCssExtractionStrategy async def main(): # 1) 浏览器配置headless、更大视口、无代理 browser_conf BrowserConfig( headlessTrue, viewport_width1280, viewport_height720 ) # 2) 示例抽取策略 schema { name: Articles, baseSelector: div.article, fields: [ {name: title, selector: h2, type: text}, {name: link, selector: a, type: attribute, attribute: href} ] } extraction JsonCssExtractionStrategy(schema) # 3) 示例 LLM 内容过滤 gemini_config LLMConfig( providergemini/gemini-1.5-pro, api_token env:GEMINI_API_TOKEN ) # 用具体指令初始化 LLM 过滤器 filter LLMContentFilter( llm_configgemini_config, # 或你偏好的供应商 instruction Focus on extracting the core educational content. Include: - Key concepts and explanations - Important code examples - Essential technical details Exclude: - Navigation elements - Sidebars - Footer content Format the output as clean markdown with proper code blocks and headers. , chunk_token_threshold500, # 按需调整 verboseTrue ) md_generator DefaultMarkdownGenerator( content_filterfilter, options{ignore_links: True} ) # 4) 爬取运行配置跳过缓存、启用抽取 run_conf CrawlerRunConfig( markdown_generatormd_generator, extraction_strategyextraction, cache_modeCacheMode.BYPASS, ) async with AsyncWebCrawler(configbrowser_conf) as crawler: # 5) 执行爬取 result await crawler.arun(urlhttps://example.com/news, configrun_conf) if result.success: print(Extracted content:, result.extracted_content) else: print(Error:, result.error_message) if __name__ __main__: asyncio.run(main())要点回顾BrowserConfig只建一次并在AsyncWebCrawler(config...)中注入CrawlerRunConfig挂在每次arun(url, configrun_conf)调用上可自由切换缓存、抽取、等待策略LLMConfig则作为“零件”装进LLMContentFilter等策略对象里。进一步阅读完整参数列表含高级参数BrowserConfig, CrawlerRunConfig LLMConfig Reference可以探索的方向Custom Hooks Auth注入 JavaScript、处理登录表单Session Management复用页面、跨多次调用保持状态Magic Mode或Identity-based Crawling模拟用户行为对抗机器人检测Advanced Caching精细调整读/写缓存模式URL 级差异化配置arun_many。BrowserConfig、CrawlerRunConfig与LLMConfig分别回答了三个问题用哪个浏览器、以什么方式运行引擎、代理、User-Agent、隐身每次爬取如何行为缓存、超时、JS 注入、抽取策略用哪个 LLM 供应商模型、Token、温度、自定义端点。三者配合可以写出清晰、可维护的抓取代码需要更专门的行为时再查阅 参考文档 中的高级参数即可。【免费下载链接】crawl4ai Crawl4AI: Open-source LLM Friendly Web Crawler Scraper. Dont be shy, join here: https://discord.gg/jP8KfhDhyN项目地址: https://gitcode.com/GitHub_Trending/craw/crawl4ai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Crawl4AI 配置系统实战：BrowserConfig、CrawlerRunConfig 与 LLMConfig 三层协作详解
Crawl4AI 配置系统实战BrowserConfig、CrawlerRunConfig 与 LLMConfig 三层协作详解【免费下载链接】crawl4ai Crawl4AI: Open-source LLM Friendly Web Crawler Scraper. Dont be shy, join here: https://discord.gg/jP8KfhDhyN项目地址: https://gitcode.com/GitHub_Trending/craw/crawl4aiCrawl4AI 的灵活性来自三个配置类BrowserConfig决定浏览器如何启动与运行CrawlerRunConfig决定每一次爬取如何执行LLMConfig决定LLM 供应商如何接入。典型用法是为整个爬虫会话创建一个BrowserConfig再在每次调用arun()时传入一个新建或复用的CrawlerRunConfig按需搭配LLMConfig。读完本篇你将掌握这三类配置的全部常用参数、取值范围与默认值以及clone()、set_defaults()等辅助机制的源码级实现能够独立编写可运行、可维护的抓取配置代码。三大配置类的职责划分从 crawl4ai/async_configs.py 的源码结构看三类配置各自独立、按需组合BrowserConfig定义位置——控制浏览器引擎类型、headless 与否、代理、User-Agent、视口、持久化上下文等作用于浏览器/上下文生命周期通常在整个会话中只创建一次。CrawlerRunConfig定义位置——控制缓存、内容抽取、等待条件、JS 注入、截图/PDF 等作用于单次爬取操作每次arun()都可传入不同的配置。LLMConfig定义位置——控制 LLM 供应商、API Token、base URL 与重试退避策略供LLMExtractionStrategy、LLMContentFilter等策略对象消费。需要高级或冷门字段时可查阅完整参数参考 Configuration Parameters。BrowserConfig控制浏览器如何启动构造函数与核心参数速览BrowserConfig.__init__的完整签名crawl4ai/async_configs.py涵盖数十个参数以下按“浏览器类型 → 运行模式 → 网络身份 → 渲染性能”的顺序梳理最常用的字段class BrowserConfig: def __init__( browser_typechromium, headlessTrue, browser_modededicated, use_managed_browserFalse, cdp_urlNone, debugging_port9222, hostlocalhost, proxy_configNone, viewport_width1080, viewport_height600, verboseTrue, use_persistent_contextFalse, user_data_dirNone, cookiesNone, headersNone, user_agent( Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 Chrome/116.0.0.0 Safari/537.36 ), user_agent_mode, text_modeFalse, light_modeFalse, extra_argsNone, enable_stealthFalse, # ... 其他高级参数省略 ): ...关键字段逐项说明1.browser_type可选值chromium、firefox、webkit默认chromium。需要其他渲染引擎时在此指定。源码中当类型为firefox/webkit时会清空channel/chrome_channelL849-L851因为 Chrome 渠道参数只适用于 chromium 系浏览器。2.headlessTrue无头模式不可见浏览器False可视化模式方便调试。3.browser_mode决定浏览器初始化方式取值dedicated默认每次创建新的浏览器实例builtin使用后台常驻的内置 CDP 浏览器custom使用cdp_url提供的显式 CDP 连接也可用docker模式运行容器化隔离浏览器。从源码看L911-L929browser_mode会联动改写use_managed_browserbuiltin、docker、以及带cdp_url的custom模式都会自动置为Trueuse_persistent_contextTrue时同样强制use_managed_browserTrue。因此多数场景只需设置browser_mode一个字段。4.use_managed_browser与cdp_urluse_managed_browserTrue通过 Chrome DevTools ProtocolCDP启动/接管浏览器便于高级控制cdp_urlCDP 端点地址例如ws://localhost:9222/devtools/browser/两者由browser_mode自动协调一般不必手工同时设置。5.debugging_port与hostdebugging_port调试协议端口默认9222host浏览器连接主机默认localhost。6.proxy_config接受ProxyConfig对象、字符串或字典例如{ server: http://proxy.example.com:8080, username: ..., password: ... }不需要代理时保持None。源码会自动把 dict/str 归一化为ProxyConfigL856-L867旧的proxy字符串参数已被标记弃用传入时会产生UserWarning提示改用proxy_configL852-L853。7.viewport_width与viewport_height初始窗口尺寸默认1080×600。部分网站在不同视口下行为不同响应式布局、懒加载触发等。另有一个viewport字典参数设置后会覆盖两个宽度/高度字段L872-L874。8.device_scale_factor控制渲染的设备像素比DPR默认1.0。设为2.0可获得 Retina 级截图质量例如1920×1080视口产出3840×2160图像数值越高截图体积与渲染耗时按比例增长。9.verboseTrue时打印额外日志便于调试默认True。10.use_persistent_contextTrue时使用持久化浏览器配置档跨运行保留 cookies / localStorage通常配合user_data_dir指定目录。11.cookies与headers在上下文创建时注入初始 cookies 或全局 HTTP 头例如cookies[{name: session, value: abc123, domain: example.com}]。源码还会根据user_agent自动生成 client hints 并写入sec-ch-ua响应头L908-L909避免 UA 与指纹不一致被识别。12.user_agent与user_agent_modeuser_agent自定义 UA 字符串user_agent_moderandom从内置合法 UA 库随机生成源码中由ValidUAGenerator实现L900-L906可配合user_agent_generator_config细化生成条件有助于降低被反爬识别的概率。13.text_mode与light_modetext_modeTrue禁用图片等富媒体加载适合纯文本抓取提速light_modeTrue关闭部分后台特性以换取性能。14.avoid_ads与avoid_cssavoid_adsTrue在浏览器上下文层面拦截常见广告与追踪域Google Analytics、DoubleClick、Facebook、Hotjar 等降低网络开销与内存占用avoid_cssTrue拦截 CSS 文件.css、.less、.scss、.sass加载只取文本内容时更轻快两者默认均为Falseopt-in可互相组合也可与text_mode叠加。15.extra_args透传给底层浏览器的额外命令行参数如[--disable-extensions]。16.enable_stealthTrue时启用基于 playwright-stealth 的隐身模式修改浏览器指纹以规避基础机器人检测默认False推荐用于有反爬保护的站点。注意源码中的约束enable_stealth与browser_modebuiltin不能同时使用否则抛出ValueError——隐身模式要求独占的浏览器实例L931-L936。最小可运行示例from crawl4ai import AsyncWebCrawler, BrowserConfig browser_conf BrowserConfig( browser_typefirefox, headlessFalse, text_modeTrue ) async with AsyncWebCrawler(configbrowser_conf) as crawler: result await crawler.arun(https://example.com) print(result.markdown[:300])CrawlerRunConfig控制单次爬取如何执行构造函数与核心参数速览class CrawlerRunConfig: def __init__( word_count_threshold200, extraction_strategyNone, chunking_strategyRegexChunking(), markdown_generatorNone, cache_modeCacheMode.BYPASS, js_codeNone, c4a_scriptNone, wait_forNone, screenshotFalse, pdfFalse, capture_mhtmlFalse, # 位置与身份参数 localeNone, # e.g. en-US, fr-FR timezone_idNone, # e.g. America/New_York geolocationNone, # GeolocationConfig 对象 # 代理配置 proxy_configNone, proxy_rotation_strategyNone, # 页面交互参数 scan_full_pageFalse, scroll_delay0.2, wait_untildomcontentloaded, page_timeout60000, delay_before_return_html0.1, # URL 匹配参数 url_matcherNone, # 用于 URL 级差异化配置 match_modeMatchMode.OR, verboseTrue, streamFalse, # 为 arun_many() 启用流式处理 # ... 其他高级参数省略 ): ...当前源码中该构造函数实际包含 100 个参数crawl4ai/async_configs.py以下只聚焦高频字段。关键字段逐项说明1.word_count_threshold一个内容块进入后续处理前的最小单词数。注意默认值以当前版本为准源码签名为word_count_threshold: int MIN_WORD_THRESHOLD而 crawl4ai/config.py 中MIN_WORD_THRESHOLD 1。也就是说当前版本默认几乎不过滤短块若希望达到上文示例中 200 词的阈值效果应显式传入word_count_threshold200。站点存在大量短段落/短条目时可调低。2.extraction_strategy挂载结构化抽取策略的入口CSS、XPath、LLM 等若为None则不做结构化抽取只返回原始/清洗后的 HTML 与 Markdown。传入时会做类型校验非ExtractionStrategy实例直接抛出ValueErrorL1838-L1843。3.chunking_strategy抽取前对内容做切块的策略默认RegexChunking()同样会做类型校验。4.markdown_generator例如DefaultMarkdownGenerator(...)控制 HTML→Markdown 的转换方式。当前源码的默认值就是一个DefaultMarkdownGenerator()实例L1592传None也会回落到默认行为。5.cache_mode控制缓存行为ENABLED、BYPASS、DISABLED等枚举定义于 crawl4ai/cache_context.py默认CacheMode.BYPASS。旧的bypass_cache/disable_cache/no_cache_read/no_cache_write布尔参数仍可用但源码中已标注为 legacy 并建议使用cache_mode表达L1579-L1584。6.js_code、js_code_before_wait与c4a_scriptjs_code在wait_for完成之后、对完全加载的页面执行 JavaScriptjs_code_before_wait在wait_for之前执行用于触发wait_for随后要检测的加载行为c4a_script编译为 JavaScript 的 C4A 脚本三者都适合实现“Load More”按钮、点击展开等页面交互。7.wait_for抽取前等待的 CSS 或 JS 表达式常见写法wait_forcss:.main-loaded或wait_forjs:() window.loaded true。可配合wait_for_timeout指定等待超时缺省使用page_timeout。8.flatten_shadow_domTrue时在捕获 HTML 前把 Shadow DOM 内容展平进 light DOM并对 closed shadow root 强制打开对基于 Web ComponentsStencil、Lit、Shoelace 等构建的站点必不可少原理详见 Flattening Shadow DOM。9.screenshot、pdf与capture_mhtml分别为True时页面完全加载后捕获截图、PDF 或 MHTML 快照结果位于result.screenshotbase64、result.pdfbytes、result.mhtml字符串配合force_viewport_screenshotTrue只截取可视视口而非整页速度更快、图片更小。10. 位置参数Location Parameterslocale浏览器区域设置如en-US、fr-FR影响语言偏好timezone_id时区如America/New_York、Europe/Parisgeolocation通过GeolocationConfig(latitude48.8566, longitude2.3522, accuracy0.0)注入 GPS 坐标定义位置完整用法参见 Identity Based Crawling。11. 代理配置Proxy Configurationproxy_config单个ProxyConfig或list[ProxyConfig]——列表会按顺序尝试天然支持自动升级escalationproxy_rotation_strategy爬取过程中轮换代理的策略对象。12. 反机器人重试与兜底Anti-Bot Retry Fallbackmax_retries检测到拦截时的重试轮数默认0每轮会遍历proxy_config中的全部代理fallback_fetch_function最后手段的异步函数接收 URL、返回原始 HTML。完整机制见 Anti-Bot Fallback。13. 页面交互参数Page Interaction Parametersscan_full_pageTrue时滚动整页以触发全部懒加载内容scroll_delay滚动步长之间的延时秒默认0.2wait_until导航时的等待条件domcontentloaded、networkidle等默认domcontentloadedpage_timeout页面操作超时毫秒默认60000来自 config.py 的PAGE_TIMEOUTdelay_before_return_html获取最终 HTML 前的延时秒默认0.1。14.url_matcher与match_mode与arun_many()配合实现 URL 级差异化配置url_matcher可设为 glob 模式、函数或它们的列表match_modeMatchMode.OR/MatchMode.AND定义位置控制多个模式的组合方式示例见 URL-Specific Configurations。15.verbose记录额外运行时细节若在BrowserConfig中也设为True两者日志会叠加。16.streamTrue时为arun_many()启用流式模式URL 完成即处理结果无需等待全部 URL 结束便于增量处理大批量任务。clone()低成本派生配置变体CrawlerRunConfig提供clone(**kwargs)实现位置来创建配置变体# 创建基础配置 base_config CrawlerRunConfig( cache_modeCacheMode.ENABLED, word_count_threshold200, wait_untilnetworkidle ) # 派生不同用途的变体 stream_config base_config.clone( streamTrue, # 启用流式模式 cache_modeCacheMode.BYPASS ) debug_config base_config.clone( page_timeout120000, # 调试时用更长超时 verboseTrue )clone()的语义生成一个保留全部原设置的新实例仅更新传入的参数原配置保持不变——适合“一份基础配置 多个场景变体”的写法避免在每个调用点重复罗列全部参数。LLMConfig接入 LLM 供应商LLMConfig的字段较少但每条都影响面很大实现位置provider指定 LLM 供应商/模型。当前源码支持的取值定义在 crawl4ai/config.py 的PROVIDER_MODELS中包括ollama/llama3、groq/llama3-70b-8192、groq/llama3-8b-8192、openai/gpt-4o-mini、openai/gpt-4o、openai/o1-mini、openai/o1-preview、openai/o3-mini、openai/o3-mini-high、anthropic/claude-3-haiku-20240307、anthropic/claude-3-opus-20240229、anthropic/claude-3-sonnet-20240229、anthropic/claude-3-5-sonnet-20240620、gemini/gemini-pro、gemini/gemini-1.5-pro、gemini/gemini-2.0-flash、gemini/gemini-2.0-flash-exp、gemini/gemini-2.0-flash-lite-preview-02-05、deepseek/deepseek-chat。当前源码的兜底默认值是DEFAULT_PROVIDER openai/gpt-4oconfig.py若传入的 provider 前缀不在已知列表中会回退到该默认值。api_token可选项。三种提供方式显式传字符串如api_tokensk-...使用env:前缀从环境变量读取源码逻辑是截取前 4 个字符后调用os.getenv()L2264-L2265因此推荐写成api_tokenenv:GROQ_API_KEYenv:后紧跟变量名完全不传源码按 provider 前缀匹配PROVIDER_MODELS_PREFIXESopenai→OPENAI_API_KEY、gemini→GEMINI_API_KEY、groq→GROQ_API_KEY等config.py自动从对应环境变量取 Key。base_url供应商存在自定义端点自建网关、兼容 API 等时指定。重试/退避控制可选backoff_base_delay默认2秒供应商返回限流响应后、首次重试前的基础延迟backoff_max_attempts默认3总尝试次数首次调用 重试超过后请求以错误形式上抛backoff_exponential_factor默认2重试延迟的增长因子delay base_delay * factor^attempt这些值会转发给共享的perform_completion_with_backoff辅助函数保证所有消费LLMConfig的策略遵循同一套限流策略。llm_config LLMConfig( provideropenai/gpt-4o-mini, api_tokenos.getenv(OPENAI_API_KEY), backoff_base_delay1, # 可选 backoff_max_attempts5, # 可选 backoff_exponential_factor3, # 可选 )除上述字段外LLMConfig还支持temperature、max_tokens、top_p、frequency_penalty、presence_penalty、stop、n等采样参数签名位置默认均为None交给供应商默认值。类级默认值set_defaults() 机制BrowserConfig与CrawlerRunConfig均支持通过set_defaults()设置类级默认覆盖由_with_defaults装饰器实现crawl4ai/async_configs.py。这在服务端/云部署中非常有用所有实例共享同一组基础设置时只需在启动时设置一次而不是在每个调用点重复。参数解析优先级为显式传参 类级用户默认值 硬编码默认值L43-L50。from crawl4ai import BrowserConfig, CrawlerRunConfig # 应用启动时 —— 只需一次 BrowserConfig.set_defaults( cache_cdp_connectionTrue, cdp_close_delay0, create_isolated_contextTrue, ) CrawlerRunConfig.set_defaults(verboseFalse) # 之后新建的实例自动继承这些默认值 cfg BrowserConfig(cdp_urlws://localhost:9222) # → cache_cdp_connectionTrue, cdp_close_delay0, create_isolated_contextTrue # 显式值仍然优先 cfg BrowserConfig(cdp_urlws://localhost:9222, cache_cdp_connectionFalse) # → cache_cdp_connectionFalse显式值覆盖类级默认值两个类都提供以下方法方法说明set_defaults(**kwargs)设置类级默认值。参数名无效时抛出ValueError装饰器会用__init__签名校验L85-L89get_defaults()返回当前类级默认值的深拷贝reset_defaults()清除全部类级默认值reset_defaults(param1, param2)只清除指定名称的默认值注意类级默认值按类相互独立——BrowserConfig.set_defaults()不影响CrawlerRunConfig反之亦然。默认值保存在内存中作用于进程生命周期。组合使用一个完整示例典型场景是为爬虫会话定义一个BrowserConfig再按每次调用的需要创建一个或多个CrawlerRunConfig与LLMConfigimport asyncio from crawl4ai import AsyncWebCrawler, BrowserConfig, CrawlerRunConfig, CacheMode, LLMConfig, LLMContentFilter, DefaultMarkdownGenerator from crawl4ai import JsonCssExtractionStrategy async def main(): # 1) 浏览器配置headless、更大视口、无代理 browser_conf BrowserConfig( headlessTrue, viewport_width1280, viewport_height720 ) # 2) 示例抽取策略 schema { name: Articles, baseSelector: div.article, fields: [ {name: title, selector: h2, type: text}, {name: link, selector: a, type: attribute, attribute: href} ] } extraction JsonCssExtractionStrategy(schema) # 3) 示例 LLM 内容过滤 gemini_config LLMConfig( providergemini/gemini-1.5-pro, api_token env:GEMINI_API_TOKEN ) # 用具体指令初始化 LLM 过滤器 filter LLMContentFilter( llm_configgemini_config, # 或你偏好的供应商 instruction Focus on extracting the core educational content. Include: - Key concepts and explanations - Important code examples - Essential technical details Exclude: - Navigation elements - Sidebars - Footer content Format the output as clean markdown with proper code blocks and headers. , chunk_token_threshold500, # 按需调整 verboseTrue ) md_generator DefaultMarkdownGenerator( content_filterfilter, options{ignore_links: True} ) # 4) 爬取运行配置跳过缓存、启用抽取 run_conf CrawlerRunConfig( markdown_generatormd_generator, extraction_strategyextraction, cache_modeCacheMode.BYPASS, ) async with AsyncWebCrawler(configbrowser_conf) as crawler: # 5) 执行爬取 result await crawler.arun(urlhttps://example.com/news, configrun_conf) if result.success: print(Extracted content:, result.extracted_content) else: print(Error:, result.error_message) if __name__ __main__: asyncio.run(main())要点回顾BrowserConfig只建一次并在AsyncWebCrawler(config...)中注入CrawlerRunConfig挂在每次arun(url, configrun_conf)调用上可自由切换缓存、抽取、等待策略LLMConfig则作为“零件”装进LLMContentFilter等策略对象里。进一步阅读完整参数列表含高级参数BrowserConfig, CrawlerRunConfig LLMConfig Reference可以探索的方向Custom Hooks Auth注入 JavaScript、处理登录表单Session Management复用页面、跨多次调用保持状态Magic Mode或Identity-based Crawling模拟用户行为对抗机器人检测Advanced Caching精细调整读/写缓存模式URL 级差异化配置arun_many。BrowserConfig、CrawlerRunConfig与LLMConfig分别回答了三个问题用哪个浏览器、以什么方式运行引擎、代理、User-Agent、隐身每次爬取如何行为缓存、超时、JS 注入、抽取策略用哪个 LLM 供应商模型、Token、温度、自定义端点。三者配合可以写出清晰、可维护的抓取代码需要更专门的行为时再查阅 参考文档 中的高级参数即可。【免费下载链接】crawl4ai Crawl4AI: Open-source LLM Friendly Web Crawler Scraper. Dont be shy, join here: https://discord.gg/jP8KfhDhyN项目地址: https://gitcode.com/GitHub_Trending/craw/crawl4ai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考