Scrapling:10 万星爬虫框架,选择器失效后能自己找回来
Scrapling:10 万星爬虫框架,选择器失效后能自己找回来
网页改版导致爬虫一夜全挂?这个库把修复成本压到了零。
写爬虫的人都躲不过一件事:目标网站一改版,昨天还好好的 CSS 选择器今天全部返回空,然后你得打开浏览器重新定位元素、改代码、发版。D4Vinci/Scrapling 想解决的就是这个维护成本问题。2026-11-10 的 GitHub 数据是 100,704 star、10,517 fork、只有 22 个未关闭 issue,最后一次代码推送就在前一天(2026-11-09),BSD-3 协议,Python 实现,当前版本 0.5.1,pyproject.toml 里开发状态仍标着 Beta。
我把 README、官方文档的 Fetcher/自适应/Spider/MCP 四个部分、还有 pyproject.toml 的真实依赖都过了一遍。这篇按四个问题展开:它到底是什么、怎么装怎么跑、哪些设计值得抄、以及它和 Scrapy、Playwright 这些老工具怎么分工。
本文提纲
- 是什么:一个框架覆盖抓取全流程,不是又一个 requests 封装
- 怎么用:安装、两类 Fetcher、自适应、Spider、MCP
- 值得学习的四个设计
- 同类比较:Scrapy、Playwright、BeautifulSoup、Crawlee 怎么选
是什么:一个框架覆盖抓取全流程,不是又一个 requests 封装
一句话定位:Scrapling 是一个把 HTTP 请求、隐身浏览器、HTML 解析、并发爬虫和数据导出收进同一个库的 Python 抓取框架,还附带 MCP server 让 AI agent 直接调用。它不是 requests 的薄封装,也不是 Scrapy 的插件,更不是 SaaS 服务。
有个历史细节值得知道:v0.2 之前它只是个解析引擎,v0.3 才加入 Fetcher,目标写在文档里——逐步覆盖抓取的完整流程。理解这个演进能解释它现在的模块边界。官方文档对 Fetcher 有一句明确声明:Fetcher 不是建在其他库之上的包装层(wrapper),底层库只当引擎用,Fetcher 在上面实现了引擎本身没有的抓取特性。这句话是否完全成立可以讨论,但它点出了设计取向:引擎可替换,抓取语义自己掌握。
它的分层结构是这样:
flowchart TB
subgraph EntryLayer
CLI["CLI / Interactive Shell"]
MCP["MCP Server - 16 tools"]
PY["Python API"]
end
subgraph FetchLayer
F["Fetcher / AsyncFetcher
curl_cffi + browser impersonate"]
SF["StealthyFetcher
Playwright + patchright stealth"]
end
subgraph ParseLayer
SEL["Selector engine
lxml + cssselect, CSS/XPath/regex"]
AD["Adaptive engine
SQLite fingerprint + similarity score"]
end
subgraph CrawlLayer
SP["Spider + Scheduler
sessions, checkpoint, response cache"]
end
OUT["ItemList export
JSON / JSONL / CSV / XML / Markdown"]
EntryLayer --> FetchLayer
FetchLayer --> ParseLayer
ParseLayer --> CrawlLayer
CrawlLayer --> OUT
AD -.->|relocates elements| SEL
classDef red fill:#FF6B6B,stroke:#764ba2,color:#000
classDef teal fill:#4ECDC4,stroke:#764ba2,color:#000
classDef blue fill:#45B7D1,stroke:#764ba2,color:#000
classDef sage fill:#96CEB4,stroke:#764ba2,color:#000
classDef yellow fill:#FFEAA7,stroke:#764ba2,color:#000
class CLI,MCP,PY red
class F,SF teal
class SEL,AD blue
class SP sage
class OUT yellow虚线那条就是它和普通抓取库最不一样的地方:自适应引擎。网页结构变了,选择器找不到元素时,它不靠大模型,而是拿元素指纹去全页面做相似度匹配,把元素重新定位回来。这个机制后面单独拆。
怎么用:安装、两类 Fetcher、自适应、Spider、MCP
安装:核心库很轻,能力按 extras 切
先看 pyproject.toml 里的真实依赖。核心包只依赖 lxml、cssselect、orjson、w3lib 这几个解析库,请求和浏览器能力全部放进 optional extras:
# 只要解析能力,不需要发请求
pip install scrapling
# 完整抓取能力(curl_cffi、playwright、patchright 等都在这个 extra 里)
pip install "scrapling[fetchers]"
# 带 MCP server 和 Markdown 导出
pip install "scrapling[ai]"
# 装浏览器二进制,StealthyFetcher 才能跑
scrapling installextras 的划分在 pyproject.toml 里写得很清楚:fetchers 是请求加浏览器的基础集,rag 在它之上加 markdownify,ai 再加 mcp,shell 换成 IPython,all 等于 ai 加 shell。要求 Python 3.10 以上。这种"核心零网络依赖、重能力按需装"的切法,让它能同时出现在轻量解析脚本和带浏览器的抓取服务里。
有个版本事实要先讲明:pyproject.toml 的 classifiers 仍标着 Development Status :: 4 - Beta,当前版本 0.5.1,1.0 之前 API 有变动空间,生产环境务必锁版本号,别用宽松依赖。
第一条请求:Fetcher 与选择器
静态页面用 Fetcher,接口风格和 Scrapy/Parsel 一致,.css()、.xpath()、.get()、.getall() 这套可以直接迁移:
from scrapling.fetchers import Fetcher
page = Fetcher.get('https://quotes.toscrape.com/')
quotes = page.css('.quote .text::text').getall()需要并发请求就换 AsyncFetcher,接口同名,靠 async/await 调度;它和 Fetcher 同属 HTTP 类,都不带浏览器,速度最快但过不了 JS 渲染和强反爬。
返回的 Response 对象同时是选择器,还挂着 status、headers、cookies、history 这些响应信息。除了 CSS/XPath,它提供两个非标准但好用的方法:find_by_text() 按文本内容找元素,find_by_regex() 按正则找;还有一个 find_similar(),给定一个元素,按 DOM 深度、标签名、父级标签和属性相似度把同结构的兄弟元素全捞出来,灵感来自 AutoScraper,但能用在任何方式找到的元素上。
需要 LLM 语料时,一行转成干净 Markdown,转换前会剥掉 script、style 和隐藏内容:
markdown = Fetcher.get('https://example.com').markdown(main_content_only=True)动态页面:StealthyFetcher 的三种浏览器接法
碰到 JavaScript 渲染和反爬,换 StealthyFetcher,底层是 Playwright API 加 stealth 补丁。它给了三种运行方式,对应不同部署环境:
from scrapling.fetchers import StealthyFetcher
# 1. 用内置 Chromium,默认隐身设置
StealthyFetcher.fetch('https://example.com')
# 2. 用本机真实 Chrome,指纹更像真人
StealthyFetcher.fetch('https://example.com', real_chrome=True)
# 3. 连远程浏览器,适合容器和托管浏览器服务
StealthyFetcher.fetch('https://example.com', cdp_url='ws://localhost:9222')反检测参数列在文档的参数表里,具体包括:solve_cloudflare=True 自动过 Cloudflare Turnstile/Interstitial、hide_canvas 给 canvas 加随机噪声、block_webrtc 防真实 IP 泄露、dns_over_https 防 DNS 泄露、block_ads 拦约 3500 个广告追踪域名。默认 headless,但文档提醒现在很多 WAF 会检查 WebGL 是否开启,所以 WebGL 默认保留。这里要划一条边界:它能处理 Cloudflare 这一档,Akamai、DataDome、Kasada 这类企业级防护,README 的赞助商部分自己也承认得接外部打码 API,框架本身不包。
自适应:让爬虫在改版后自愈
这是 Scrapling 最核心的功能,分两个阶段。第一次选中元素时打开 auto_save,它把元素的指纹存进本地 SQLite;以后选择器失效时打开 adaptive,它取指纹去新页面做相似度打分,返回最像的元素:
from scrapling import Fetcher
Fetcher.configure(adaptive=True, adaptive_domain='stackoverflow.com')
# 第一次:保存元素指纹
page = Fetcher.get(old_url, timeout=30)
element = page.css('#hmenus > div:nth-child(1) > ul > li:nth-child(1) > a', auto_save=True)[0]
# 网站改版后,同一条选择器已经匹配不到
page = Fetcher.get(new_url)
element = page.css('#hmenus > div:nth-child(1) > ul > li:nth-child(1) > a', adaptive=True)[0]官方文档给的验证案例挺有意思:用 Wayback Machine 上 2010 年版 StackOverflow 和当前版本做对比,同一条 Chrome 生成的超长选择器,在自适应模式下两个页面定位到了同一个按钮。
指纹具体存什么,文档写得透明:元素自身的标签名、文本、属性名和值、兄弟标签、路径标签,加上父级的标签名、属性和文本。匹配不是精确相等,而是算相似度,连 class 名的书写顺序都纳入比较;默认相似度阈值 0.2,href 和 src 默认忽略,因为 URL 在同类元素间本来就变化大。存储靠域名加 identifier 做键,网站连域名一起换了,就用 adaptive_domain 告诉它这是同一个站。注意 adaptive 默认关闭,要显式开。
也要看清它的失效条件,文档专门有 Troubleshooting 和 Known Issues:页面结构大改、元素文本和属性同时剧变时,会出现匹配不到或匹配错,相似度阈值和忽略属性得按站点调。它降低的是改版后的维护频率,不是消灭维护,上线后对关键选择器仍要保留校验和告警。
规模化:Spider 与断点续爬
单个 Fetcher 管一次请求,整站爬取用 Spider。写法对 Scrapy 用户几乎零学习成本:
from scrapling.spiders import Spider, Response
class QuotesSpider(Spider):
name = "quotes"
start_urls = ["https://quotes.toscrape.com/"]
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(),
}
result = QuotesSpider().start()
result.items.to_json("quotes.json")引擎内部是 Scheduler 优先队列加 URL 指纹去重、Session Manager 按 sid 路由会话、被封响应自动重试(is_blocked() 钩子可自定义)。两个工程细节值得说。一是 checkpoint:给 crawldir 传个目录,待爬请求和已见 URL 会周期性原子写入磁盘,Ctrl+C 退出时再存一次,下次同目录启动直接续爬。二是开发模式的 response cache,把每次响应存本地,迭代 parse() 逻辑时直接回放,不再反复请求目标站。导出靠 ItemList 的 to_json/to_jsonl/to_csv/to_xml。
让 AI agent 来爬:MCP server
pip install "scrapling[ai]" 之后,scrapling-mcp 命令(v0.4.13 加的快捷方式,等价于 scrapling mcp)启动一个暴露 16 个工具的 MCP server。Claude Desktop 的配置就一行:
{
"mcpServers": {
"ScraplingServer": { "command": "scrapling-mcp" }
}
}工具分两类:one-shot 工具抓完一个 URL 就关浏览器,session 工具跨调用保留 cookie 和标签页,能看网络历史。它还在输出侧做了 prompt injection 清洗,隐藏元素、aria-hidden、零宽字符、HTML 注释这些会在交给 LLM 前去掉。对做 agent 数据采集的人,这等于把隐身抓取能力变成了模型可调用的标准工具。
合规这关框架替不了你:robots.txt、目标站服务条款、当地数据法规要自己守,MCP 文档也专门有一节 Legal and Ethical Considerations。另外 README 里一排代理和打码赞助商其实透露了成本结构——规模化抓取的 IP 轮换和验证码开销不在框架内,Cloudflare 这一档能自动过,Akamai、DataDome、Kasada 这类企业级防护得接外部服务。
值得学习的四个设计
1. 用指纹相似度替代固定选择器,把维护成本从人转给库
传统选择器是硬绑定:#p1 就是找 id 等于 p1 的节点,网站把 id 改成 data-id 就彻底失联。Scrapling 的思路是把元素降级成一组可比较的特征,选择器只负责第一次定位,之后靠特征相似度在新 DOM 里重新认领。这本质上是把"元素定位"从精确匹配改成了近似检索。值得学的不是相似度算法本身(阈值 0.2 相当宽松),而是这个问题建模:爬虫维护的大头是改版后的重新定位,它把这件事产品化成了 save/match 两阶段加一个 SQLite 存储,而且全程不依赖 AI,没有额外推理成本和不确定性。
2. HTTP 与浏览器显式分层,按被封风险选引擎
它没有用一个"万能 Fetcher"隐藏所有差异,而是把快但弱的 Fetcher 和慢但强的 StealthyFetcher 分开,文档直接给了速度、隐身、内存的星级对照。底层引擎也不一样:静态请求走 curl_cffi 做 TLS/HTTP2 指纹模拟,浏览器走 Playwright 加 patchright 补丁。这种分层逼着使用者先判断目标站的防护等级再选工具,而不是无脑起浏览器。启动一个 Chromium 要拉起完整渲染进程,资源开销远高于单次 HTTP 请求,能静态解决就不开浏览器,这条取舍被写进了 API 形态里。
3. 爬虫状态当成一等公民:checkpoint 与开发缓存
很多轻量抓取库只管"发请求拿响应",爬取状态要你自己维护。Scrapling 把断点续爬做成了配置项而非框架玄学:pickle 文件、临时文件加 rename 的原子写、正常跑完自动清理。更实用的是开发模式 response cache——解析逻辑的迭代频率远高于页面变化,每次改 parse() 都重新打目标站既慢又容易触发封禁,本地回放把开发循环和网络解耦。这两个设计都在解决同一件事:让长时间运行的爬虫可中断、可调试。
4. 一个解析内核,喂给四种入口
同一个 Selector/Response 抽象,同时服务 Python 调用、CLI、交互式 shell 和 MCP server,Spider 的回调拿到的也是它。解析逻辑写一次,可以在脚本里跑、在终端里试、交给 agent 调。这种"内核稳定、入口多样"的架构让它能赶上 MCP 这波——MCP server 不需要重写抓取能力,只是把现有能力包成 16 个工具。反观很多抓取库,每个入口都是一套独立实现,加新交互方式就得重造一遍。
同类比较:Scrapy、Playwright、BeautifulSoup、Crawlee 怎么选
先声明口径:Scrapling 与 Scrapy 的概念映射来自官方文档的同一张对照表;BeautifulSoup、Playwright、Crawlee 的定位是这些项目公开文档的通用事实,各家没有统一 benchmark,这里不编造性能数字,只比架构和适用场景。
| 维度 | Scrapling | Scrapy | Playwright(裸用) | BeautifulSoup | Crawlee |
|---|---|---|---|---|---|
| 核心定位 | 全流程抓取框架 | 成熟爬虫框架 | 浏览器自动化 | HTML 解析库 | 爬虫自动化库(JS/Python) |
| HTTP 与浏览器 | 双 Fetcher 内置分层 | HTTP 为主,浏览器靠插件 | 只有浏览器 | 不发请求,要配 requests | 两者都支持 |
| 选择器失效自愈 | 有,指纹相似度 | 无 | 无 | 无 | 无 |
| 反爬指纹 | curl_cffi + stealth 补丁 | 靠中间件自建 | 需自己加 stealth | 无 | 有指纹注入 |
| 断点续爬 | crawldir 内置 | JOBDIR | 自己实现 | 不涉及 | 有持久化 |
| MCP/AI 入口 | 官方 MCP server | 社区方案 | 无 | 无 | 无官方 MCP |
| 成熟度 | Beta,0.5.x | 生产级,十余年 | 生产级 | 生产级 | 生产级,JS 生态更强 |
再看和 Scrapy 的具体映射,这张是官方文档原样给出的对照,迁移成本可以直接读出来:Spider 子类对 scrapy.Spider,response.follow 两边同名,yield dict 出数据一致,allowed_domains、robots 设置都能一一对应;Scrapy 的 Downloader+Middlewares 在这里换成 Session Manager,封禁检测从自定义中间件变成内置 is_blocked() 钩子,暂停恢复从 JOBDIR 变成 crawldir。额外多出来的是流式 async for item in spider.stream()、单 spider 多类型会话,以及自适应。
选型上我的判断分四类:
- 大规模、长时间、已经有 Scrapy 运维体系的团队:继续用 Scrapy。它的中间件生态、调度器(如 Scrapy-Redis 分布式)和生产案例厚度,一个 0.5.x 的 Beta 库短期内补不上。
- 要的是浏览器自动化本身(端到端测试、表单交互、截图):直接用 Playwright。Scrapling 的 StealthyFetcher 底层就是 Playwright,如果你不需要抓取专属的解析、自适应和导出层,多套一层没有收益。
- 只解析本地 HTML 或简单脚本:BeautifulSoup 加 requests 仍然最轻,Scrapling 的核心解析依赖 lxml,解析速度更快但学习曲线略陡,简单场景差异不大。
- 反爬中等、改版频繁、想让 agent 直接取数的新项目:这是 Scrapling 的甜区。自适应解决改版维护,双 Fetcher 解决动态页面,MCP 解决 AI 接入,一个库把这三件事打通,省掉自己拼装三四个库的胶水代码。Crawlee 是最接近的竞品,但它的主战场在 Node.js,Python 版生态和文档厚度目前不及 Scrapling 在 Python 侧的投入。
参考文档与链接
- D4Vinci/Scrapling(GitHub) — 仓库主体,BSD-3,100,704 star / 10,517 fork / 22 open issue(2026-11-10 GitHub API 快照)
- pyproject.toml — v0.5.1、Python ≥3.10、Beta 状态、extras 划分与真实依赖
- 官方文档:Fetchers basics — Fetcher/StealthyFetcher 对照、Response 对象、Markdown 导出
- 官方文档:Browser fetching with StealthyFetcher — 三种浏览器接法、完整反检测参数表、Cloudflare 处理
- 官方文档:Adaptive scraping — save/match 两阶段、元素指纹构成、SQLite 存储、Wayback Machine 验证案例
- 官方文档:Querying elements — CSS/XPath、find_by_text、find_similar 机制与相似度阈值
- 官方文档:Spiders architecture — 数据流、checkpoint、response cache,含与 Scrapy 的官方对照表
- 官方文档:MCP Server Guide — 16 个工具、安装命令、Claude 配置、prompt injection 清洗
- Scrapy 官方文档 — 对照用,JOBDIR、中间件与 Downloader 架构
- Playwright Python 文档 — StealthyFetcher 的底层引擎与 Page API
- patchright — Scrapling 浏览器隐身补丁依赖
- curl_cffi — 静态 Fetcher 的 TLS 指纹模拟引擎
- Crawlee 官网 — 最接近的全流程竞品,Python/JS 双实现
- AutoScraper — find_similar 功能的灵感来源
你被网站改版搞崩过爬虫吗?用过自适应选择器或者别的自愈方案的话,评论区聊聊实际命中率。觉得有帮助点个赞,让更多写爬虫的人看到。
作者: itech001
来源: 公众号:AI人工智能时代(the-ai-era)
网站: https://www.theaiera.top/
关注每日最新AI新闻和技术博客,主页有更多的文章的AI 技术参考:https://www.theaiera.top
本文首发于 AI人工智能时代,转载请注明出处。