Crawl4AI 超长页面截图与 PDF 导出实战：从 PDF 优先策略到滚动参数调优

Crawl4AI 超长页面截图与 PDF 导出实战从 PDF 优先策略到滚动参数调优【免费下载链接】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 官方示例文档 full_page_screenshot_and_pdf_export.md系统讲解如何对超长网页如大型 Wikipedia 词条可靠地获取整页截图与 PDF 快照。读完后你将掌握pdf、screenshot、scroll_delay、force_viewport_screenshot、screenshot_height_threshold等参数的配合使用方式并能从源码层面理解 Crawl4AI 的截图决策链viewport 判定、分段滚动、图像拼接、PDF 转图以及各失败分支的降级行为。为什么超长页面的整页截图很难做对非常长的网页做传统整页截图通常会遇到三类问题渲染耗时长导致超时、内存压力过大导致失败、以及视口放大后响应式 CSS 重排造成的样式失真。因此 Crawl4AI 引入了一个新思路先把页面导出为 PDF再把 PDF 转为高质量图片让浏览器内置的 PDF 渲染引擎承担最重的工作。官方文档给出的核心收益可靠性ReliabilityPDF 导出不会超时且与页面长度无关通用性Versatility一次抓取同时拿到 PDF 和截图无需重新加载或重复处理页面性能Performance跳过手动滚动与图像拼接逻辑降低复杂度与运行时开销。同时当没有 PDF 可用时Crawl4AI 会退回到“滚动分段截图 拼接”的兜底方案通过scroll_delay控制滚动节奏适配懒加载内容。一次抓取同时拿到 PDF 与截图下面是官方示例的完整代码pdfTrue与screenshotTrue同时开启抓取完成后result.pdf是原始 PDF 字节流result.screenshot是 base64 编码的图片import os import sys import asyncio from crawl4ai import AsyncWebCrawler, CacheMode, CrawlerRunConfig # Adjust paths as needed parent_dir os.path.dirname(os.path.dirname(os.path.abspath(__file__))) sys.path.append(parent_dir) __location__ os.path.realpath(os.path.join(os.getcwd(), os.path.dirname(__file__))) async def main(): async with AsyncWebCrawler() as crawler: # Request both PDF and screenshot result await crawler.arun( urlhttps://en.wikipedia.org/wiki/List_of_common_misconceptions, configCrawlerRunConfig( cache_modeCacheMode.BYPASS, pdfTrue, screenshotTrue ) ) if result.success: # Save screenshot if result.screenshot: from base64 import b64decode with open(os.path.join(__location__, screenshot.png), wb) as f: f.write(b64decode(result.screenshot)) # Save PDF if result.pdf: with open(os.path.join(__location__, page.pdf), wb) as f: f.write(result.pdf) if __name__ __main__: asyncio.run(main())文档中描述的底层流程为Crawl4AI 导航到目标页面若pdfTrue将当前页面导出为完整 PDF无论页面多长都包含全部内容若screenshotTrue且已有 PDF直接把 PDF 第一页转换为图片——不重复加载、不滚动最终得到可用的 PDF 和/或截图。源码印证媒体导出发生在 HTML 提取之后在抓取主流程中PDF / MHTML / 截图的生成统一放在before_return_html钩子之后位于 async_crawler_strategy.py 的这段逻辑if config.pdf: pdf_data await self.export_pdf(page) if config.capture_mhtml: mhtml_data await self.capture_mhtml(page) if config.screenshot: if config.screenshot_wait_for: await asyncio.sleep(config.screenshot_wait_for) screenshot_data await self.take_screenshot( page, screenshot_height_thresholdconfig.screenshot_height_threshold, force_viewport_screenshotconfig.force_viewport_screenshot, scan_full_pageconfig.scan_full_page, scroll_delayconfig.scroll_delay )可以看到三个开关相互独立、顺序执行screenshot_wait_for会在截图前额外等待指定秒数适合等待动画或字体加载完成的场景。PDF 导出本身的实现非常薄见 export_pdfasync def export_pdf(self, page: Page) - bytes: pdf_data await page.pdf(print_backgroundTrue) return pdf_dataprint_backgroundTrue保证页面的背景色与渐变样式被打印进 PDF。截图决策链从源码看 take_screenshot 的三条路径截图并不是“无脑整页截图”take_screenshot会根据参数与页面形态做分支决策核心分发逻辑在 async_crawler_strategy.py# Check if viewport-only screenshot is forced force_viewport kwargs.get(force_viewport_screenshot, False) scan_full_page kwargs.get(scan_full_page, True) if force_viewport or not scan_full_page: # Use viewport-only screenshot return await self.take_screenshot_naive(page) need_scroll await self.page_need_scroll(page) if not need_scroll: # Page is short enough, just take a screenshot return await self.take_screenshot_naive(page) else: # Page is too long, try to take a full-page screenshot return await self.take_screenshot_scroller(page, **kwargs)三条路径的含义视口路径naive显式设置force_viewport_screenshotTrue或页面高度不超过视口page_need_scroll判定为否直接调用page.screenshot(full_pageFalse)见 take_screenshot_naive。滚动拼接路径scroller页面过高且需要整页时走 take_screenshot_scroller。PDF 转图路径take_screenshot_from_pdf 提供把 PDF 第一页转成 JPEG base64 的能力。需要说明的是从当前仓库源码结构看在长页面分支中该调用位于一行被注释的代码里# return await self.take_screenshot_from_pdf(await self.export_pdf(page))即当前版本实际走的是 scroller 分段拼接文档描述的“PDF 转图”能力由take_screenshot_from_pdf方法实现并保留且当pdfTrue时 PDF 数据本身始终会随结果返回你可以自行离线转换。page_need_scroll的判定逻辑也很直白见 page_need_scroll比较document.documentElement.scrollHeight与window.innerHeight前者更大才需要滚动判定失败时出于安全考虑默认返回True。分段拼接的细节冻结尺寸、扩大视口、逐段截取take_screenshot_scroller是整个功能中最值得细读的一段它依次做了四件事冻结媒体元素尺寸在改变视口之前用 JS 给img/video/picture/svg/canvas写入!important的固定宽高并打上data-crawl4aiFrozen标记。目的是防止响应式 CSS 在视口放大时重新缩放图片官方注释说明这是为了修复 Elementor 等建站系统下的图像失真问题。扩大视口把视口高度设为min(page_height, screenshot_height_threshold)即最多放大到阈值高度。阈值默认值来自 config.py 中的常量SCREENSHOT_HEIGHT_TRESHOLD 10000注意 async_configs.py 的文档字符串写的是 “e.g. 20000”示例文档中也称 “default ~20,000px”以当前仓库实际常量为准是 10000且该值可以通过screenshot_height_threshold参数在每次运行时覆盖。逐段滚动截图按page_height // viewport_height 1计算分段数每段执行window.scrollTo后asyncio.sleep(scroll_delay)等待渲染再以typejpeg, quality85截取该段最后一小段会临时把视口调整为剩余高度避免多余空白。拼接与还原用 Pillow 把所有段拼成一张 PNG再恢复元素的原始尺寸设置移除冻结样式并还原初始视口。任何一步抛异常都会降级为一张 800x600 的黑色错误图白字写明错误原因保证result.screenshot始终有值、流程不中断——这是take_screenshot_scroller与take_screenshot_naive共同的容错设计。scroll_delay控制整页截图的滚动节奏当页面高度超过阈值且没有走 PDF 路径时Crawl4AI 会滚动整个页面来生成拼接截图。scroll_delay控制每一步滚动之间的停顿config CrawlerRunConfig( screenshotTrue, scroll_delay0.5, # Wait 0.5s between scroll steps (default: 0.2) )从源码看scroll_delay在 CrawlerRunConfig 中定义为“当scan_full_pageTrue时滚动步骤之间的延迟秒默认 0.2”并被传入take_screenshot后在分段循环里作为每段截图前的等待时间await asyncio.sleep(scroll_delay)。对懒加载图片、滚动触发动画较多的页面把它从 0.2 调大到 0.5 甚至更高能显著减少“滚过去时内容还没加载完”的空白块问题。仅视口截图force_viewport_screenshot如果只需要首屏viewport截图而非整页使用force_viewport_screenshotTrue。它对长页面更快、生成的图片更小import os import asyncio from base64 import b64decode from crawl4ai import AsyncWebCrawler, CrawlerRunConfig async def main(): async with AsyncWebCrawler() as crawler: result await crawler.arun( urlhttps://en.wikipedia.org/wiki/List_of_common_misconceptions, configCrawlerRunConfig( screenshotTrue, force_viewport_screenshotTrue # Only capture the visible viewport ) ) if result.success and result.screenshot: with open(viewport_screenshot.png, wb) as f: f.write(b64decode(result.screenshot)) print(Viewport screenshot saved!) if __name__ __main__: asyncio.run(main())文档给出的适用场景只需要“首屏以上”可见内容长页面上希望更快完成截图需要小体积图片做缩略图或预览。源码印证该参数直接进入take_screenshot的第一个判断分支为真时完全跳过高度探测与滚动拼接走一次page.screenshot(full_pageFalse)因此是长页面场景下最轻量的截图方式。参数语义的官方定义见 async_configs.py“为 True 时无论页面高度如何都只截视口为 False 时自动决策短页面截视口长页面整页截图”。参数速查表结合 CrawlerRunConfig 的构造函数签名本文涉及的关键参数汇总如下参数类型默认值作用pdfboolFalse为 True 时导出整页 PDFprint_backgroundTrue存入result.pdfscreenshotboolFalse为 True 时生成截图base64存入result.screenshotscreenshot_wait_forfloat / NoneNone截图前额外等待的秒数等待渲染/动画screenshot_height_thresholdintSCREENSHOT_HEIGHT_TRESHOLD当前仓库为 10000大视口放大与分段策略的高度阈值force_viewport_screenshotboolFalse强制只截视口跳过整页逻辑scan_full_pageboolFalse参与截图分支决策为 False 时按视口截图scroll_delayfloat0.2滚动步骤之间的停顿秒影响懒加载内容捕获max_scroll_stepsOptional[int]None整页扫描的滚动步数上限防止无限滚动页面挂起依赖与环境注意事项PDF 转图路径依赖pdf2image与系统级的 popplerconvert_from_bytes内部调用 poppler 工具链安装环境如缺失它们take_screenshot_from_pdf会捕获异常并返回错误占位图截图主路径依赖 Pillow拼接与转码所有导出结果统一为 base64 字符串PNG 或 JPEGPDF 导出走 Chromium 打印管线适合 Chromium 内核的浏览器环境这也是官方示例默认使用AsyncWebCrawler内置 Playwright 浏览器的原因相关行为可参考仓库中的截图回归测试 tests/test_issue_1750_screenshot_scan_full_page.py它覆盖了scan_full_page与整页截图组合下的实际行为。小结Crawl4AI 对超长页面的截图/PDF 方案可以概括为三层策略能用浏览器 PDF 管线解决就优先用稳定、不超时、与页面长度无关必须截图时按“视口判定—大视口分段拼接”的决策链执行并用scroll_delay给懒加载内容留出渲染时间只要首屏时则用force_viewport_screenshot走最轻路径。三者都通过CrawlerRunConfig的独立开关组合一次arun调用即可同时产出result.pdf与result.screenshot且失败时有黑底错误图兜底保证了批处理场景下的流程鲁棒性。【免费下载链接】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），仅供参考