Scrapling 自适应网页抓取手册¶

作者：Bob 最后更新：2026-06-14 定位：用 Scrapling（D4Vinci/Scrapling，63k★ Python 库）做"抓竞品站 / 支付渠道页 / 行情汇率 / 印尼菲律宾本地站"的高效、抗反爬、低维护抓取。 底层逻辑：Scrapling 把"高性能解析 + 反反爬（绕 Cloudflare）+ 自适应定位（改版自动找回元素）+ 爬虫框架 + MCP（AI 集成）"五合一打包，一个库覆盖从单请求到大规模爬取。

0. TL;DR¶

它是什么：Python 3.10+ 的自适应网页抓取框架，BSD-3 协议（商业可用），维护非常活跃（最新 v0.4.9，2026-06-07）。
两大杀手锏：① 自适应定位——网站改版后用元素"指纹"自动重新找到它，脚本不报错；② 反反爬——StealthyFetcher 内置隐身浏览器 + TLS 指纹伪装，开箱即可解 Cloudflare Turnstile。
怎么开始：pip install "scrapling[fetchers]" && scrapling install，三档 Fetcher 按反爬强度递增选用。

1. 它解决什么问题（对比主流工具）¶

传统爬虫两大痛点，Scrapling 针对性破解： 1. 选择器易碎：网站改版后 CSS/XPath 失效，脚本批量报错要人工逐个修 → Scrapling 记住元素特征，改版后自动重定位。 2. 反爬越来越强：Cloudflare / Turnstile / TLS 指纹检测让普通 requests 直接被墙 → Scrapling 内置浏览器 TLS 指纹伪装 + 隐身浏览器。

工具	角色	与 Scrapling 的关系
BeautifulSoup	纯 HTML 解析器，无抓取/反爬	Scrapling 解析快约 780 倍，且自带抓取+反爬+自适应
Scrapy	重型框架，学习陡，反爬要装一堆中间件	解析速度与 Scrapy 的 Parsel 持平，但 API 更轻、反爬内置、有自适应；自带 Spider 框架
Selenium/Playwright	浏览器自动化，慢、易被识别	Scrapling 把 Playwright 封进 `DynamicFetcher`，再加反指纹隐身层 `StealthyFetcher`
AutoScraper	也做相似元素匹配	Scrapling 相似度搜索快约 5.2 倍

核心差异化：唯一把五大能力（解析 + 反反爬 + 自适应 + 爬虫框架 + MCP）一次打包的库。

2. 核心卖点¶

2.1 自适应定位 / auto-match（最大卖点）¶

两阶段机制： - 保存阶段（auto_save=True）：首次选中元素时，把它的"指纹"存进本地 SQLite——标签名、文本、属性、兄弟节点标签、路径结构、父节点信息。 - 匹配阶段（adaptive=True）：原选择器失效（改版）时，取出指纹对页面所有元素打相似度分，返回最匹配的那个。 - 存储索引：用"域名 + 标识符（默认就是选择器字符串）"两键定位指纹。

意义：竞品站改版后脚本不报错、自动找回元素，大幅降低维护成本。

2.2 三档 Fetcher（按反爬强度递增）¶

Fetcher：快速 HTTP，自带浏览器 TLS 指纹伪装（impersonate）。对付只看 UA/TLS 的站够用，最快。
StealthyFetcher：隐身浏览器 + 指纹欺骗，能解 Cloudflare Turnstile（solve_cloudflare=True）。
DynamicFetcher：完整 Playwright Chromium，适合重 JS 的 SPA。
每档都有 Session 变体（维持登录态/Cookie）和异步版。

2.3 其他¶

高性能：5000 嵌套元素解析 2.02ms，同类最快档。
反反爬工具箱：代理轮换、按域名限流并发、广告/追踪域名拦截（内置约 3500 个）、DNS-over-HTTPS 防 DNS 泄漏、robots.txt 合规缓存。
Spider 爬虫框架：Scrapy 风格 API，支持多 Session 路由、Ctrl+C 暂停/断点续爬、流式消费、自动检测被封重试、JSON/JSONL 导出。
内置 MCP Server：pip install "scrapling[ai]" 后可被 Claude/Cursor 调用——先抓取精炼再喂 AI，省 token。

3. 安装¶

pip install scrapling                 # 仅解析器（最小）
pip install "scrapling[fetchers]"     # 抓取 + 浏览器（常用）
scrapling install                     # 安装浏览器二进制依赖，必须跑
pip install "scrapling[ai]"           # MCP server（AI 集成）
pip install "scrapling[shell]"        # 交互式 shell
pip install "scrapling[all]"          # 全家桶
# Docker
docker pull pyd4vinci/scrapling

⚠️ 仍是 0.x 版本，生产环境锁定版本号（如 scrapling==0.4.9），升级前回归测试。

4. 核心 API 用法（可复制）¶

4.1 Fetcher — 快速 HTTP + TLS 指纹伪装¶

from scrapling.fetchers import Fetcher, FetcherSession

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

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

4.2 StealthyFetcher — 解 Cloudflare¶

from scrapling.fetchers import StealthyFetcher, StealthySession

page = StealthyFetcher.fetch('https://nopecha.com/demo/cloudflare')

with StealthySession(headless=True, solve_cloudflare=True) as session:
    page = session.fetch('https://nopecha.com/demo/cloudflare', google_search=False)
    data = page.css('#padded_content a').getall()

4.3 DynamicFetcher — 完整浏览器（重 JS）¶

from scrapling.fetchers import DynamicFetcher, DynamicSession

page = DynamicFetcher.fetch('https://quotes.toscrape.com/')

with DynamicSession(headless=True, network_idle=True) as session:
    page = session.fetch('https://quotes.toscrape.com/', load_dom=False)
    data = page.xpath('//span[@class="text"]/text()').getall()

4.4 选择器与提取¶

page = Fetcher.get('https://quotes.toscrape.com/')

quotes = page.css('.quote')                          # CSS
quotes = page.xpath('//div[@class="quote"]')         # XPath
quotes = page.find_all('div', {'class': 'quote'})    # BS4 风格
quotes = page.find_by_text('quote', tag='div')       # 按文本找

text  = page.css('.quote .text::text').get()         # 单个文本
texts = page.css('.quote .text::text').getall()      # 全部文本
href  = page.css('.next a::attr(href)').get()        # 属性

first  = page.css('.quote')[0]
parent = first.parent
similar = first.find_similar()                       # 找结构相似元素

4.5 自适应定位 — 改版后自动找回¶

from scrapling import Fetcher

Fetcher.configure(adaptive=True, adaptive_domain='target-site.com')
page = Fetcher.get('https://target-site.com')

element = page.css('#price', auto_save=True)    # 首次：保存指纹
element = page.css('#price', adaptive=True)     # 改版后：用指纹自动重定位
products = page.css('.product', adaptive=True)  # 一组元素也行

4.6 分页 / Spider 框架¶

from scrapling.spiders import Spider, 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()
result.items.to_json("quotes.json")
QuotesSpider(crawldir="./crawl_data").start()   # 断点续爬

4.7 命令行（零代码）¶

scrapling shell                                            # 交互调试
scrapling extract get 'https://example.com' content.md     # 抓成 markdown
scrapling extract stealthy-fetch 'https://site.com' out.html \
  --css-selector '#padded_content a' --solve-cloudflare

5. 性能基准（README 官方）¶

文本提取 5000 嵌套元素（越小越快）：Scrapling 2.02ms ≈ Parsel(2.04) < Raw Lxml(2.54) ≪ PyQuery(24) ≪ BS4+Lxml(1584，约 784×)。相似搜索：Scrapling 2.39ms vs AutoScraper 12.45ms（快 5.2×）。

6. 在 iGaming 运营场景的实战用法¶

针对"抓竞品站、支付渠道页、行情数据、印尼/菲律宾本地站"：

竞品博彩站（几乎都挂 Cloudflare）→ StealthyFetcher + solve_cloudflare

from scrapling.fetchers import StealthySession
with StealthySession(headless=True, solve_cloudflare=True) as s:
    page = s.fetch('https://competitor-site.com/promotions')
    promos  = page.css('.promo-card .title::text').getall()   # 活动话术
    bonuses = page.css('.bonus-amount::text').getall()        # 优惠金额

抓竞品活动、赔率、优惠政策、落地页文案，喂进知识库做对标。

竞品改版频繁 → 全程开 adaptive=True：博彩站常换 DOM 规避封锁/做 A-B，给赔率、优惠额、入口链接加 auto_save / adaptive，免去每周修选择器。
支付渠道页（QRIS/DANA/OVO/GoPay 状态页、汇率页）→ Fetcher 够用：静态/轻 JS 用最快的 Fetcher.get(...impersonate='chrome') 定时抓渠道公告、维护通知、限额变更；重 JS 的用 DynamicFetcher。
行情/汇率 → Spider 框架定时批量 + JSONL 落库：多站点并发 + 按域名限速避风控 + 断点续爬应对中途被封。
印尼/菲律宾本地站 → 配本地住宅代理 + 隐身：本地新闻、支付生态、监管动态常有地域限制，配本地住宅代理 + Scrapling 内置代理轮换。
接 AI 总结 → 上 MCP：scrapling[ai] 的 MCP server 让 Claude 直接调 Scrapling 抓取精炼竞品页再总结成对标报告。

7. 注意事项与风险¶

合规/法律（博彩行业尤其敏感）：抓竞品/第三方站可能违反对方 ToS，部分辖区对自动化抓取有法律限制。仅用于内部调研，勿转载/再分发对方受版权内容。

被封 IP 的应对（实操）： 1. 必上代理池：印尼/菲律宾住宅代理（机房 IP 秒封），开内置代理轮换。 2. 限速：按域名限流 + download delay，模拟人类节奏。 3. 指纹一致：impersonate 选定一种浏览器后保持一致。 4. 被封自动退避：Spider 内置"检测被封重试" + 代理轮换换 IP。 5. Cloudflare 解不动：升 StealthyFetcher + solve_cloudflare=True；仍失败说明上了行为验证码，需人工或第三方打码。 6. DNS 泄漏：开 DNS-over-HTTPS。

技术风险：0.x 锁版本号、升级回归测试；solve_cloudflare 非 100% 成功（Cloudflare 持续对抗，关注 release）；浏览器型 Fetcher 资源占用高，大并发控 max_pages/并发数防内存爆。

8. 关键链接¶

仓库：https://github.com/D4Vinci/Scrapling
文档：https://scrapling.readthedocs.io/en/latest/
自适应原理：https://scrapling.readthedocs.io/en/latest/parsing/adaptive/
最新版：https://github.com/D4Vinci/Scrapling/releases

数据来源：官方 README、文档、gh 仓库元数据（2026-06-14）。