Scrapling 全栈实战指南：从单次请求到自适应抓取与大规模爬虫框架

Scrapling 是一个面向现代 Web 的自适应爬虫框架，用一套 Python 库同时覆盖三种场景：单页面 HTTP 请求、需要绕过反爬（Cloudflare Turnstile 等）的隐身浏览器抓取、以及支持并发/多会话/断点续爬的 Spider 爬虫框架。读完本篇，你将掌握 Scrapling 的三种 Fetcher 选型与 Session 用法、自适应解析（adaptive）机制、Spider 框架的并发与会话路由配置、CLI 免代码抓取命令，以及基于仓库源码核实的参数默认值与实现细节，可直接复制到项目中运行。

一、框架总览：一个库覆盖抓取全生命周期

Scrapling 的定位（见 README.md）可以用一段核心代码概括：

from scrapling.fetchers import Fetcher, AsyncFetcher, StealthyFetcher, DynamicFetcher

StealthyFetcher.adaptive = True
p = StealthyFetcher.fetch('https://example.com', headless=True, network_idle=True)  # 低特征抓取页面
products = p.css('.product', auto_save=True)          # 抓取并保存元素指纹，抵御网站改版
products = p.css('.product', adaptive=True)          # 网站结构变化后，靠自适应算法重新定位元素

以及规模化的爬虫入口：

from scrapling.spiders import Spider, Response

class MySpider(Spider):
    name = "demo"
    start_urls = ["https://example.com/"]

    async def parse(self, response: Response):
        for item in response.css('.product'):
            yield {"title": item.css('h2::text').get()}

MySpider().start()

从源码结构看，整个包分为四层：

目录	职责
scrapling/parser.py	核心解析器 Selector，支持 CSS/XPath/BS4 风格选择与自适应定位
scrapling/fetchers/	Fetcher（HTTP）、DynamicFetcher（浏览器）、StealthyFetcher（隐身浏览器）及各自 Session
scrapling/spiders/	Spider 框架：引擎、调度、会话管理、断点、限流、模板
scrapling/cli.py	命令行入口：install、shell、extract、mcp 子命令

Fetcher、DynamicFetcher、StealthyFetcher 等类通过 scrapling/fetchers/init.py 中的 __getattr__ 懒加载映射（_LAZY_IMPORTS）导入各自模块——这也是“只安装解析器不安装 fetchers 依赖时导入会报错”的底层原因（见第五节安装说明）。

1.1 核心能力清单

以下是 README 中列出的关键特性，后文将逐项展开：

• Spiders 完整爬虫框架：Scrapy 风格的 start_urls + 异步 parse 回调、可配置并发与按域限流、多会话路由、Ctrl+C 断点续爬、流式输出（spider.stream()）、被拦截请求自动检测重试、AutoThrottle 自适应延迟、可选 robots.txt 遵循、开发模式本地缓存回放、现成 Spider 模板（CrawlSpider/SitemapSpider/XMLFeedSpider/CSVFeedSpider/ShopifySpider）、独立 LinkExtractor、内置 JSON/JSONL/CSV/XML 导出。
• 高级网页抓取与 Session：TLS 指纹模拟的 HTTP 请求（含 HTTP/3）、Playwright Chromium/Chrome 浏览器自动化、可绕过 Cloudflare Turnstile 的隐身抓取、FetcherSession/StealthySession/DynamicSession 持久会话、内置 ProxyRotator 代理轮换、域名与广告请求拦截（约 3,500 个广告/追踪域名）、DNS-over-HTTPS 防泄漏、通过 cdp_url 连接远程浏览器、capture_xhr 后台捕获 XHR/fetch 响应、全异步支持。
• 自适应抓取与 AI 集成：基于相似度算法的元素重定位、CSS/XPath/过滤/文本/正则等多种选择方式、find_similar 相似元素定位、内置 MCP Server 供 AI 助手调用、可直接安装的 Agent Skill（agent-skill/）。
• 高性能架构：优化的数据结构与惰性加载、基于 orjson 的快速 JSON 序列化。
• 开发者体验：交互式抓取 Shell、终端免代码抓取、丰富的 DOM 导航 API、正则与文本清洗工具、自动生成 CSS/XPath 选择器、Scrapy 装饰器式集成（scrapling_response）、全类型注解（PyRight/MyPy 扫描）、随版本发布的完整 Docker 镜像。

二、Fetcher 三件套：HTTP、浏览器、隐身浏览器

Scrapling 提供三类抓取入口，README 中给出了各自的最小可用示例。

2.1 HTTP 请求（Fetcher / FetcherSession）

基于 curl_cffi（见 scrapling/fetchers/requests.py），可模拟浏览器的 TLS 指纹与 HTTP 头，并支持 HTTP/3：

from scrapling.fetchers import Fetcher, FetcherSession

with FetcherSession(impersonate='chrome') as session:  # 使用最新版 Chrome 的 TLS 指纹
    page = session.get('https://quotes.toscrape.com/', stealthy_headers=True)
    quotes = page.css('.quote .text::text').getall()

# 或一次性请求（不维护会话状态）
page = Fetcher.get('https://quotes.toscrape.com/')
quotes = page.css('.quote .text::text').getall()

要点：

• impersonate 指定要模拟的浏览器指纹（如 chrome、firefox135）；从 CLI 源码 可见，impersonate 支持逗号分隔的多个浏览器名，表示从中随机挑选。
• FetcherSession 上下文管理器会保持会话（Cookie/状态）直到 with 块结束，而 Fetcher.get 这类类方法是“一次性请求”风格。
• stealthy_headers=True 会为请求附加更贴近真实浏览器的 HTTP 头。

2.2 隐身模式（StealthyFetcher / StealthySession）

面向受反爬保护的站点，底层是打了指纹伪装的 Chromium：

from scrapling.fetchers import StealthyFetcher, StealthySession

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

# 或一次性请求：为本请求启动浏览器，完成后自动关闭
page = StealthyFetcher.fetch('https://nopecha.com/demo/cloudflare')
data = page.css('#padded_content a').getall()

solve_cloudflare 参数在 scrapling/fetchers/stealth_chrome.py 的文档字符串中说明为：“在返回响应前解决所有类型的 Cloudflare Turnstile/Interstitial 挑战”。StealthyFetcher.adaptive = True 则开启自适应元素定位（见第四节）。

2.3 完整浏览器自动化（DynamicFetcher / DynamicSession）

当需要点击、滚动等交互行为时使用，支持 Playwright Chromium 与 Google Chrome：

from scrapling.fetchers import DynamicFetcher, DynamicSession

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

# 或一次性请求风格
page = DynamicFetcher.fetch('https://quotes.toscrape.com/')
data = page.css('.quote .text::text').getall()

浏览器类 Fetcher 还具备以下能力（README 特性清单，对应实现位于 scrapling/engines/ 与 scrapling/engines/_browsers/）：

• 域名与广告拦截：可拦截指定域名及其子域名的请求，或启用内置广告拦截（约 3,500 个已知广告/追踪域名，见 scrapling/engines/toolbelt/ad_domains.py）；
• DNS 防泄漏：可选 DNS-over-HTTPS，将 DNS 查询经 Cloudflare DoH 路由；
• 远程浏览器：通过 cdp_url 连接已运行的浏览器（本机、其他主机或托管服务），或用 executable_path 指定自己的 Chromium 构建；
• 后台 API 捕获：给 capture_xhr 传 URL 模式，页面加载期间所有匹配的 XHR/fetch 响应会被收集为 response.captured_xhr 中的 Response 对象——无需逆向请求即可拿到站点 API 数据。

2.4 异步会话管理

所有 Fetcher 均提供异步版本，且同步 Session 类具有上下文感知能力，可同时用于同步/异步：

import asyncio
from scrapling.fetchers import FetcherSession, AsyncStealthySession, AsyncDynamicSession

async with FetcherSession(http3=True) as session:  # 同步/异步两种模式都能用
    page1 = session.get('https://quotes.toscrape.com/')
    page2 = session.get('https://quotes.toscrape.com/', impersonate='firefox135')

# 异步会话用法
async with AsyncStealthySession(max_pages=2) as session:
    tasks = []
    urls = ['https://example.com/page1', 'https://example.com/page2']

    for url in urls:
        task = session.fetch(url)
        tasks.append(task)

    print(session.get_pool_stats())  # 可选：浏览器标签页池状态（busy/free/error）
    results = await asyncio.gather(*tasks)
    print(session.get_pool_stats())

max_pages 控制浏览器标签页池大小，get_pool_stats() 用于观测池内标签页的忙/闲/错误分布。

三、Spider 爬虫框架：并发、多会话与断点续爬

Spider 框架位于 scrapling/spiders/，API 风格对齐 Scrapy：start_urls + 异步 parse + Request/Response 对象。

3.1 基础爬虫：并发翻页

from scrapling.spiders import Spider, Request, 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()
print(f"Scraped {len(result.items)} quotes")
result.items.to_json("quotes.json")

从 scrapling/spiders/spider.py 的类属性默认值可确认各配置项：

属性	默认值	说明
concurrent_requests	4	全局并发请求数
concurrent_requests_per_domain	0	单域并发上限（0 表示不限）
download_delay	0.0	下载延迟（秒）
max_blocked_retries	3	被拦截请求的最大重试次数
robots_txt_obey	False	是否遵循 robots.txt
development_mode	False	开发模式：首次请求缓存到磁盘，之后回放
autothrottle_enabled	False	是否启用自适应限流
autothrottle_start_delay	5.0	AutoThrottle 起始延迟（秒）
autothrottle_max_delay	60.0	AutoThrottle 延迟上限（秒）
allowed_domains	set()	允许抓取的域名集合

被拦截判定基于状态码集合 BLOCKED_CODES = {401, 403, 407, 429, 444, 500, 502, 503, 504}（spider.py#L16），并可通过覆写 is_blocked(response) 与 retry_blocked_request(request, response) 自定义检测与重试逻辑。

start(use_uvloop=False, **backend_options) 是主入口，内部通过 anyio 运行 asyncio 事件循环；README 提示按 Ctrl+C 优雅暂停（等待活动任务完成后保存 checkpoint），再按一次则强制停止。

3.2 多会话路由：一个 Spider 混合使用 HTTP 与隐身浏览器

通过覆写 configure_sessions(manager) 注册多个会话，再用 Request(link, sid=...) 按 ID 路由：

from scrapling.spiders import Spider, Request, Response
from scrapling.fetchers import FetcherSession, AsyncStealthySession

class MultiSessionSpider(Spider):
    name = "multi"
    start_urls = ["https://example.com/"]

    def configure_sessions(self, manager):
        manager.add("fast", FetcherSession(impersonate="chrome"))
        manager.add("stealth", AsyncStealthySession(headless=True), lazy=True)

    async def parse(self, response: Response):
        for link in response.css('a::attr(href)').getall():
            if "protected" in link:
                yield Request(link, sid="stealth")   # 受保护页面走隐身会话
            else:
                yield Request(link, sid="fast", callback=self.parse)  # 显式 callback

从源码看，configure_sessions 的默认实现是向 manager 添加一个名为 "default" 的 FetcherSession（spider.py#L218-L230）；第一个添加的会话成为 start_requests() 的默认会话；若一个会话都未添加会抛出 SessionConfigurationError。lazy=True 表示该会话在首次被路由到时才真正初始化（适合昂贵资源的浏览器会话）。

3.3 断点续爬（Pause & Resume）

QuotesSpider(crawldir="./crawl_data").start()

crawldir 传入即启用 checkpoint 持久化：按 Ctrl+C 优雅退出时进度自动保存（Spider.__init__ 的 interval 参数控制周期性保存间隔，默认 300 秒，见 spider.py#L106-L111）；下次启动时传入相同 crawldir 即从断点恢复，on_start(resuming=True) 回调可用于区分恢复场景。

3.4 流式模式与现成模板

流式模式适合长任务与 UI 集成——items 边抓边出，spider.stats 提供实时统计（stream() 不支持 SIGINT 暂停，见 spider.py#L304-L323）：

async for item in spider.stream():
    print(item)
    print(spider.stats)  # 实时统计

不想写抓取逻辑时可直接继承模板（scrapling/spiders/templates/）：

模板	场景	位置
CrawlSpider	基于规则（CrawlRule）的链接跟随	crawler.py
SitemapSpider	sitemap/robots.txt 驱动的抓取	sitemap.py
XMLFeedSpider / CSVFeedSpider	迭代 XML/RSS 与 CSV 数据源	feed.py
ShopifySpider	通过 JSON API 抽取任意 Shopify 商店全部商品，每个变体一条 item	shopify.py

Shopify 模板示例（README 原文）：

from scrapling.spiders import ShopifySpider

class MyStore(ShopifySpider):
    target_website = "example.com"

result = MyStore().start()  # 商店内每个商品，每个变体一条 item

从 shopify.py 的实现看，target_website 也可用 start_urls 或 allowed_domains 替代，三者缺失其一会抛出 ValueError；它依次抓取 collections 与 products 的 JSON 端点并处理翻页。

此外还有独立原语 LinkExtractor（scrapling/spiders/links.py）：支持 allow/deny 模式、域名过滤、CSS/XPath 作用域、扩展名过滤与 URL 规范化；结果导出方面，除 on_scraped_item 等钩子外，result.items 提供 to_json()、to_jsonl()、to_csv()、to_xml() 内置导出（scrapling/spiders/result.py）。

四、自适应解析：让选择器在网站改版后继续工作

这是 Scrapling 区别于普通库的核心能力。解析器主类是 scrapling/parser.py 中的 Selector，Selector.__init__ 接受全局开关 adaptive（该参数优先级高于所有方法级 adaptive 参数）以及 storage（自适应存储类，需继承 StorageSystemMixin）。

4.1 丰富的元素选择与导航

from scrapling.fetchers import Fetcher

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'})   # BeautifulSoup 风格
quotes = page.find_all('div', class_='quote')
quotes = page.find_all(['div'], class_='quote')
quotes = page.find_all(class_='quote')
quotes = page.find_by_text('quote', tag='div')      # 按文本内容查找

# 导航与链式调用
quote_text = page.css('.quote')[0].css('.text::text').get()
quote_text = page.css('.quote').css('.text::text').getall()  # 链式选择器
first_quote = page.css('.quote')[0]
author = first_quote.next_sibling.css('.author::text')
parent_container = first_quote.parent

# 元素关系与相似度
similar_elements = first_quote.find_similar()   # 找到与指定元素相似的其他元素
below_elements = first_quote.below_elements()

不抓取网页时也可直接用解析器：

from scrapling.parser import Selector

page = Selector("<html>...</html>")

其 API 与抓取返回的 Response 完全一致。

4.2 adaptive / auto_save / identifier 机制

从 parser.py 中 css/xpath 等方法的签名与文档字符串看，自适应相关参数为：

• auto_save: bool = False —— 首次选取时自动保存元素指纹，供日后 adaptive 重定位使用；
• adaptive: bool = False —— 启用后，若元素曾被保存，则尝试用相似度算法在新页面中重定位；
• identifier —— 在自适应存储中保存/读取元素数据的标识字符串；
• percentage —— 自适应匹配可接受的最低相似度百分比。

参数组合有明确约束（源码中会抛出 ValueError）：Selector 未以 adaptive=True 初始化时，auto_save 会被忽略；已开启全局 adaptive 时，方法层的 adaptive 参数也会被忽略。README 开头的示例即展示了标准工作流：先 auto_save=True 存档，改版后 adaptive=True 重新定位。更细节的存储系统设计见 docs/development/adaptive_storage_system.md。

五、CLI、交互式 Shell 与 MCP

Scrapling 附带完整命令行接口（入口为 scrapling/cli.py，pip 安装后注册 scrapling 与 scrapling-mcp 两个可执行命令，见 pyproject.toml#L107-L109）。

5.1 交互式抓取 Shell

scrapling shell

启动带 Scrapling 集成的 IPython 控制台（-c 可求值一段代码后退出，-L 设置日志级别，默认 debug）。Shell 内置工具包括把 curl 请求转换为 Scrapling 请求、在浏览器中查看请求结果等（对应 scrapling/core/_shell.py 与 scrapling/core/shell.py）。

5.2 免代码抓取：extract 命令

scrapling extract get 'https://example.com' content.md
scrapling extract get 'https://example.com' content.txt --css-selector '#fromSkipToProducts' --impersonate 'chrome'
scrapling extract fetch 'https://example.com' content.md --css-selector '#fromSkipToProducts' --no-headless
scrapling extract stealthy-fetch 'https://nopecha.com/demo/cloudflare' captchas.html --css-selector '#padded_content a' --solve-cloudflare

输出格式由文件后缀决定（默认抽取 <body> 内内容）：

后缀	输出
.txt	目标元素的纯文本
.md	HTML 内容的 Markdown 表示
.html	HTML 内容本身

三个子命令分别对应 HTTP（get）、浏览器（fetch）、隐身浏览器（stealthy-fetch），--css-selector 限定抽取范围，--impersonate 指定 TLS 指纹。

5.3 MCP Server（AI 集成）

安装 scrapling[ai] 后可用 scrapling-mcp 启动 MCP Server，供 Claude/Cursor 等 AI 客户端调用。从 cli.py#L145-L185 看，它支持 stdio 与 streamable-http 两种传输（--http --host --port，端口默认 8000）、自定义浏览器可执行文件（--executable-path）、Bearer Token 鉴权（--auth-token，也可用环境变量 SCRAPLING_MCP_AUTH_TOKEN）以及防 DNS 重绑定的 --allowed-host。其设计意图是先由 Scrapling 抽取目标内容再交给 AI，从而减少 token 消耗；MCP Server 还能跨调用保持浏览器会话、截屏、通过 CDP 驱动远程浏览器。更多细节见 docs/ai/mcp-server.md。仓库同时提供了面向编码 Agent 的 Agent Skill，让 AI 生成的代码对齐当前 API。

六、性能基准

README 给出了解析器在 5000 个嵌套元素上提取文本的对比（100 次以上运行的均值，测试脚本为 benchmarks.py，其中定义了 test_scrapling、test_bs4_lxml、test_selectolax 等对比函数）：

#	库	耗时 (ms)	相对 Scrapling
1	Scrapling	1.99	1.0x
2	Parsel/Scrapy	2.06	1.035
3	Raw Lxml	2.56	1.286
4	PyQuery	23.98	约 12x
5	Selectolax	197.02	约 99x
6	MechanicalSoup	1545.15	约 776.5x
7	BS4 + Lxml	1562.1	约 785.0x
8	BS4 + html5lib	3412.73	约 1714.9x

元素相似度与文本搜索（自适应能力的核心路径）对比：

库	耗时 (ms)	相对 Scrapling
Scrapling	2.3	1.0x
AutoScraper	12.58	5.47x

JSON 序列化方面，Scrapling 基于 orjson（核心依赖之一，见 pyproject.toml#L63-L70），README 声称比标准库 json 快约 10 倍。

七、安装与依赖矩阵

Scrapling 要求 Python 3.10 及以上（pyproject.toml 中 requires-python = ">=3.10"，classifier 覆盖 3.10–3.13），基础安装只含解析引擎：

pip install scrapling

重要：该安装仅包含解析器及其依赖（lxml、cssselect、orjson、tld、w3lib 等）。此时 from scrapling.fetchers import ... 或 from scrapling.spiders import ... 会抛出 ModuleNotFoundError——原因是 fetchers 依赖（curl_cffi、playwright、patchright 等，见 pyproject.toml#L72-L83）未安装。

7.1 可选依赖分组

extras	内容	安装命令
fetchers	fetchers 与浏览器依赖（click、curl_cffi、playwright、patchright、browserforge 等）	pip install "scrapling[fetchers]"
ai	MCP Server（mcp、markdownify，含 fetchers）	pip install "scrapling[ai]"
shell	交互 Shell 与 extract 命令（IPython、markdownify，含 fetchers）	pip install "scrapling[shell]"
all	以上全部	pip install "scrapling[all]"

安装 fetchers extras 后，还需下载浏览器及其系统依赖、指纹伪装依赖：

scrapling install           # 常规安装
scrapling install --force   # 强制重装

从 cli.py#L120-L142 的实现看，scrapling install 实际执行 python -m playwright install chromium 与 playwright install-deps chromium，再更新 tld 数据，最后写入标记文件 .scrapling_dependencies_installed（--force 可跳过该标记）。也可以在代码中调用：

from scrapling.cli import install

install([], standalone_mode=False)          # 常规安装
install(["--force"], standalone_mode=False) # 强制重装

7.2 Docker

官方提供包含全部 extras 与浏览器的镜像：

docker pull pyd4vinci/scrapling
# 或从 GitHub 容器仓库拉取
docker pull ghcr.io/d4vinci/scrapling:latest

镜像基于仓库主分支由 CI 自动构建推送（构建配置见 Dockerfile）。

八、工程化配套：测试、类型与集成

• 测试：仓库包含完整的测试树（tests/），覆盖 fetchers 同步/异步、spiders 引擎与断点、parser 自适应、CLI 等模块；README 声称测试覆盖率 92%，CI 状态见仓库工作流徽章。
• 类型检查：整个代码库每次变更都经过 PyRight 与 MyPy 自动扫描（pyproject.toml#L119-L129 中已内置两套工具的基线配置），py.typed 标记文件（scrapling/py.typed）使其类型注解对下游 IDE 生效。
• Scrapy 集成：已有 Scrapy 项目可通过装饰器 scrapling_response 让 Scrapy 抓到的响应直接用 Scrapling 解析器解析，无需重写（实现位于 scrapling/integrations/scrapy.py，文档见 docs/integrations/scrapy.md）。
• 代理轮换：ProxyRotator（scrapling/engines/toolbelt/proxy_rotation.py）默认采用循环轮换策略，也接受自定义策略函数（签名 (proxies, current_index) -> (proxy, next_index)），并支持按请求覆盖代理；用法详见 docs/api-reference/proxy-rotation.md。
• 合规提醒：README 声明该库仅供教育与研究用途，使用者需遵守当地与国际数据抓取及隐私法规、目标网站的 ToS 与 robots.txt（Spider 也提供 robots_txt_obey 开关辅助合规）。

九、小结：按场景选型

场景	推荐路径
简单静态页面、单条请求	Fetcher.get(...) / FetcherSession
有 Cloudflare 等反爬的页面	StealthyFetcher.fetch(..., solve_cloudflare=True) 或 StealthySession
需要交互/动态渲染	DynamicFetcher / DynamicSession
网站频繁改版	StealthyFetcher.adaptive = True + auto_save/adaptive 参数
大规模站点抓取	Spider 子类：并发、多会话 sid 路由、crawldir 断点、stream() 流式输出
站点结构高度标准化	直接继承 CrawlSpider/SitemapSpider/ShopifySpider 等模板
不写代码快速取数	scrapling extract get/fetch/stealthy-fetch
让 AI 助手代写抓取代码	安装 Agent Skill 或启用 scrapling-mcp MCP Server

所有功能的完整参数文档位于仓库内 docs/ 目录（抓取选型见 docs/fetching/choosing.md，Spider 架构见 docs/spiders/architecture.md，选择器 API 见 docs/parsing/selection.md）。项目采用 BSD-3-Clause 许可证（LICENSE），核心解析部分包含改编自 Parsel 的代码（scrapling/core/translator.py）。