Scrapling 自适应 Web 抓取框架指南Fetcher、Spider 与 CLI 全解析【免费下载链接】Scrapling️ An adaptive Web Scraping framework that handles everything from a single request to a full-scale crawl!项目地址: https://gitcode.com/GitHub_Trending/sc/Scrapling本文基于 Scrapling 仓库中的项目说明文档docs/README_KR.md整理而成系统讲解这个“从单请求到大规模爬取通吃”的自适应 Web 抓取框架你将学会如何选用三类 FetcherHTTP / 隐身浏览器 / 浏览器自动化、搭建带检查点与多会话路由的 Spider 爬虫、使用 CLI 交互式 Shell 与extract命令做零代码提取并理解安装依赖分层与性能基准背后的实现依据。框架概览一个库覆盖从单请求到完整爬取Scrapling 的定位是自适应 Web Scraping 框架。它由三块能力组成自适应解析器解析器会“学习”网站变更页面更新后能自动重新定位元素抗反爬 Fetcher无需额外配置即可绕过 Cloudflare Turnstile 一类反爬系统Spider 框架支持暂停/恢复、自动代理轮换、并发多会话爬取——全部只需几行 Python 代码。文档开篇给出的最小示例浓缩了前两块能力from scrapling.fetchers import Fetcher, AsyncFetcher, StealthyFetcher, DynamicFetcher StealthyFetcher.adaptive True p StealthyFetcher.fetch(https://example.com, headlessTrue, network_idleTrue) # 规避检测地抓取网站 products p.css(.product, auto_saveTrue) # 即使网站改版也能存活的数据提取 products p.css(.product, adaptiveTrue) # 网站结构变化后用 adaptiveTrue 重新找回元素而“从单请求扩展到完整爬取”只差一个 Spider 子类from scrapling.spiders import Spider, Response class MySpider(Spider): name demo start_urls [https://example.com/] async def parse(self, response: Response): for item in response.css(.product): yield {title: item.css(h2::text).get()} MySpider().start()从源码结构看scrapling包按职责拆分为 scrapling/fetchers/抓取入口、scrapling/engines/底层引擎与浏览器控制、scrapling/spiders/爬取框架、scrapling/core/解析核心与 Shell、存储与 scrapling/cli.py命令行入口这与文档“一个库、分层可选依赖”的设计一致。核心能力总览Spider完整爬虫框架文档为 Spider 列出的能力均能在 scrapling/spiders/spider.py 中找到对应实现载体Scrapy 风格 APIstart_urls、异步parse回调、Request/Response对象并发控制类属性concurrent_requests默认 4、concurrent_requests_per_domain、download_delay可在 Spider 中直接覆盖多会话路由HTTP 请求与隐身无头浏览器共享同一接口通过请求sid把流量路由到不同会话暂停与恢复检查点持久化CtrlC 优雅停止后重启即从断点继续。对应 scrapling/spiders/spider.py#L106-L111构造参数crawldir用于存放检查点文件interval默认 300 秒控制周期性落盘间隔流式模式async for item in spider.stream()实时接收带统计的 item适合 UI、管道与长时爬取拦截检测与重试可自定义逻辑识别被拦截请求并自动重试max_blocked_retries默认 3AutoThrottle自动按站点响应速度调整每域延迟遇到拦截/限速时加倍延迟或按Retry-After等待恢复后再提速。源码中对应autothrottle_enabled、autothrottle_start_delay默认 5 秒、autothrottle_max_delay默认 60 秒、autothrottle_block_backoff等类属性见 scrapling/spiders/spider.py#L88-L93robots.txt 遵守可选robots_txt_obey标志默认False遵守Disallow、Crawl-delay、Request-rate指令并按域缓存开发模式development_mode首次运行时把响应缓存到磁盘development_cache_dir后续运行回放缓存不再请求目标服务器方便反复调试parse()逻辑即用模板CrawlSpider规则化链接跟踪、SitemapSpidersitemap/robots.txt 驱动、XMLFeedSpider/CSVFeedSpiderXML/RSS、CSV 源站、ShopifySpider通过 JSON API 抓取任意 Shopify 商店全部商品每个变体一个条目实现见 scrapling/spiders/templates/链接提取独立LinkExtractor支持 allow/deny 模式、域名过滤、CSS/XPath 作用域、扩展名过滤与 URL 规范化内建导出result.items.to_json()、to_jsonl()、to_csv()、to_xml()直接导出结果无需自建管道。会话化的高级网站抓取Fetcher 层提供四种入口全部在 scrapling/fetchers/init.py 中延迟导出组件定位适用场景Fetcher/AsyncFetcher快速 HTTP 请求普通页面模拟浏览器 TLS 指纹与头部支持 HTTP/3DynamicFetcherPlaywright 浏览器自动化Chromium / 系统 Chrome动态渲染页面StealthyFetcher隐身 指纹伪装Cloudflare Turnstile / 反爬拦截页FetcherSession/DynamicSession/StealthySession及Async*版本持久会话跨请求保留 Cookie 与状态其他关键能力代理轮换内置ProxyRotator循环或自定义策略支持逐请求代理覆盖域名与广告拦截浏览器型 Fetcher 可拦截指定域名含子域或启用内建广告拦截——约 3,500 个已知广告/追踪域名名单定义于 scrapling/engines/toolbelt/ad_domains.pyDNS 防泄漏使用代理时可选经 Cloudflare DoH 路由 DNS 查询远程浏览器cdp_url连接已运行的浏览器本地、远端或托管服务executable_path指定自编译 ChromiumXHR 捕获传入capture_xhrURL 模式后页面加载期间匹配的 XHR/fetch 响应会全部收集为Response对象存放在response.captured_xhr无需逆向接口即可拿到站点 API 数据全异步支持所有 Fetcher 均有异步版本与专属异步会话类。自适应抓取与 AI 集成智能元素跟踪基于相似度算法在改版后重定位元素auto_saveTrue保存基线、adaptiveTrue恢复查找灵活选择CSS、XPath、条件过滤、文本匹配、正则匹配相似元素发现find_similar()自动找出与目标相似的元素MCP 服务器内建 MCP 服务供 Claude/Cursor 等 AI 通过 Scrapling 先提取目标内容再交给模型降低 token 消耗还能跨调用保持浏览器会话、截图、经 CDP 控制远程浏览器。实现与说明见 scrapling/core/ai.py、docs/ai/mcp-server.md 与 docs/api-reference/mcp-server.mdAgent Skill仓库内置即用型 Agent Skill把整个库的 API 教给编码代理使其生成的代码贴合当前 API 而非凭空猜测。性能与工程化特性官方说明强调优化后的解析速度超过多数 Python 抓取库内存占用经数据结构与延迟加载优化JSON 序列化基于orjson见 pyproject.toml 核心依赖orjson3.11.8比标准库快约 10 倍官方文档称其具备 92% 测试覆盖率与完整类型提示并持续由 PyRight 与 MyPy 校验pyproject.toml 中同时配置了[tool.mypy]与[tool.pyright]。此外还提供内建 IPython 交互式 Shell可把 curl 请求转成 Scrapling 请求、免代码 CLI 抓取、完整的 DOM 遍历 API父/兄弟/子节点、自动选择器生成、与 Scrapy/BeautifulSoup 风格一致的伪元素 API以及scrapling_response装饰器——给 Scrapy 回调加一行装饰即可用 Scrapling 解析器解析已有响应集成实现见 scrapling/integrations/scrapy.py。快速开始基础 HTTP 请求from scrapling.fetchers import Fetcher, FetcherSession with FetcherSession(impersonatechrome) as session: # 使用 Chrome 最新 TLS 指纹 page session.get(https://quotes.toscrape.com/, stealthy_headersTrue) quotes page.css(.quote .text::text).getall() # 或一次性请求 page Fetcher.get(https://quotes.toscrape.com/) quotes page.css(.quote .text::text).getall()隐身模式from scrapling.fetchers import StealthyFetcher, StealthySession with StealthySession(headlessTrue, solve_cloudflareTrue) as session: # 保持浏览器直到工作完成 page session.fetch(https://nopecha.com/demo/cloudflare, google_searchFalse) data page.css(#padded_content a).getall() # 或一次性请求 —— 为该请求开浏览器完成后关闭 page StealthyFetcher.fetch(https://nopecha.com/demo/cloudflare) data page.css(#padded_content a).getall()完整浏览器自动化from scrapling.fetchers import DynamicFetcher, DynamicSession with DynamicSession(headlessTrue, disable_resourcesFalse, network_idleTrue) as session: page session.fetch(https://quotes.toscrape.com/, load_domFalse) data page.xpath(//span[classtext]/text()).getall() # 同样支持 XPath # 或一次性请求风格 page DynamicFetcher.fetch(https://quotes.toscrape.com/) data page.css(.quote .text::text).getall()Spider 实战并发爬取带翻页的站点from scrapling.spiders import Spider, Request, Response class QuotesSpider(Spider): name quotes start_urls [https://quotes.toscrape.com/] concurrent_requests 10 async def parse(self, response: Response): for quote in response.css(.quote): yield { text: quote.css(.text::text).get(), author: quote.css(.author::text).get(), } next_page response.css(.next a) if next_page: yield response.follow(next_page[0].attrib[href]) result QuotesSpider().start() print(f共抓取 {len(result.items)} 条引语) result.items.to_json(quotes.json)一个 Spider 内混用多种会话类型——把受保护页面路由到隐身会话from scrapling.spiders import Spider, Request, Response from scrapling.fetchers import FetcherSession, AsyncStealthySession class MultiSessionSpider(Spider): name multi start_urls [https://example.com/] def configure_sessions(self, manager): manager.add(fast, FetcherSession(impersonatechrome)) manager.add(stealth, AsyncStealthySession(headlessTrue), lazyTrue) async def parse(self, response: Response): for link in response.css(a::attr(href)).getall(): if protected in link: yield Request(link, sidstealth) else: yield Request(link, sidfast, callbackself.parse) # 显式回调长时爬取的暂停与恢复只需传入crawldirQuotesSpider(crawldir./crawl_data).start()按 CtrlC 即优雅暂停并自动保存进度下次启动传入相同crawldir便从断点恢复。如果完全不想写爬取逻辑可直接继承模板例如抓取 Shopify 商店全目录from scrapling.spiders import ShopifySpider class MyStore(ShopifySpider): target_website example.com result MyStore().start() # 商店全部商品每个变体一个条目高级解析与导航from scrapling.fetchers import Fetcher page Fetcher.get(https://quotes.toscrape.com/) # 多种选择方式 quotes page.css(.quote) # CSS quotes page.xpath(//div[classquote]) # XPath quotes page.find_all(div, {class: quote}) # BeautifulSoup 风格 quotes page.find_all(div, class_quote) quotes page.find_all([div], class_quote) quotes page.find_all(class_quote) quotes page.find_by_text(quote, tagdiv) # 按文本内容查找 # 高级导航 quote_text page.css(.quote)[0].css(.text::text).get() quote_text page.css(.quote).css(.text::text).getall() # 链式选择 first_quote page.css(.quote)[0] author first_quote.next_sibling.css(.author::text) parent_container first_quote.parent # 元素关系与相似度 similar_elements first_quote.find_similar() below_elements first_quote.below_elements()不抓取网页也能直接使用解析器用法完全一致from scrapling.parser import Selector page Selector(html.../html)异步会话管理import asyncio from scrapling.fetchers import FetcherSession, AsyncStealthySession, AsyncDynamicSession async with FetcherSession(http3True) as session: # 上下文管理器同步/异步模式均可 page1 session.get(https://quotes.toscrape.com/) page2 session.get(https://quotes.toscrape.com/, impersonatefirefox135) async with AsyncStealthySession(max_pages2) as session: tasks [session.fetch(url) for url in [https://example.com/page1, https://example.com/page2]] print(session.get_pool_stats()) # 可选浏览器标签池状态使用中/空闲/出错 results await asyncio.gather(*tasks) print(session.get_pool_stats())CLI 与交互式 ShellScrapling 提供完整命令行接口入口定义在 scrapling/cli.pyscrapling shell启动交互式 Web Scraping Shell带 Scrapling 预置对象、快捷键、curl 转 Scrapling 请求等工具对应文档 docs/cli/interactive-shell.md。免编程直接把页面导出为文件——默认提取body内容输出格式由扩展名决定.txt为纯文本、.md为 Markdown 化内容、.html为原始 HTMLscrapling extract get https://example.com content.md scrapling extract get https://example.com content.txt --css-selector #fromSkipToProducts --impersonate chrome scrapling extract fetch https://example.com content.md --css-selector #fromSkipToProducts --no-headless scrapling extract stealthy-fetch https://nopecha.com/demo/cloudflare captchas.html --css-selector #padded_content a --solve-cloudflare从 scrapling/cli.py 的实现可以看出各子命令的完整参数面extract get/post/put/deleteHTTP 类--impersonate单个浏览器名或逗号分隔列表随机选取、--stealthy-headers默认开启、--css-selector/-s返回全部匹配、--proxy、--timeout默认 30 秒、--cookies、--headers/-H、--params/-p、--verify、--follow-redirectsextract fetch / stealthy-fetch浏览器类在共享参数之外还有--headless/--no-headless默认无头、--wait-selector、--wait加载后额外等待毫秒、--network-idle、--disable-resources丢弃非必要资源提速、--solve-cloudflare、--block-ads拦截已知广告/追踪域、--dns-over-https经 Cloudflare DoH 防 DNS 泄漏、--real-chrome使用本机 Chrome、--locale所有 extract 命令均支持--ai-targeted只提取主体内容并清理隐藏元素便于喂给 AI。完整的 Shell 与extract命令细节分别见 docs/cli/overview.md、docs/cli/extract-commands.md。性能基准文档给出的“5000 个嵌套元素文本提取”对比单位 msvs Scrapling 为相对倍数#库耗时 (ms)相对 Scrapling1Scrapling1.991.0x2Parsel/Scrapy2.061.035x3原生 Lxml2.561.286x4PyQuery23.98~12x5Selectolax197.02~99x6MechanicalSoup1545.15~776.5x7BS4 lxml1562.10~785.0x8BS4 html5lib3412.73~1714.9x元素相似度与文本查找对比Scrapling 2.3 ms vs AutoScraper 12.58 ms约 5.47 倍。测量方法可在 benchmarks.py 中复现对含 5000 个div.item的 HTML 文档先用timeit做 2 轮预热再以time.process_time计时、repeat100取平均benchmarks.py#L22-L43其中 Scrapling 项直接执行Selector(large_html, adaptiveFalse).css(.item::text).getall()而 Lxml 对照组也刻意使用与 Parsel/Scrapling 相同的 HTML 解析器以保证公平。安装与依赖分层Scrapling 要求Python 3.10pyproject.toml 中requires-python 3.10当前版本 0.4.13pip install scrapling注意基础安装只包含解析器引擎及其依赖lxml、cssselect、orjson、tld、w3lib不含Fetcher 与 CLI 相关依赖。此时from scrapling.fetchers import ...会抛ModuleNotFoundError。scrapling/fetchers/init.py 采用模块级__getattr__延迟导入映射表真正需要某 Fetcher 时才去导入其实现模块——缺少依赖时该导入即失败这正是文档中该警告的来源。需要 Fetcher 与 Spider 时安装可选依赖并下载浏览器pip install scrapling[fetchers] scrapling install # 常规安装 scrapling install --force # 强制重装这会将浏览器、系统依赖与指纹伪装依赖一并下载也可以直接用代码安装from scrapling.cli import install install([], standalone_modeFalse) # 常规安装 install([--force], standalone_modeFalse) # 强制重装其余可选功能pyproject.toml 定义的 extraspip install scrapling[ai] # MCP 服务器mcp、markdownify fetchers pip install scrapling[shell] # 交互式 Shell 与 extract 命令IPython fetchers pip install scrapling[all] # 全部功能安装任意外挂功能后若尚未执行过仍需scrapling install补装浏览器依赖。Docker每个发布版都会自动构建并推送含全部功能与浏览器的镜像docker pull pyd4vinci/scrapling # 或 docker pull ghcr.io/d4vinci/scrapling:latest镜像构建脚本见仓库根目录 Dockerfile。使用注意与许可官方免责说明本库仅供教育与研究目的使用者须自行遵守所在司法辖区的爬虫与隐私法律并尊重目标网站的条款与 robots.txt——这一点与 Spider 内建的robots_txt_obey能力相呼应实现见 scrapling/spiders/robotstxt.py。该项目以BSD-3-Clause许可发布LICENSE。代码致谢scrapling/core/translator.py 中的选择器翻译子模块借鉴了 BSD 许可的 Parsel 项目。贡献者请先阅读 CONTRIBUTING.md测试套件覆盖 CLI、解析器、Spider、Fetcher同步/异步、Scrapy 集成等模块tests/可作为行为验证的参照。【免费下载链接】Scrapling️ An adaptive Web Scraping framework that handles everything from a single request to a full-scale crawl!项目地址: https://gitcode.com/GitHub_Trending/sc/Scrapling创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考