Scrapling:9.5 万 Star 的爬虫库,把 Scrapy、Playwright、Cloudflare 破解和 MCP 塞进了一个 pip 包

两年做到 95,868 Star 的 Python 爬虫框架:HTTP 与隐身双 Fetcher、自适应选择器、并发 Spider、16 个 MCP 工具。附实测数据、性能基准的可信度分析,以及 README 里那半页赞助商广告。

图:Scrapling 官方标识

Scrapling 是一个 Python 爬虫框架,主张「一个库搞定从单次请求到全站爬取」:HTTP 请求、隐身浏览器、自适应解析、并发 Spider、代理轮换、断点续爬、MCP 服务端,全塞在一个 pip 包里。

项目:https://github.com/D4Vinci/Scrapling(95,868 Star · 10,051 Fork · BSD-3-Clause · Python)

它 2024 年 10 月建库,两年做到近 10 万 star,月下载量约 92 万次。这个量级已经不是「小众工具」,而是一个正在收敛的生态位。

本文数字均为 2026-11-04 通过 GitHub REST API 与 PyPI JSON API 实测,非引用二手报道。


01 · 硬数据

维度实测值备注
Star / Fork95,868 / 10,051关注度极高
Watchers339相对 star 偏低,围观多于参与
建库 / 最近 push2024-10-13 / 2026-11-04存续 2 年
Commit 总数1,786平均每天 2.4 次
贡献者42第一人占 94.3%
Release / PyPI 版本54 / 54首个 0.1(2024-10-13),最新 0.5(2026-10-17)
Issue / PR180 / 305当前仅 10 个 open issue
月下载量(PyPI)919,855近 7 天 298,235
许可证BSD-3-Clause商用友好

贡献者分布(/contributors?anon=1):

D4Vinci        1684   ← 94.3%
yetval           17
AbdullahY36      10
SulimanAbdulrazzaq 10
Yigtwxx           8
mhillebrand       4
haosenwang1018    4
Bortlesboat       4
mturac            3
(其余 33 人 ≤2 次)

42 个贡献者,94% 的代码来自一个人。 作者是 Karim Shoair(D4Vinci),安全研究方向出身——这个背景能解释为什么库里有 Cloudflare 破解和指纹伪装。

代码构成(git/trees/main?recursive=1,692 个文件,未截断):

类别文件数体积说明
源码(scrapling/)61630 KB库本体
测试(tests/)991,054 KB是源码的 1.67 倍
文档(docs/**/*.md)3895.72 MB含 9 种语言 360 个译文文件
CI 工作流4—tests / code-quality / release / docker

测试代码比源码还多——这在爬虫库里是罕见比例,因为爬虫库最难写测试(要对抗会变的真实网站)。


02 · 它到底是什么

一句话:它把原本需要拼 4~6 个库才能做的事,收进了一个 import。

传统 Python 爬虫的组合拳是这样的:

需求传统方案
快速 HTTP + 绕过 TLS 指纹检测curl_cffi
解析 HTMLBeautifulSoup + lxml,或 parsel
JS 渲染 / 过 CloudflarePlaywright + undetected 补丁
并发爬取 / 断点续爬 / 限速Scrapy
代理轮换自己写
给 AI 用自己包一层 MCP

Scrapling 的答案是:这些全都有,且用同一套 Response / Selector 对象贯通。

from scrapling.fetchers import Fetcher

page = Fetcher.get('https://quotes.toscrape.com/')
quotes = page.css('.quote .text::text').getall()

Response 对象继承 Selector,所以拿到页面之后,CSS、XPath、find_all、find_by_text、正则搜索全都能直接用,不用在 fetcher 和 parser 之间倒手。

底层依赖(pyproject.toml 的 [project] dependencies):

lxml>=6.1.1          cssselect>=1.5.0     orjson>=3.11.8
tld>=0.13.2          w3lib>=2.4.1         typing_extensions

fetchers 可选组才会拉进 curl_cffi、playwright、patchright、browserforge、apify-fingerprint-datapoints。

这个分层设计值得注意:pip install scrapling 只装解析引擎(6 个依赖),不装任何浏览器。想用 fetcher 必须 pip install "scrapling[fetchers]" + scrapling install 下载 Chromium。作者把「轻」和「重」切得很干净——但也意味着第一次用会踩 ModuleNotFoundError,README 里专门用 IMPORTANT 提示框警告这一点。


03 · Fetcher 还是 StealthyFetcher

FetcherStealthyFetcher
相对速度🐇🐇🐇🐇🐇🐇🐇🐇
隐身能力⭐⭐⭐⭐⭐⭐⭐
JS 渲染❌✅
内存占用⭐⭐⭐⭐
底层curl_cffiPlaywright(Chromium / Chrome)
适用HTTP 请求能拿到完整内容时动态加载、反爬复杂的中小站点

选择逻辑很干脆:

三条使用路径的差别在于代价:Fetcher 是纯 HTTP,秒级;StealthyFetcher 要起浏览器,内存和耗时高一个量级;solve_cloudflare=True 还要额外等挑战通过。

一个细节值得记:Fetcher 支持 impersonate='chrome'——伪装成浏览器真实的 TLS 指纹,而不只是改 User-Agent。这两者在反爬面前差别巨大:UA 随便改,但 JA3 指纹对不上就露馅。

with FetcherSession(impersonate='chrome') as session:
    page = session.get('https://quotes.toscrape.com/', stealthy_headers=True)

04 · adaptive parsing:让选择器活过网站改版

这是 Scrapling 最有辨识度的功能,也是我认为它唯一「别人抄不走」的部分。

老问题:page.css('#p1') 在网站改版后必然失效,然后你半夜收到报警。

Scrapling 的做法是:第一次选中元素时把它的特征存进 SQLite,改版后用相似度重新找回来。

存的特征(docs/parsing/adaptive.md 原文):

元素的标签名、文本、属性(名与值)、兄弟节点(仅标签名)、路径(仅标签名);父节点的标签名、属性、文本。

匹配时逐项打分,取相似度最高的元素返回。不经过 AI,不调用模型,纯相似度算法。

文档里给了个真实可复现的例子:用 2010 年 Stack Overflow 的存档页(Wayback Machine)保存特征,再用同一个选择器去抓 2026 年的现站,两边返回同一个「Questions」按钮。

这套设计的关键洞察是:元素的一切属性都可能被网站改掉,所以不能拿任何单一属性当唯一 ID。 作者的解法是把域名 + 自定义 identifier 作为数据库主键,特征只用于打分——这比「缓存选择器」或「靠 AI 重新生成选择器」都稳,因为前者失效时你连回退都没有,后者每次要花 token 且结果不可复现。

代价也清楚:相似度匹配是启发式,会误匹配。特征存多了库会膨胀;adaptive_domain 这类参数说明跨域名场景需要手动干预。


05 · Spider:并发、断点续爬、现成模板

图:Scrapling Spider 官方架构图

官方给的架构图很干净:Spider 定义抓取规则 → Crawler Engine 调度 → Session Manager 分发到不同 fetcher → Items 输出;中途 Checkpoint system 落盘,重启后从断点续爬。

代码形态接近 Scrapy,但用 async:

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()}

几个在爬虫实战里真正省事的能力:

能力解决的问题
crawldir="./crawl_data" + Ctrl+C断点续爬。保存 pending 请求与已见 URL,重启从同一目录恢复
多 Session 混用同一个 Spider 里,普通页走 HTTP、受保护页走隐身浏览器,用 sid 路由
AutoThrottle不用猜 delay。按目标站点响应速度自动调,被限流时翻倍或按 Retry-After 等
Development Mode首次跑把响应缓存到磁盘,之后重放——改 parse() 逻辑不用反复打目标站
ShopifySpider直接拉整站商品目录,每个 SKU 一条
result.items.to_json()内置 JSON / JSONL / CSV / XML 导出

Development Mode 是这里最实用的一条。 爬虫开发 90% 的时间花在调解析逻辑,而每次调试都要重新请求目标站——既慢又容易被封。缓存重放把这件事从「每次都联网」变成「一次联网 + N 次本地」,本质上是给爬虫加了单元测试的能力。

robots.txt 遵守是可选项(robots_txt_obey),默认不开启。这一点后面会提。


06 · 对 AI 的三层接口

2026 年的开源库如果还只提供 Python API,基本等于自绝于 AI 生态。Scrapling 给了三层,且分层很清楚:

层形态给谁用
MCP 服务端16 个工具(browser_fetch、browser_actions、browser_screenshot、browser_network_requests…)Claude / Cursor 等任意 MCP 客户端
Agent Skill一个 ZIP,含完整 API 指南与示例编码 agent(Claude Code / OpenClaw)
page.markdown()一行把任意页面转成干净 MarkdownRAG 管道

MCP 那层的设计思路值得看:它不是「把 Python 函数暴露出去」,而是把浏览器操作拆成 agent 能组合的原子动作。

  • browser_actions:一次调用里串起填表、点击、悬停、滚动、按键、处理弹窗、等待——遇到第一个错误就停。这样 agent 不用每一步都往返一次模型。
  • browser_extract:不重新加载页面,直接读当前页或单个元素,支持 HTML / Markdown / text / 带元素角色和坐标的快照。
  • browser_network_requests:读页面背后的 API 调用。默认隐藏静态资源,历史有容量上限。
  • browser_save_state / load_state:登录状态存成 Playwright 兼容 JSON,下次复用。

文档里明确写了对抗 prompt 注入的意图:

它用了大量方法来减少发送给模型的内容、拦截广告,并保护其免受 Prompt 注入。

这一点很关键——把网页内容喂给 AI,本质是把不可信输入喂进模型。 一个爬虫 MCP 服务端如果不做这层防护,等于给目标站点开了一个直通 agent 的注入通道。

page.markdown() 那层则是纯本地转换,不调模型:

md = page.markdown()   # 干净、去噪、LLM-ready

配合 ContentSpider 模板,可以把整站爬成一份 Markdown 语料——构建 RAG 知识库时不需要任何 LLM 参与。


07 · 性能数字:哪部分可信,哪部分别信

README 给了一张 5000 层嵌套元素的文本提取基准(benchmarks.py,100+ 次取平均):

#库耗时 (ms)vs Scrapling
1Scrapling1.991.0x
2Parsel / Scrapy2.061.035
3Raw Lxml2.561.286
4PyQuery23.98~12x
5Selectolax197.02~99x
6MechanicalSoup1545.15~776x
7BS4 + Lxml1562.10~785x
8BS4 + html5lib3412.73~1715x

前四行可信,第五行要打问号。

Scrapling、Parsel、Raw Lxml 三者都在 2ms 量级,因为它们底层是同一个 lxml(benchmarks.py 里注释也写了「Scrapling 和 Parsel 内部用同一个 parser,这样才公平」)。这个排序符合工程直觉。

但 Selectolax 197ms 明显异常——selectolax 基于 Modest/lexbor,通常是最快的 HTML 解析器之一,不该比 raw lxml 慢 77 倍。合理推测是基准只测了 cssselect 路径,而 selectolax 的 .css() 走自己的 CSS 引擎、再逐个调 .text(),在 5000 层深嵌套下退化。这是基准设计的问题,不是库的问题。

BS4 那两行倒是可信:BeautifulSoup 慢是公开事实,html5lib 比 lxml 慢一倍也是常识。

我的建议:把这张表当「Scrapling 不比 Parsel / lxml 慢」的证据看,别当「Scrapling 最快」的证据看。 前者的结论成立,后者需要独立复测。

另一个数字:README 声称 92% 测试覆盖率、完整类型标注、已被数百名爬虫日常使用一年。前两项可以从 tox.ini 的 --cov=scrapling --cov-report=xml 和 CI 里的 mypy / pyright / vermin 看出配置是真的;具体百分比我没有复测。第三项无法验证。


08 · README 的另一半:赞助商

这件事值得单独说,因为它解释了整个赛道的商业模式。

README.md 共 38,299 字节 / 629 行,「Key Features」这一章从第 267 行才开始——前面 18,419 字节(48%)是赞助商和广告位。

列出来的厂商清一色是代理 IP 服务商:NodeMaven、Hyper Solutions、Evomi、TikHub、SwiftProxy、Byteful、ProxyLane、LundProxy、Resolvr、NoneCap、DataImpulse、Decodo、ProxyEmpire、Webshare、Proxiware……每一家都带 utm_source=scrapling 追踪参数和折扣码。

这不是道德指控,是行业结构说明。 反爬工具的真正瓶颈从来不是代码,是 IP 资源:目标站点封的是 IP 段,不是你的 Python。所以「爬虫框架 + 代理供应商」是天然的利益绑定——框架负责把请求发出去,供应商负责让请求看起来来自不同地方。

看懂了这一层,才能理解 README 里那些措辞的动机:

🕷️ The BEST Web Scraping framework 它使用大量方法…… 让合适的 AI 模型能绕过它遇到的任何 CAPTCHA

「BEST」是自评,「任何 CAPTCHA」是营销。 这类宣称在同类项目里普遍存在,读者需要自己打折。


09 · 三个必须说清的代价

① 合规边界由使用者承担

README 的免责声明写得明确:

本库仅供教育研究用途。使用本库即表示你同意遵守当地及国际数据抓取与隐私法律。作者与贡献者对任何滥用不承担责任。请始终尊重网站的服务条款与 robots.txt。

但功能上是矛盾的:robots_txt_obey 默认关闭,而 solve_cloudflare=True 的存在本身就意味着绕过网站主动设置的访问控制。

这是这类工具的结构性张力:它同时提供「遵守 robots.txt」的开关和「破解 Cloudflare 挑战」的能力,把选择权交给用户。法律风险也就跟着转移给了用户。

对企业使用的实际含义:爬取自有系统、有授权的数据、公开 API 都没问题;爬第三方站点前,先确认 ToS 与当地法律(欧盟 GDPR、中国《数据安全法》都涉及)。

② 单点依赖

94.3% 的代码来自一个人。42 个贡献者里,33 人贡献 ≤2 次。

好消息是 issue 响应快(180 个历史 issue,只剩 10 个 open);坏消息是 Bus factor = 1。这不是「不信任作者」,而是任何生产依赖都要算的风险——尤其当你的爬虫跑在关键链路上。

缓解方式:BSD-3 允许 fork,代码量 630 KB 属于可自行维护的规模。

③ 0.5 版本 + 破坏性变更

v0.5 的发布说明第一句就是警告:

本版本引入大量破坏性变更,无法在此列出。更新前请先阅读迁移指南。

从 0.1 到 0.5,两年 54 个版本。语义化版本在这里只做到 0.x——意味着 API 还在演进,pip install 不锁版本会出问题。 生产环境必须 pin 版本。


10 · 和 Scrapy / Playwright / BS4 是什么关系

不是替代,是收编。

你的现状建议
已有成熟的 Scrapy 项目别迁。Scrapling 提供 @scrapling_response 装饰器,可以让 Scrapy 的 callback 用 Scrapling 的解析器——只换解析层,不换调度层
只用 BS4 + requests,被反爬卡住这是最该换的场景。StealthyFetcher 直接解决 JS 渲染和指纹问题,解析 API 也兼容 BS4 习惯(find_all('div', {'class':'quote'}))
需要给 AI agent 提供网页访问能力用它的 MCP 服务端,别自己写
要做大规模分布式爬取看 Scrapy + Scrapy-Redis。Scrapling 的 Spider 是单机并发,不是分布式调度器
只想解析 HTML,不需要联网pip install scrapling 就够了(6 个依赖),或直接用 Selector(html)

最容易踩的坑是最后一条:很多人以为装了 scrapling 就能用 fetcher,结果 ModuleNotFoundError。解析引擎和抓取引擎是两个安装粒度。


11 · 判断

值得用的场景:

  • 中小规模爬取(单机、几十万页以内),不想维护 5 个库的版本冲突
  • 目标站有 Cloudflare / 指纹检测,且你有授权
  • 要给自己或团队搭一套 RAG 语料
  • 给 AI agent 加网页访问能力

不值得用的场景:

  • 已有稳定运行的 Scrapy 集群
  • 需要分布式调度
  • 需要长期稳定 API 承诺(0.x 阶段不适合)

值得读源码的部分(对做工程的人):

  1. adaptive 的相似度算法(docs/parsing/adaptive.md + scrapling/parser.py)——把「选择器脆弱性」这个老问题做成了可持久化的工程方案,而不是靠 AI 重新猜。
  2. 测试的组织方式——99 个测试文件、1.05 MB,比源码多 67%。爬虫库的测试是最难写的,这里值得看它怎么用 -m "browser" / -m "asyncio" 分组串行/并行。
  3. MCP 服务端的动作编排(scrapling/core/ai/server.py,55 KB)——browser_actions 那种「一次调用串起多步、遇错即停」的设计,是 agent 工具接口的一个好范本。

写在最后

Scrapling 的 9.5 万 star,一半来自它确实好用(一个 import 解决整条链路),一半来自它踩中了两个时代红利:反爬军备竞赛和AI 需要网页。

但它的技术含量不在「功能多」——功能多是集成能力,不是壁垒。真正的壁垒是 adaptive parsing:别人都在教 AI 重新生成选择器,它选择把元素特征存进数据库做相似度匹配。 前者每次要花 token 且不可复现,后者一次保存、永久可查。

代价也清楚:一个人写了 94% 的代码,0.5 版本、破坏性变更、默认不守 robots.txt、README 里近半是代理厂商广告。

它现在是一个好用的工具,也是一个值得读的工程样本,但不是一个可以无条件信任的生产依赖。


数据来源:GitHub REST API(2026-11-04),含 /repos/D4Vinci/Scrapling、/commits?per_page=1(Link last page 1786)、/contributors?anon=1(42 人)、/releases(54 页)、/search/issues(issue 180 / PR 305)、/git/trees/main?recursive=1(692 项未截断);PyPI JSON API(0.5,requires_python >=3.10,54 个版本,首个 0.1 / 2024-10-13);pypistats.org(近 1 天 66,033 / 近 7 天 298,235 / 近 30 天 919,855)。文档引文出自 README.md(38,299 字节)、docs/parsing/adaptive.md、docs/fetching/choosing.md、docs/ai/mcp-server.md、docs/cli/overview.md、agent-skill/README.md、pyproject.toml、benchmarks.py、tox.ini、.github/workflows/{tests,code-quality}.yml。截图与架构图取自仓库 docs/assets/。

未验证项:README 声称的 92% 测试覆盖率、与 Selectolax 的实际性能差距(基准只测了 cssselect 路径,197ms 与 selectolax 的通常表现不符,未做独立复测)、solve_cloudflare 对各类 Cloudflare 部署的实际成功率。本文只陈述文档与代码中声明的行为。