返回博客列表

Scrapling:10 万星爬虫框架,选择器失效后能自己找回来

2026-11-10T16:30:00+08:00
Scrapling爬虫PythonPlaywrightMCP开源项目

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 这些老工具怎么分工。

本文提纲

  1. 是什么:一个框架覆盖抓取全流程,不是又一个 requests 封装
  2. 怎么用:安装、两类 Fetcher、自适应、Spider、MCP
  3. 值得学习的四个设计
  4. 同类比较: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 install

extras 的划分在 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 侧的投入。

参考文档与链接

你被网站改版搞崩过爬虫吗?用过自适应选择器或者别的自愈方案的话,评论区聊聊实际命中率。觉得有帮助点个赞,让更多写爬虫的人看到。


作者: itech001
来源: 公众号:AI人工智能时代(the-ai-era)
网站: https://www.theaiera.top/ 关注每日最新AI新闻和技术博客,主页有更多的文章的AI 技术参考:https://www.theaiera.top

本文首发于 AI人工智能时代,转载请注明出处。

分享给朋友