Crawl4AI 懒加载图片抓取实战wait_for_images 与 scan_full_page 全解析【免费下载链接】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在 Crawl4AI 中很多现代网站会随滚动懒加载lazy-load图片——页面初次渲染时只有少量真实img其余是占位符。如果直接抓取这些图片不会出现在result.media里。本文基于仓库文档 懒加载指南讲透三个核心配置项wait_for_images、scan_full_page、scroll_delay的用法与底层实现读完你可以稳定抓取整个图库/信息流中的懒加载图片并了解每个参数在源码中的真实执行路径。一、三个核心配置项及其默认值参数类型默认值作用wait_for_imagesboolFalse等待所有img元素加载完成后再提取内容scan_full_pageboolFalse让爬虫从页面顶部滚动到底部触发懒加载scroll_delayfloat0.2秒每一步滚动之间的暂停时间给站点留出加载图片的时间max_scroll_stepsint | NoneNone全页扫描的最大滚动步数防止无限滚动页卡死这四个参数的定义可以在 CrawlerRunConfig 构造函数 中直接确认# crawl4ai/async_configs.py节选 wait_until: str domcontentloaded, page_timeout: int PAGE_TIMEOUT, wait_for: str None, wait_for_images: bool False, delay_before_return_html: float 0.1, ... scan_full_page: bool False, scroll_delay: float 0.2, max_scroll_steps: Optional[int] None,官方参数说明 对这三个参数给出了与本文一致的语义wait_for_images为True时在提取内容前等待图片加载scan_full_page为True时滚动整个页面以加载所有内容scroll_delayscan_full_pageTrue时每一步滚动之间的秒级延迟默认0.2max_scroll_steps全页扫描期间的最大滚动步数None表示一直滚动直到整个页面加载完默认None。二、完整示例确保懒加载图片出现在结果中下面是文档给出的可运行示例配合注释说明每一步的意图import asyncio from crawl4ai import AsyncWebCrawler, CrawlerRunConfig, BrowserConfig from crawl4ai.async_configs import CacheMode async def main(): config CrawlerRunConfig( # 强制等待图片完全加载后再收尾 wait_for_imagesTrue, # 方案 1自动滚动整页以触发懒加载 scan_full_pageTrue, # 让爬虫尝试滚动整个页面 scroll_delay0.5, # 每步滚动之间的延迟秒 # 方案 2如果站点用 Load More 或 JS 事件触发图片 # 还可以在此处指定 js_code 或 wait_for 逻辑。 cache_modeCacheMode.BYPASS, # 绕过缓存保证抓到最新图片 verboseTrue ) async with AsyncWebCrawler(configBrowserConfig(headlessTrue)) as crawler: result await crawler.arun(https://www.example.com/gallery, configconfig) if result.success: images result.media.get(images, []) print(Images found:, len(images)) for i, img in enumerate(images[:5]): print(f[Image {i}] URL: {img[src]}, Score: {img.get(score,N/A)}) else: print(Error:, result.error_message) if __name__ __main__: asyncio.run(main())关键点解释wait_for_imagesTrue爬虫在最终确定 HTML 前会尝试确保图片加载完毕源码行为见下一节scan_full_pageTrue爬虫会从顶部向底部逐步滚动每一步滚动都会触发视口内懒加载逻辑scroll_delay0.5每步滚动后暂停 0.5 秒帮助站点在下载/渲染图片后再继续结果通过result.media[images]获取每个条目含src与score字段可与image_score_threshold配合做质量过滤。三、源码解析wait_for_images到底做了什么在 AsyncCrawlerStrategy 的内容加载阶段可以清楚看到wait_for_images的执行路径# crawl4ai/async_crawler_strategy.py节选 if not self.browser_config.text_mode and ( config.wait_for_images or config.adjust_viewport_to_content ): await page.wait_for_load_state(domcontentloaded) await asyncio.sleep(0.1) # Check for image loading with improved error handling images_loaded await self.csp_compliant_wait( page, () Array.from(document.getElementsByTagName(img)).every(img img.complete), timeout1000, ) if not images_loaded and self.logger: self.logger.warning( messageSome images failed to load within timeout, tagSCRAPE, )从源码结构看有三个值得注意的实现细节判定标准是img.complete并非等待所有图片字节 100% 下载完成而是轮询检查页面上每个img元素的complete属性1 秒超时会发出Some images failed to load within timeout警告。这意味着它适合图片是否开始加载的场景而极慢网络下的超大图仍可能被跳过text_mode下会被跳过BrowserConfig(text_modeTrue)的纯文本模式不做图片等待这是合理的资源优化与adjust_viewport_to_content共用同一入口两者任一为True都会先进入domcontentloaded等待说明该分支是整个渲染等待的总闸口。四、源码解析scan_full_page的滚动算法scan_full_page触发的滚动逻辑集中在_handle_full_page_scan调用点在内容处理流程 中并受page_timeout约束# crawl4ai/async_crawler_strategy.py节选 if config.scan_full_page: scan_timeout (config.page_timeout or 30000) / 1000 # ms to seconds try: await asyncio.wait_for( self._handle_full_page_scan(page, config.scroll_delay, config.max_scroll_steps), timeoutscan_timeout, ) except asyncio.TimeoutError: self.logger.warning( messageFull page scan timed out after {timeout}s, continuing with partial scroll, tagPAGE_SCAN, params{timeout: scan_timeout}, )滚动算法本身分五步源码 docstring 有明确描述获取视口高度viewport_height先滚动一个视口高度触发首屏外的懒加载通过get_page_dimensions获取页面总高度total_height循环滚动viewport_height步每步滚动后都会重新测量页面高度——如果new_height total_height则更新total_height这正是它能追上动态增长页面的关键到底后先滚回顶部、再滚到最底部确保首尾区域的懒加载元素都进入过视口。# crawl4ai/async_crawler_strategy.py节选 scroll_step_count 0 while current_position total_height: if max_scroll_steps is not None and scroll_step_count max_scroll_steps: break current_position min(current_position viewport_height, total_height) await self.safe_scroll(page, 0, current_position, delayscroll_delay) scroll_step_count 1 dimensions await self.get_page_dimensions(page) new_height dimensions[height] if new_height total_height: total_height new_height还有两处容易踩坑的边界行为max_scroll_steps的双默认值陷阱配置层 的默认值是Nonedocstring 写的是一直滚动到整页加载完但执行层 在收到None时会兜底为 10 步Default to 10 steps to prevent infinite scroll on dynamic pages。也就是说实际运行时不传max_scroll_steps的scan_full_page最多只滚 10 个视口高度。对超长页面需要显式传入更大的max_scroll_steps否则扫全页实际只扫了前 10 屏步数上限有安全钳制对不受信来源构造的配置参数钳制逻辑 会把max_scroll_steps限制在_MAX_SCROLL_STEPS 1000以内防止外部请求制造超长滚动任务。滚动是怎么执行的每一步滚动走safe_scroll先用 CSP 兼容的方式执行window.scrollTo不直接内联字符串注入滚动成功后再wait_for_timeout(delay * 1000)——所以scroll_delay直接决定了每次滚动后等待渲染的时长。滚动后源码还会校验实际落点与目标位置的delta滚动是否真正生效是有反馈的。五、与媒体过滤、域名排除的组合懒加载逻辑可以与常规的媒体/链接过滤参数自由叠加config CrawlerRunConfig( wait_for_imagesTrue, scan_full_pageTrue, scroll_delay0.5, # 只保留主域图片过滤外部图片 exclude_external_imagesTrue, # 从链接结果中排除特定域名 exclude_domains[spammycdn.com], )这样爬虫会先物理滚动整页触发懒加载最终result.media与result.links中只保留主域图片和非排除域名的链接。这些过滤参数的构造入口同样在 CrawlerRunConfigexclude_external_images、exclude_all_images、exclude_social_media_domains、exclude_domains等。六、场景选择与排错清单文档给出的排错建议Tips Troubleshooting结合源码可以整理成一张决策表场景建议做法图片随滚动出现普通懒加载scan_full_pageTruescroll_delay0.5wait_for_imagesTrue超长页面 / 无限滚动scan_full_page资源开销大改用 hooks 页面交互 循环点击 Load More并注意显式传max_scroll_steps控制步数Twitter/Instagram 风格虚拟滚动用 Virtual Scroll 专项能力仓库内有现成示例 virtual_scroll_example.py分批加载导致漏图增大scroll_delay或用js_code/hooks 循环执行多次部分滚动占位图在某个事件后才变真图wait_forcss:img.loaded或自定义 JSwait_for配合js_code_before_wait先触发加载疑似缓存导致漏新图设置cache_modeCacheMode.BYPASS强制重新抓取排错时还可以利用verboseTrue观察日志标签滚动相关警告会打出PAGE_SCAN、SCRAPE等 tag见上文源码片段能直接定位是图片超时未加载还是全页扫描超时。七、小结Crawl4AI 对懒加载图片的处理是一个三层配合机制wait_for_images负责加载完成判定基于img.complete轮询scan_full_page负责触发加载分步滚动 动态高度重测scroll_delay控制触发节奏。理解 执行层实现 后可以避开的最大陷阱是不显式设置max_scroll_steps时实际只滚 10 步超长页面务必显式放大该值。再叠加exclude_external_images、exclude_domains等过滤参数与CacheMode.BYPASS就构成了一套完整的链接与媒体抓取策略。【免费下载链接】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），仅供参考