Scrapling

[!info] 知识库定位 这是一篇 工具评估 / 使用笔记，重点回答”它值不值得用、怎么用、什么时候不用”。 底层概念链接到 related_concepts；真实项目落地链接到 used_in_projects。

一款自适应 Web 爬虫框架，集 HTTP 请求、反检测浏览器、智能元素定位、并发爬虫和 AI 集成于一体，一个库覆盖从单页采集到全站爬取的全部需求。

为什么需要它

传统 Python 爬虫工具链是碎片化的：requests + BeautifulSoup 只能处理静态页面，遇到 Cloudflare 等反爬就歇菜；Selenium / Playwright 能跑浏览器但慢、重、且没有自适应能力；Scrapy 功能完整但学习曲线陡峭、同样缺乏反检测能力。更关键的是——网站一改版，选择器全废，维护成本极高。

Scrapling 把这些痛点一锅端：内建三级 Fetcher（HTTP → 动态渲染 → 隐身浏览器），自带自适应解析器让选择器”活过”网站改版，还有类 Scrapy 的 Spider 框架支撑大规模爬取。一个库替代 requests + BS4 + Playwright + Scrapy 的组合。

核心优势

• 自适应元素追踪：用 auto_save=True 记录元素指纹，网站改版后用 adaptive=True 自动重定位，不需要手动修复选择器。这是最大的差异化卖点。
• 三级 Fetcher 一体化：Fetcher（快速 HTTP）→ DynamicFetcher（Playwright 浏览器渲染）→ StealthyFetcher（反检测隐身模式，可绕 Cloudflare Turnstile），按需升级，API 统一。
• 类 Scrapy 的 Spider 框架：start_urls + parse 回调 + 并发控制 + 暂停/恢复 + 代理轮换，几行代码搭起完整爬虫。
• MCP Server：内置 AI 集成服务器，先精准提取内容再喂给 LLM，大幅减少 token 消耗。
• 极致解析性能：解析速度与 Parsel/Scrapy 持平，比 BeautifulSoup 快约 780 倍。

性能表现

官方 benchmark（5000 嵌套元素，100+ 次平均）：

自适应元素查找（相似元素搜索）：

[!note] 以上为项目自有 benchmark，使用合成 HTML 文档。实际性能因页面复杂度和网络条件而异，仅作相对参考。

快速上手

安装

# 1. 基础安装（仅解析引擎，无 fetcher）
pip install scrapling

# 2. 带 fetcher 的安装（含浏览器依赖）
pip install "scrapling[fetchers]"
scrapling install   # 下载浏览器及指纹伪装依赖

# 3. 带 AI/MCP 的安装
pip install "scrapling[ai]"
scrapling install

# 4. 全功能安装
pip install "scrapling[all]"
scrapling install

# 5. Docker（开箱即用，包含所有依赖）
docker pull pyd4vinci/scrapling

[!warning] Python 版本要求 必须使用 Python 3.10+，3.14 目前存在兼容性问题（#104）。

最小示例

from scrapling.fetchers import Fetcher

# 基础 HTTP 请求
page = Fetcher.get('https://quotes.toscrape.com/')

# CSS 选择器提取
for quote in page.css('.quote'):
    text = quote.css('.text::text').get()
    author = quote.css('.author::text').get()
    print(f"{author}: {text}")

# XPath 也支持
titles = page.xpath('//span[@class="text"]/text()').getall()

from scrapling.fetchers import StealthyFetcher

# 隐身模式绕过反爬（如 Cloudflare）
page = StealthyFetcher.fetch(
    'https://protected-site.com',
    headless=True,
    network_idle=True
)
products = page.css('.product', auto_save=True)  # 保存元素指纹

# 自适应解析：网站改版后自动重定位
page = Fetcher.get('https://example.com')
# 第一次：保存指纹
items = page.css('.product-card', auto_save=True)

# 网站改版后：自动找回
page2 = Fetcher.get('https://example.com')
items = page2.css('.product-card', adaptive=True)  # 即使选择器变了也能找到

Spider 示例（大规模爬取）

import asyncio
from scrapling.spiders import Spider, Request

class MySpider(Spider):
    start_urls = ['https://quotes.toscrape.com/page/1/']

    async def parse(self, 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::attr(href)').get()
        if next_page:
            yield Request(response.urljoin(next_page), callback=self.parse)

result = asyncio.run(MySpider.to_run())
print(result.items.to_json())

配置要点

适用场景

适合：

• 长期运行的数据采集任务（自适应解析大幅降低维护成本）
• 需要绕过 Cloudflare 等反爬系统的目标站
• 从小脚本到大爬虫的渐进式扩展（三级 Fetcher 平滑升级）
• AI 辅助数据提取（MCP Server 直接对接 Claude / Cursor）
• 替代 requests+BS4 的快速原型开发

不适合：

• 纯 Java/JS 技术栈的团队（Python only）
• 只需要简单 API 调用而非网页抓取（杀鸡用牛刀）
• 对内存极度敏感的嵌入式环境（浏览器模式开销大）
• 需要分布式爬取集群的企业级场景（目前是单机框架）

已知坑 & 注意事项

[!warning] Session 级代理可能泄露真实 IP #295 — Session 模式下代理设置可能被静默忽略，导致请求直连。使用前务必验证代理是否生效。

[!warning] init_script + user_data_dir 组合问题 #294 — 同时使用自定义脚本和用户数据目录会导致 ERR_NAME_NOT_RESOLVED。两者暂不建议同时启用。

[!warning] Python 3.14 不兼容 #104 — Camoufox 配置在 Python 3.14 下有问题，建议使用 3.10–3.13。

• 版本迭代快：0.4.x 仍在活跃开发中，API 可能有 breaking changes，升级前务必查看 Changelog
• 浏览器安装耗时：scrapling install 首次运行需下载浏览器和指纹数据，耗时数分钟
• 自适应不是万能的：40% 相似度阈值下可能误匹配，大改版后仍需人工验证

竞品对比

选择建议：

• 选 Scrapling：需要自适应解析 + 反检测 + 渐进式扩展，想一个库搞定一切
• 选 Scrapy：纯大规模爬取、分布式需求、已有 Scrapy 生态投资
• 选 BS4 + requests：快速一次性脚本、学习入门、对性能和反爬无要求
• 选 Playwright：纯浏览器自动化测试场景、非爬虫用途

生态 & 社区

• 维护状态：活跃开发中，v0.4.8（2026年5月），commit 频率高，多个社区贡献者
• 文档质量：好 — 有完整的 ReadTheDocs 文档站，涵盖解析、抓取、Spider、MCP 全链路，含代码示例
• 周边生态：
  • MCP Server（Claude / Cursor 集成）
  • CLI 工具（交互式 Shell、extract 命令）
  • Docker 镜像（开箱即用）
  • CrawlSpider / SitemapSpider 等通用模板
  • BeautifulSoup 迁移教程
• 社区活跃度：Issues 响应及时，有多个社区 PR 被合并，The Web Scraping Club 专题评测（2025.11）

引入评估

结论：推荐使用 — 如果你需要一款能从单页采集平滑升级到大规模爬取的 Python 爬虫工具，Scrapling 是目前最全面的选择。自适应解析和内建反检测是真正的杀手锏。但项目尚在快速迭代期（0.4.x），生产环境使用建议锁定版本并关注 Changelog。

推荐引入版本：0.4.8（避免使用 latest）

相关链接

前置知识：CSS选择器 · XPath 竞品：Scrapy · BeautifulSoup · Playwright 使用场景：数据采集 · 反爬与反检测 底层概念：无头浏览器 · HTTP协议 项目落地：[[ ]] · [[ ]]

• 官方文档
• GitHub 仓库
• Changelog
• The Web Scraping Club 评测
• ScrapingBee 深度评测

个人备注

{留白，供后续补充实际使用心得}