Crawl4AI 前缀式输入机制详解用统一 arun 接口爬取 Web 页面、本地 HTML 文件与原始 HTML 字符串【免费下载链接】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 的AsyncWebCrawler.arun()通过“统一url参数 前缀识别”这一设计让 Web 地址、本地 HTML 文件、原始 HTML 字符串三类输入走同一套爬取管线。读完本篇你将掌握http://、file://、raw:三种前缀的正确用法、CrawlerRunConfig在本地场景下的关键配置如CacheMode、base_url并能从源码层面理解每种输入在 Crawl4AI 内部的真实执行路径——包括何时直接读文件、何时仍会启动浏览器以及为什么raw:输入永远不进缓存。三种输入形式一览Crawl4AI 对传入arun(url...)的参数只做前缀判断据此决定后续处理路径。官方文档 local-files.md 中演示了以下三种形式AsyncWebCrawler.arun 的文档字符串 同样声明其接受的输入为 “http://, https://, file://, or raw:”输入前缀适用场景典型写法http:///https://爬取在线网页走完整的浏览器导航流程https://en.wikipedia.org/wiki/applefile://处理本地保存的 HTML 文件file:///path/to/apple.htmlraw:源码同时兼容raw://直接处理内存中的原始 HTML 字符串raw:htmlbody.../body/html注意file://后面紧跟的是绝对路径Linux/macOS 上路径以/开头因此实际形如file:///home/user/apple.htmlWindows 上则是file://C:/...。爬取 Web URL在线页面的用法是基准场景构造CrawlerRunConfig示例中使用CacheMode.BYPASS强制绕过缓存传入https://地址即可import asyncio from crawl4ai import AsyncWebCrawler, CacheMode, CrawlerRunConfig async def crawl_web(): config CrawlerRunConfig(cache_modeCacheMode.BYPASS) async with AsyncWebCrawler() as crawler: result await crawler.arun( urlhttps://en.wikipedia.org/wiki/apple, configconfig ) if result.success: print(Markdown Content:) print(result.markdown) else: print(fFailed to crawl: {result.error_message}) asyncio.run(crawl_web())此类 URL 会进入 _crawl_web() 的page.goto()导航流程返回真实的状态码、响应头与重定向信息。爬取本地 HTML 文件file://前缀对已保存的 HTML 文件例如离线归档、API 返回的原始响应、测试 fixture只需给绝对路径加上file://前缀import asyncio from crawl4ai import AsyncWebCrawler, CacheMode, CrawlerRunConfig async def crawl_local_file(): local_file_path /path/to/apple.html # 替换为你的文件绝对路径 file_url ffile://{local_file_path} config CrawlerRunConfig(cache_modeCacheMode.BYPASS) async with AsyncWebCrawler() as crawler: result await crawler.arun(urlfile_url, configconfig) if result.success: print(Markdown Content from Local File:) print(result.markdown) else: print(fFailed to crawl local file: {result.error_message}) asyncio.run(crawl_local_file())从 AsyncCrawlerStrategy 的前缀分派逻辑 可以看到file://输入的处理分两条路径快速路径默认不启动浏览器页面导航直接以 UTF-8 读取文件内容包装成AsyncCrawlResponse返回status_code固定为 200response_headers为空浏览器路径若配置中启用了任何需要浏览器能力的选项如js_code、screenshot、pdf、simulate_user、magic等则转入_crawl_web()内部改用page.set_content(html_content, wait_untilconfig.wait_until)把文件内容“注入”页面而不是网络导航见 set_content 分支。这意味着本地文件同样可以叠加 JS 执行、截图、全页扫描等浏览器级能力代价是启动浏览器的开销。爬取原始 HTML 字符串raw:前缀当 HTML 已经在内存中字符串、变量、API 响应体时用raw:前缀直接喂给arun省去“先写文件再读文件”的中间步骤import asyncio from crawl4ai import AsyncWebCrawler, CacheMode from crawl4ai.async_configs import CrawlerRunConfig async def crawl_raw_html(): raw_html htmlbodyh1Hello, World!/h1/body/html raw_html_url fraw:{raw_html} config CrawlerRunConfig(cache_modeCacheMode.BYPASS) async with AsyncWebCrawler() as crawler: result await crawler.arun(urlraw_html_url, configconfig) if result.success: print(Markdown Content from Raw HTML:) print(result.markdown) else: print(fFailed to crawl raw HTML: {result.error_message}) asyncio.run(crawl_raw_html())源码对raw:与raw://两种写法都做了兼容剥离前缀后剩下的部分即为 HTML 原文见 前缀剥离逻辑。与file://相同raw:输入默认走无浏览器的快速路径只有需要浏览器能力时才经set_content()注入。base_url让raw:/file://内容里的相对链接可解析本地/原始 HTML 中的资源引用如a href...、img src...往往是相对路径缺少“页面所在地址”就无法正确解析。Crawl4AI 为此在CrawlerRunConfig中提供了base_url参数其注释明确写着 “Base URL for markdown link resolution (used with raw: HTML)”见 async_configs.py 第 1687 行。结合源码行为可以说明其完整语义raw:/file://输入在快速路径和浏览器路径下结果的redirected_url都直接取自config.base_url快速路径、set_content 分支而非浏览器page.url后者会是about:blank。因此推荐写法config CrawlerRunConfig( cache_modeCacheMode.BYPASS, base_urlhttps://en.wikipedia.org/wiki/apple, # 供链接解析与结果元数据使用 ) result await crawler.arun(urlfraw:{html_content}, configconfig) print(result.redirected_url) # - https://en.wikipedia.org/wiki/apple相关行为在 test_raw_html_redirected_url.py 与 test_raw_html_browser.py、test_raw_html_edge_cases.py 中有对应测试覆盖。为什么示例统一使用CacheMode.BYPASSCacheMode的完整枚举定义在 cache_context.pyENABLED读写、DISABLED不缓存、READ_ONLY、WRITE_ONLY、BYPASS本次操作完全绕过缓存。关键在于 CacheContext 中的可缓存性判断self.is_cacheable url.startswith((http://, https://, file://)) self.is_web_url url.startswith((http://, https://)) self.is_local_file url.startswith(file://) self.is_raw_html url.startswith(raw:)由此可得三个事实raw:字符串永远不读也不写缓存——把一整段 HTML 作为缓存键既不划算也不可复现这是有意设计file://输入是可以被缓存的同一路径第二次爬取可能直接命中缓存这正是文档示例中本地文件与raw:场景都显式传cache_modeCacheMode.BYPASS的原因保证每次拿到的是最新文件内容若未指定arun默认回退到CacheMode.ENABLED见 arun 默认值逻辑。完整示例三步一致性验证脚本local-files.md 给出的综合脚本演示了一个很有实战价值的用法同一份 HTML 分别经 Web 爬取、本地文件、原始字符串三条路径转换用 Markdown 长度断言三者输出一致可用于验证自己的内容处理管线内容过滤、Markdown 生成参数在离线/在线场景下行为等价import os import sys import asyncio from pathlib import Path from crawl4ai import AsyncWebCrawler, CacheMode, CrawlerRunConfig async def main(): wikipedia_url https://en.wikipedia.org/wiki/apple script_dir Path(__file__).parent html_file_path script_dir / apple.html async with AsyncWebCrawler() as crawler: # Step 1: 爬取 Web URL print(\n Step 1: Crawling the Wikipedia URL ) web_config CrawlerRunConfig(cache_modeCacheMode.BYPASS) result await crawler.arun(urlwikipedia_url, configweb_config) if not result.success: print(fFailed to crawl {wikipedia_url}: {result.error_message}) return with open(html_file_path, w, encodingutf-8) as f: f.write(result.html) web_crawl_length len(result.markdown) print(fLength of markdown from web crawl: {web_crawl_length}\n) # Step 2: 从本地 HTML 文件爬取 print( Step 2: Crawling from the Local HTML File ) file_url ffile://{html_file_path.resolve()} file_config CrawlerRunConfig(cache_modeCacheMode.BYPASS) local_result await crawler.arun(urlfile_url, configfile_config) if not local_result.success: print(fFailed to crawl local file {file_url}: {local_result.error_message}) return local_crawl_length len(local_result.markdown) assert web_crawl_length local_crawl_length, Markdown length mismatch print(Markdown length matches between web and local file crawl.\n) # Step 3: 使用原始 HTML 字符串爬取 print( Step 3: Crawling Using Raw HTML Content ) with open(html_file_path, r, encodingutf-8) as f: raw_html_content f.read() raw_html_url fraw:{raw_html_content} raw_config CrawlerRunConfig(cache_modeCacheMode.BYPASS) raw_result await crawler.arun(urlraw_html_url, configraw_config) if not raw_result.success: print(fFailed to crawl raw HTML content: {raw_result.error_message}) return raw_crawl_length len(raw_result.markdown) assert web_crawl_length raw_crawl_length, Markdown length mismatch print(Markdown length matches between web and raw HTML crawl.\n) print(All tests passed successfully!) if html_file_path.exists(): os.remove(html_file_path) if __name__ __main__: asyncio.run(main())脚本的要点result.html原样落盘Web 爬取拿到的result.html就是后续两步的输入来源保证三条路径处理的是同一份 DOM路径必须先resolve()file://拼接的是绝对路径相对路径直接拼接会导致源码中os.path.exists检查失败并抛出FileNotFoundError长度断言三次 Markdown 长度相等说明raw:/file://的无浏览器快速路径与page.goto()全流程产出的转换结果等价前提是均未使用依赖运行时网络的浏览器级特性如懒加载滚动、JS 注入改写 DOM 等。源码纵深一次arun调用在本地输入下的完整链路把上文散落的证据串起来一条raw:或file://请求在 Crawl4AI 内的处理链路如下以 async_crawler_strategy.py 为主入口校验arun 校验url为非空字符串默认缓存模式为ENABLED并创建CacheContext由于raw:的is_cacheable为False读缓存分支直接被跳过前缀分派AsyncCrawlerStrategy.arun依次匹配http:///https:///view-source:→_crawl_web()file:///raw:///raw:→ 本地处理否则抛出ValueError明确提示 “URL must start with http://, https://, file://, or raw:”是否需要浏览器本地分支会检查process_in_browser、screenshot、pdf、js_code、wait_for、simulate_user、magic、capture_console_messages等约十余个配置项needs_browser 判定任一为真则转入完整浏览器管线快速路径file://读取磁盘文件UTF-8raw:/raw://直接截取前缀后的字符串构造AsyncCrawlResponsestatus_code200、redirected_urlconfig.base_url后直接返回全程不接触浏览器浏览器路径若需浏览器_crawl_web()检测到本地前缀后改用page.set_content()注入内容status_code同样置 200JS 执行、截图、console/网络捕获等能力均可正常生效返回前特意保留redirected_url为base_url而不取page.url因为注入内容的页面地址是about:blank见 redirected_url 保护逻辑。这条链路的工程含义是file://与raw:在结果元数据上与 Web URL 有所区别状态码恒为 200、无真实响应头、重定向地址来自base_url但内容转换管线HTML → 清洗 → Markdown → 内容筛选 → 结构化结果完全共用因此三类输入产出的result.markdown、result.links、result.media等字段结构一致。使用建议与注意事项何时选哪种前缀在线抓取用https://有落盘文件、且不需要浏览器能力时优先file://省去把大 HTML 拼进字符串HTML 已在内存中如来自另一 API、测试夹具时用raw:性能最省本地输入下缓存要显式控制file://输入默认可能被缓存重复处理会读到旧数据离线批处理建议显式cache_modeCacheMode.BYPASS或DISABLEDraw:则天然不缓存相对链接解析依赖base_url只要 HTML 内含相对href/src无论file://还是raw:都应设置base_url否则链接字段可能无法还原为完整 URL需要 JS 运行时再考虑浏览器若目标 HTML 依赖 JS 渲染SPA、动态加载纯raw:/file://快速路径拿不到渲染后内容此时显式开启js_code、wait_for等选项让 Crawl4AI 自动转入浏览器管线即可错误处理file://指向不存在的文件会抛FileNotFoundErrorarun层面建议始终检查result.success并输出result.error_message。小结Crawl4AI 通过前缀约定把“从哪里拿 HTML”从爬取流程中解耦出来http(s)://、file://、raw:三种输入共享同一个url参数与同一套CrawlerRunConfig底层由 前缀分派逻辑 决定走网络导航、磁盘读取还是内存注入并由 CacheContext 统一裁决缓存行为。掌握这一机制后你可以用同一段代码同时处理线上页面与离线快照为测试、归档回放、内容管线一致性校验等场景打下基础进一步阅读可从 test_raw_html_browser.py、test_raw_html_edge_cases.py 等测试文件入手查看各种边界情形的预期行为。【免费下载链接】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），仅供参考