Scrapling 完全指南从单请求抓取到自适应大规模爬虫的 Python 框架【免费下载链接】Scrapling️ An adaptive Web Scraping framework that handles everything from a single request to a full-scale crawl!项目地址: https://gitcode.com/GitHub_Trending/sc/Scrapling本文以 Scrapling 官方文档入口docs/index.md为主体系统梳理这一自适应 Web 抓取框架的三大核心能力——学习型解析器、抗反爬 Fetcher 体系与 Scrapy 风格 Spider 框架并结合仓库源码补充安装分层、adaptive机制的底层实现与调用链帮助读者在 30 分钟内建立起可落地的完整使用路径。一、框架定位一条库覆盖从单请求到全站爬取Scrapling 的官方定位是一个自适应 Web 抓取框架adaptive Web Scraping framework设计目标是让同一套库覆盖从抓一个页面到全站并发爬取的所有规模。文档首页给出的三句话概括了它的核心差异化解析器会学习网站变化当目标页面改版后Scrapling 能自动重新定位你之前保存过的元素而不是让选择器失效Fetcher 开箱即用地绕过反爬内置对 Cloudflare Turnstile / Interstitial 的自动化绕过能力Spider 框架负责规模化支持并发、多会话爬取、断点续传pause/resume与自动代理轮换。官方文档给出的最简示例展示了抓取 → 解析 → 自适应复定位的完整闭环from scrapling.fetchers import Fetcher, StealthyFetcher, DynamicFetcher StealthyFetcher.adaptive True page StealthyFetcher.fetch(https://example.com, headlessTrue, network_idleTrue) # 隐身抓取 products page.css(.product, auto_saveTrue) # 首次抓取时保存元素数据 products page.css(.product, adaptiveTrue) # 网站改版后用 adaptiveTrue 重新找到它们而放大到全站爬取时代码形态与 Scrapy 高度相似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()这个类 Scrapy API的设计贯穿整个 Spider 框架对已有 Scrapy 经验的开发者几乎是零迁移成本。二、安装与环境分层依赖是理解 Scrapling 的第一把钥匙Scrapling 要求Python 3.10 或更高版本pyproject.toml 中requires-python 3.10classifiers 覆盖到 3.13基础安装只包含解析引擎pip install scrapling这里有一个必须注意的分层依赖设计基础安装只装了解析器parser及其依赖不包含任何 fetcher 或命令行依赖。也就是说仅执行pip install scrapling后from scrapling.fetchers import ...或from scrapling.spiders import ...都会抛出ModuleNotFoundError。这一点在源码结构上可以印证scrapling/fetchers/init.py 采用惰性导入__getattr___LAZY_IMPORTS映射只有 fetcher 第三方依赖curl_cffi、playwright 等存在时才能真正加载。基础依赖在 pyproject.toml 中声明为lxml、cssselect、orjson、tld、w3lib、typing_extensions——这解释了为什么纯解析场景下 Scrapling 依然轻量。2.1 按需安装 Fetcher 依赖如果要用Fetcher/StealthyFetcher/DynamicFetcher或任何 Spider需要额外安装 fetcher 依赖并下载浏览器pip install scrapling[fetchers] scrapling install # 常规安装下载浏览器及系统依赖、指纹操纵依赖 scrapling install --force # 强制重新安装也可以不走命令行直接在代码中触发安装from scrapling.cli import install install([], standalone_modeFalse) # 常规安装 install([--force], standalone_modeFalse) # 强制重装从 pyproject.toml 的可选依赖声明看fetchers这一 extras 实际拉取了curl_cffiTLS 指纹伪造、playwrightChromium 自动化、patchright反检测的 Playwright 分支、browserforge与apify-fingerprint-datapoints浏览器指纹生成、protegorobots.txt 解析等——这也解释了为什么浏览器指纹伪造能力需要单独的scrapling install步骤。2.2 其他可选功能与 Docker功能安装命令对应源码入口MCP ServerAI 集成pip install scrapling[ai]命令行入口scrapling-mcp交互式 Shell 与extract命令pip install scrapling[shell]scrapling/core/shell.py全部功能pip install scrapling[all]等价于[ai,shell]免安装镜像docker pull pyd4vinci/scrapling或docker pull ghcr.io/d4vinci/scrapling:latestDockerfileDocker 镜像包含全部 extras 和所有浏览器由 GitHub Actions 基于 main 分支自动构建推送免去本地装浏览器的折腾。三、Fetcher 体系三类抓取器 会话 反爬工具箱3.1 三个 Fetcher 与对应会话类scrapling.fetchers包通过 scrapling/fetchers/init.py 的惰性导入对外暴露 10 个类按抓取方式 × 同步/异步组织能力无状态抓取器有状态会话类底层实现快速隐身 HTTP 请求可伪造浏览器 TLS 指纹、请求头支持 HTTP/3Fetcher/AsyncFetcherFetcherSessionscrapling/fetchers/requests.py完整浏览器自动化Playwright Chromium 与 Google ChromeDynamicFetcherDynamicSession/AsyncDynamicSessionscrapling/fetchers/chrome.py高级隐身指纹欺骗绕过 Cloudflare Turnstile/InterstitialStealthyFetcherStealthySession/AsyncStealthySessionscrapling/fetchers/stealth_chrome.pyProxyRotator也从这个包直接导出可用于所有会话类型。选择哪个 Fetcher 的完整决策指南见 docs/fetching/choosing.md静态、动态、隐身三类分别有 docs/fetching/static.md、docs/fetching/dynamic.md、docs/fetching/stealthy.md 专题文档。3.2 文档首页列出的进阶能力除了三类 Fetcher首页还罗列了一组实用特性均落在scrapling/engines目录的工具带中代理轮换内置ProxyRotator支持循环cyclic或自定义策略跨所有会话类型生效且支持按请求覆盖代理实现见 scrapling/engines/toolbelt/proxy_rotation.py域名与广告拦截可阻断对特定域名含子域的请求或在浏览器型 Fetcher 中启用内置广告拦截约 3,500 个已知广告/追踪域名域表见 scrapling/engines/toolbelt/ad_domains.py;防 DNS 泄漏可选 DNS-over-HTTPS将 DNS 查询路由至 Cloudflare DoH避免使用代理时 DNS 泄漏远程浏览器通过cdp_url用 CDP 连接已运行的浏览器本机、他机或托管浏览器服务均可也可用executable_path指向自建的 Chromium后台 API 捕获给capture_xhr传入 URL 模式页面加载期间所有匹配的 XHR/fetch 响应会作为Response对象收集进response.captured_xhr——无需逆向请求即可拿到网站的 API 数据完整异步支持所有 Fetcher 与对应的异步会话类。3.3adaptive类属性到底做了什么首页示例中StealthyFetcher.adaptive True这行容易被忽视但它正是自适应抓取的总开关。从源码看该属性定义在 Fetcher 基类的配置模型中scrapling/engines/toolbelt/custom.py 中adaptive: Optional[bool] FalseFetcher 将其传递给构造出的 Response只有当它被开启时page.css(selector, auto_saveTrue)才会真正把命中元素的结构指纹持久化保存下来。若未开启css()会明确告警auto_savewill be ignored becauseadaptivewasnt enabled on initialization见 scrapling/parser.py 中xpath方法的守卫逻辑约 L658-L686。3.4css()/xpath()的自适应参数详解scrapling/parser.py 中Selector.css()L566-L624与Selector.xpath()L626 起接受四个与自适应相关的参数这是官方文档 docs/parsing/adaptive.md 的源码级注脚参数默认值作用adaptiveFalse若该选择器此前保存过则尝试在新页面上重新定位元素auto_saveFalse自动保存本次命中的元素供后续adaptive复定位使用identifier保存/检索时使用的标识符不传则用选择器本身。官方建议计划日后更换选择器时务必显式指定percentage40复定位时的最低相似度百分比阈值。注意相似度计算只依赖页面结构非必要时不要随意调低复定位的核心算法在relocate()中scrapling/parser.py L540-L564 附近遍历页面上所有元素逐一与保存的元素数据计算相似度得分即使出现 100% 的匹配也不提前停止因为可能还有其他同分元素最后取最高分档——只有最高分 ≥percentage才返回结果否则发出告警提示可以调低percentage。这解释了为什么auto_save是一次性动作、而adaptiveTrue可以反复使用。此外css()的实现细节值得一提Scrapling 将 CSS 选择器先翻译为 XPath 再交给 lxml 执行_css_to_xpath并且支持::text、::attr()等 Scrapy/Parsel 风格的伪元素这对从 BeautifulSoup/Scrapy 迁移的用户是无缝的迁移指南见 docs/tutorials/migrating_from_beautifulsoup.md。四、Spider 框架Scrapy 式 API 的全功能爬取引擎Spider 框架是 Scrapling 从抓取库升级为爬取框架的关键源码位于 scrapling/spiders/ 目录engine.py、scheduler.py、session.py、checkpoint.py、throttle.py等模块各司其职专题文档从 docs/spiders/getting-started.md 开始架构与请求/响应模型分别在 docs/spiders/architecture.md 和 docs/spiders/requests-responses.md。首页对 Spider 特性的完整清单原文档逐条继承如下每条都值得展开类 Scrapy 的 Spider API用start_urls、异步parse回调、Request/Response对象定义爬虫并发爬取可配置的并发上限、按域限速per-domain throttling与下载延迟限速实现见 scrapling/spiders/throttle.py多会话支持在同一个 Spider 里统一使用 HTTP 请求与隐身无头浏览器按会话 ID 把请求路由到不同会话会话管理见 scrapling/spiders/session.py暂停与续爬基于检查点的爬取持久化——CtrlC优雅退出重启后从上次中断处继续实现见 scrapling/spiders/checkpoint.py流式模式async for item in spider.stream()实时消费抓取项并伴随实时统计适合 UI、数据管道与长时爬取;被封检测自动检测被阻断的请求并重试检测逻辑可自定义AutoThrottleSpider 根据网站响应速度自行调节每个域名的延迟一旦网站开始封禁/限流就加倍延迟或遵循Retry-After压力解除后再提速——不再靠拍脑袋设 delayRobots.txt 合规可选robots_txt_obey标志遵循Disallow、Crawl-delay、Request-rate指令并按域缓存解析器 scrapling/spiders/robotstxt.py开发模式首次运行把响应缓存到磁盘后续运行直接回放——迭代parse()逻辑时不再重复轰炸目标服务器现成 Spider 模板scrapling/spiders/templates/CrawlSpider基于规则的链接跟随SitemapSpider由 sitemap/robots.txt 驱动的爬取XMLFeedSpider/CSVFeedSpider迭代 XML/RSS 与 CSV 数据源ShopifySpider通过 JSON API 抽取任意 Shopify 商店的全部商品每个 variant 一条数据链接提取独立原语LinkExtractor支持 allow/deny 模式、域名过滤、CSS/XPath 作用域限定、扩展名过滤与 URL 规范化可嵌在模板内也可独立使用scrapling/spiders/links.py内置导出result.items.to_json()、to_jsonl()、to_csv()、to_xml()四合一导出或经由 hook 接自己的管道。代理轮换、广告拦截、封锁应对等专题另有 docs/spiders/proxy-blocking.md 与 docs/api-reference/proxy-rotation.md。五、自适应解析与 AI 集成Adaptive Scraping AI Integration 是首页单列的一节包含四个能力智能元素追踪网站改版后基于相似度算法重新定位元素——即第三节 3.3/3.4 节所述的auto_save/adaptive机制灵活的智能选择CSS、XPath、基于属性过滤的搜索、文本搜索、正则搜索等多种选择方式选择方法大全见 docs/parsing/selection.md相似元素查找find_similar一族方法自动定位与已找到元素相似的元素高级用法测试见 tests/parser/test_find_similar_advanced.py内置 MCP Server面向 AIClaude/Cursor 等的 AI 辅助抓取与数据提取服务。它的特点是先提取、后喂给 AI——利用 Scrapling 在传给模型前就把目标内容抽取出来从而减少 token 消耗、加快操作此外还支持跨多次调用保持浏览器会话、页面截图、经 CDP 驱动远程浏览器。安装方式为pip install scrapling[ai]命令入口scrapling-mcp在 pyproject.toml 的[project.scripts]中注册使用文档见 docs/ai/mcp-server.mdAgent Skill仓库内置可安装的 Agent Skillagent-skill/Scrapling-Skill/SKILL.md把整套库的 API 教给编程 Agent使其生成的 Scrapling 代码符合当前 API 而非凭猜测。该目录还按抓取方式/解析/Spider/集成组织了成体系的参考文档例如 agent-skill/Scrapling-Skill/references/fetching/choosing.md 与 agent-skill/Scrapling-Skill/references/parsing/adaptive.md。六、性能、工程质量与开发者体验首页High-Performance battle-tested Architecture一节的原话承诺包括优化后的高性能、面向最小内存占用的优化数据结构与懒加载、比标准库快 10 倍的 JSON 序列化依赖orjson可在 pyproject.toml 基础依赖中确认、92% 测试覆盖率与全量类型提示。这些属于文档宣称测试规模可由仓库佐证tests/ 下覆盖 parser、fetchers同步/异步/会话、spiders、CLI、AI MCP 等各层模块且 scrapling/py.typed 标记表明整个包带类型信息[tool.mypy]/[tool.pyright]配置pyproject.toml显示每次变更都过 PyRight 与 MyPy 扫描。对 Web 爬虫/开发者的友好特性还包括交互式抓取 Shell基于 IPython 的内置 Shellpip install scrapling[shell]带快捷键与工具如把 curl 命令转换为 Scrapling 请求、在浏览器中查看请求结果docs/cli/interactive-shell.md纯终端抓取可以不写一行代码直接在终端抓 URLdocs/cli/overview.md、docs/cli/extract-commands.md富导航 API父/兄弟/子节点的高级 DOM 遍历增强的文本处理内置正则、清理方法与优化的字符串操作自动生成选择器为任意元素生成稳健的 CSS/XPath 选择器类 Scrapy/BeautifulSoup 的 API沿用 Scrapy/Parsel 的伪元素习惯Scrapy 即插即用集成给 Scrapy 回调加scrapling_response(adaptiveTrue)装饰器即可用 Scrapling 解析器解析 Scrapy 已抓到的响应无需重写集成实现见 scrapling/integrations/scrapy.py指南见 docs/integrations/scrapy.md就绪的 Docker 镜像每次发布自动构建并推送含全部浏览器的镜像。七、文档组织与延伸阅读官方文档遵循 Diátaxis 文档框架组织按教程/操作指南/参考分层。与本文相关的入口导航选择哪个 Fetcherdocs/fetching/choosing.md解析器三大类与选择方式docs/parsing/main_classes.md、docs/parsing/selection.md、docs/parsing/adaptive.mdSpider 入门与架构docs/spiders/getting-started.md、docs/spiders/architecture.md、docs/spiders/sessions.mdCLI 与 Shelldocs/cli/overview.mdMCP Serverdocs/ai/mcp-server.mdAPI 参考docs/api-reference/fetchers、selector、response、proxy-rotation、spiders 等项目元信息BSD-3 许可证LICENSE作者 Karim Shoair当前版本 0.4.13pyproject.toml。小结Scrapling 的价值主张可以浓缩为一条主线——Fetcher/StealthyFetcher/DynamicFetcher负责把页面拿下来含 TLS 指纹、隐身浏览器、代理轮换、XHR 捕获Selector的css(auto_saveTrue)adaptiveTrue负责让选择器活过网站改版Spider则把两者编排成带断点续传、AutoThrottle 与流式输出的工业级爬取。安装上牢记基础包只含解析器、fetcher 依赖需[fetchers]extras 加scrapling install这一分层即可按上文各节路径在当前仓库中深入源码继续学习。【免费下载链接】Scrapling️ An adaptive Web Scraping framework that handles everything from a single request to a full-scale crawl!项目地址: https://gitcode.com/GitHub_Trending/sc/Scrapling创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/5 15:29:36 · 阅读 1.2k Scrapling 完全指南：从单请求抓取到自适应大规模爬虫的 Python 框架
Scrapling 完全指南从单请求抓取到自适应大规模爬虫的 Python 框架【免费下载链接】Scrapling️ An adaptive Web Scraping framework that handles everything from a single request to a full-scale crawl!项目地址: https://gitcode.com/GitHub_Trending/sc/Scrapling本文以 Scrapling 官方文档入口docs/index.md为主体系统梳理这一自适应 Web 抓取框架的三大核心能力——学习型解析器、抗反爬 Fetcher 体系与 Scrapy 风格 Spider 框架并结合仓库源码补充安装分层、adaptive机制的底层实现与调用链帮助读者在 30 分钟内建立起可落地的完整使用路径。一、框架定位一条库覆盖从单请求到全站爬取Scrapling 的官方定位是一个自适应 Web 抓取框架adaptive Web Scraping framework设计目标是让同一套库覆盖从抓一个页面到全站并发爬取的所有规模。文档首页给出的三句话概括了它的核心差异化解析器会学习网站变化当目标页面改版后Scrapling 能自动重新定位你之前保存过的元素而不是让选择器失效Fetcher 开箱即用地绕过反爬内置对 Cloudflare Turnstile / Interstitial 的自动化绕过能力Spider 框架负责规模化支持并发、多会话爬取、断点续传pause/resume与自动代理轮换。官方文档给出的最简示例展示了抓取 → 解析 → 自适应复定位的完整闭环from scrapling.fetchers import Fetcher, StealthyFetcher, DynamicFetcher StealthyFetcher.adaptive True page StealthyFetcher.fetch(https://example.com, headlessTrue, network_idleTrue) # 隐身抓取 products page.css(.product, auto_saveTrue) # 首次抓取时保存元素数据 products page.css(.product, adaptiveTrue) # 网站改版后用 adaptiveTrue 重新找到它们而放大到全站爬取时代码形态与 Scrapy 高度相似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()这个类 Scrapy API的设计贯穿整个 Spider 框架对已有 Scrapy 经验的开发者几乎是零迁移成本。二、安装与环境分层依赖是理解 Scrapling 的第一把钥匙Scrapling 要求Python 3.10 或更高版本pyproject.toml 中requires-python 3.10classifiers 覆盖到 3.13基础安装只包含解析引擎pip install scrapling这里有一个必须注意的分层依赖设计基础安装只装了解析器parser及其依赖不包含任何 fetcher 或命令行依赖。也就是说仅执行pip install scrapling后from scrapling.fetchers import ...或from scrapling.spiders import ...都会抛出ModuleNotFoundError。这一点在源码结构上可以印证scrapling/fetchers/init.py 采用惰性导入__getattr___LAZY_IMPORTS映射只有 fetcher 第三方依赖curl_cffi、playwright 等存在时才能真正加载。基础依赖在 pyproject.toml 中声明为lxml、cssselect、orjson、tld、w3lib、typing_extensions——这解释了为什么纯解析场景下 Scrapling 依然轻量。2.1 按需安装 Fetcher 依赖如果要用Fetcher/StealthyFetcher/DynamicFetcher或任何 Spider需要额外安装 fetcher 依赖并下载浏览器pip install scrapling[fetchers] scrapling install # 常规安装下载浏览器及系统依赖、指纹操纵依赖 scrapling install --force # 强制重新安装也可以不走命令行直接在代码中触发安装from scrapling.cli import install install([], standalone_modeFalse) # 常规安装 install([--force], standalone_modeFalse) # 强制重装从 pyproject.toml 的可选依赖声明看fetchers这一 extras 实际拉取了curl_cffiTLS 指纹伪造、playwrightChromium 自动化、patchright反检测的 Playwright 分支、browserforge与apify-fingerprint-datapoints浏览器指纹生成、protegorobots.txt 解析等——这也解释了为什么浏览器指纹伪造能力需要单独的scrapling install步骤。2.2 其他可选功能与 Docker功能安装命令对应源码入口MCP ServerAI 集成pip install scrapling[ai]命令行入口scrapling-mcp交互式 Shell 与extract命令pip install scrapling[shell]scrapling/core/shell.py全部功能pip install scrapling[all]等价于[ai,shell]免安装镜像docker pull pyd4vinci/scrapling或docker pull ghcr.io/d4vinci/scrapling:latestDockerfileDocker 镜像包含全部 extras 和所有浏览器由 GitHub Actions 基于 main 分支自动构建推送免去本地装浏览器的折腾。三、Fetcher 体系三类抓取器 会话 反爬工具箱3.1 三个 Fetcher 与对应会话类scrapling.fetchers包通过 scrapling/fetchers/init.py 的惰性导入对外暴露 10 个类按抓取方式 × 同步/异步组织能力无状态抓取器有状态会话类底层实现快速隐身 HTTP 请求可伪造浏览器 TLS 指纹、请求头支持 HTTP/3Fetcher/AsyncFetcherFetcherSessionscrapling/fetchers/requests.py完整浏览器自动化Playwright Chromium 与 Google ChromeDynamicFetcherDynamicSession/AsyncDynamicSessionscrapling/fetchers/chrome.py高级隐身指纹欺骗绕过 Cloudflare Turnstile/InterstitialStealthyFetcherStealthySession/AsyncStealthySessionscrapling/fetchers/stealth_chrome.pyProxyRotator也从这个包直接导出可用于所有会话类型。选择哪个 Fetcher 的完整决策指南见 docs/fetching/choosing.md静态、动态、隐身三类分别有 docs/fetching/static.md、docs/fetching/dynamic.md、docs/fetching/stealthy.md 专题文档。3.2 文档首页列出的进阶能力除了三类 Fetcher首页还罗列了一组实用特性均落在scrapling/engines目录的工具带中代理轮换内置ProxyRotator支持循环cyclic或自定义策略跨所有会话类型生效且支持按请求覆盖代理实现见 scrapling/engines/toolbelt/proxy_rotation.py域名与广告拦截可阻断对特定域名含子域的请求或在浏览器型 Fetcher 中启用内置广告拦截约 3,500 个已知广告/追踪域名域表见 scrapling/engines/toolbelt/ad_domains.py;防 DNS 泄漏可选 DNS-over-HTTPS将 DNS 查询路由至 Cloudflare DoH避免使用代理时 DNS 泄漏远程浏览器通过cdp_url用 CDP 连接已运行的浏览器本机、他机或托管浏览器服务均可也可用executable_path指向自建的 Chromium后台 API 捕获给capture_xhr传入 URL 模式页面加载期间所有匹配的 XHR/fetch 响应会作为Response对象收集进response.captured_xhr——无需逆向请求即可拿到网站的 API 数据完整异步支持所有 Fetcher 与对应的异步会话类。3.3adaptive类属性到底做了什么首页示例中StealthyFetcher.adaptive True这行容易被忽视但它正是自适应抓取的总开关。从源码看该属性定义在 Fetcher 基类的配置模型中scrapling/engines/toolbelt/custom.py 中adaptive: Optional[bool] FalseFetcher 将其传递给构造出的 Response只有当它被开启时page.css(selector, auto_saveTrue)才会真正把命中元素的结构指纹持久化保存下来。若未开启css()会明确告警auto_savewill be ignored becauseadaptivewasnt enabled on initialization见 scrapling/parser.py 中xpath方法的守卫逻辑约 L658-L686。3.4css()/xpath()的自适应参数详解scrapling/parser.py 中Selector.css()L566-L624与Selector.xpath()L626 起接受四个与自适应相关的参数这是官方文档 docs/parsing/adaptive.md 的源码级注脚参数默认值作用adaptiveFalse若该选择器此前保存过则尝试在新页面上重新定位元素auto_saveFalse自动保存本次命中的元素供后续adaptive复定位使用identifier保存/检索时使用的标识符不传则用选择器本身。官方建议计划日后更换选择器时务必显式指定percentage40复定位时的最低相似度百分比阈值。注意相似度计算只依赖页面结构非必要时不要随意调低复定位的核心算法在relocate()中scrapling/parser.py L540-L564 附近遍历页面上所有元素逐一与保存的元素数据计算相似度得分即使出现 100% 的匹配也不提前停止因为可能还有其他同分元素最后取最高分档——只有最高分 ≥percentage才返回结果否则发出告警提示可以调低percentage。这解释了为什么auto_save是一次性动作、而adaptiveTrue可以反复使用。此外css()的实现细节值得一提Scrapling 将 CSS 选择器先翻译为 XPath 再交给 lxml 执行_css_to_xpath并且支持::text、::attr()等 Scrapy/Parsel 风格的伪元素这对从 BeautifulSoup/Scrapy 迁移的用户是无缝的迁移指南见 docs/tutorials/migrating_from_beautifulsoup.md。四、Spider 框架Scrapy 式 API 的全功能爬取引擎Spider 框架是 Scrapling 从抓取库升级为爬取框架的关键源码位于 scrapling/spiders/ 目录engine.py、scheduler.py、session.py、checkpoint.py、throttle.py等模块各司其职专题文档从 docs/spiders/getting-started.md 开始架构与请求/响应模型分别在 docs/spiders/architecture.md 和 docs/spiders/requests-responses.md。首页对 Spider 特性的完整清单原文档逐条继承如下每条都值得展开类 Scrapy 的 Spider API用start_urls、异步parse回调、Request/Response对象定义爬虫并发爬取可配置的并发上限、按域限速per-domain throttling与下载延迟限速实现见 scrapling/spiders/throttle.py多会话支持在同一个 Spider 里统一使用 HTTP 请求与隐身无头浏览器按会话 ID 把请求路由到不同会话会话管理见 scrapling/spiders/session.py暂停与续爬基于检查点的爬取持久化——CtrlC优雅退出重启后从上次中断处继续实现见 scrapling/spiders/checkpoint.py流式模式async for item in spider.stream()实时消费抓取项并伴随实时统计适合 UI、数据管道与长时爬取;被封检测自动检测被阻断的请求并重试检测逻辑可自定义AutoThrottleSpider 根据网站响应速度自行调节每个域名的延迟一旦网站开始封禁/限流就加倍延迟或遵循Retry-After压力解除后再提速——不再靠拍脑袋设 delayRobots.txt 合规可选robots_txt_obey标志遵循Disallow、Crawl-delay、Request-rate指令并按域缓存解析器 scrapling/spiders/robotstxt.py开发模式首次运行把响应缓存到磁盘后续运行直接回放——迭代parse()逻辑时不再重复轰炸目标服务器现成 Spider 模板scrapling/spiders/templates/CrawlSpider基于规则的链接跟随SitemapSpider由 sitemap/robots.txt 驱动的爬取XMLFeedSpider/CSVFeedSpider迭代 XML/RSS 与 CSV 数据源ShopifySpider通过 JSON API 抽取任意 Shopify 商店的全部商品每个 variant 一条数据链接提取独立原语LinkExtractor支持 allow/deny 模式、域名过滤、CSS/XPath 作用域限定、扩展名过滤与 URL 规范化可嵌在模板内也可独立使用scrapling/spiders/links.py内置导出result.items.to_json()、to_jsonl()、to_csv()、to_xml()四合一导出或经由 hook 接自己的管道。代理轮换、广告拦截、封锁应对等专题另有 docs/spiders/proxy-blocking.md 与 docs/api-reference/proxy-rotation.md。五、自适应解析与 AI 集成Adaptive Scraping AI Integration 是首页单列的一节包含四个能力智能元素追踪网站改版后基于相似度算法重新定位元素——即第三节 3.3/3.4 节所述的auto_save/adaptive机制灵活的智能选择CSS、XPath、基于属性过滤的搜索、文本搜索、正则搜索等多种选择方式选择方法大全见 docs/parsing/selection.md相似元素查找find_similar一族方法自动定位与已找到元素相似的元素高级用法测试见 tests/parser/test_find_similar_advanced.py内置 MCP Server面向 AIClaude/Cursor 等的 AI 辅助抓取与数据提取服务。它的特点是先提取、后喂给 AI——利用 Scrapling 在传给模型前就把目标内容抽取出来从而减少 token 消耗、加快操作此外还支持跨多次调用保持浏览器会话、页面截图、经 CDP 驱动远程浏览器。安装方式为pip install scrapling[ai]命令入口scrapling-mcp在 pyproject.toml 的[project.scripts]中注册使用文档见 docs/ai/mcp-server.mdAgent Skill仓库内置可安装的 Agent Skillagent-skill/Scrapling-Skill/SKILL.md把整套库的 API 教给编程 Agent使其生成的 Scrapling 代码符合当前 API 而非凭猜测。该目录还按抓取方式/解析/Spider/集成组织了成体系的参考文档例如 agent-skill/Scrapling-Skill/references/fetching/choosing.md 与 agent-skill/Scrapling-Skill/references/parsing/adaptive.md。六、性能、工程质量与开发者体验首页High-Performance battle-tested Architecture一节的原话承诺包括优化后的高性能、面向最小内存占用的优化数据结构与懒加载、比标准库快 10 倍的 JSON 序列化依赖orjson可在 pyproject.toml 基础依赖中确认、92% 测试覆盖率与全量类型提示。这些属于文档宣称测试规模可由仓库佐证tests/ 下覆盖 parser、fetchers同步/异步/会话、spiders、CLI、AI MCP 等各层模块且 scrapling/py.typed 标记表明整个包带类型信息[tool.mypy]/[tool.pyright]配置pyproject.toml显示每次变更都过 PyRight 与 MyPy 扫描。对 Web 爬虫/开发者的友好特性还包括交互式抓取 Shell基于 IPython 的内置 Shellpip install scrapling[shell]带快捷键与工具如把 curl 命令转换为 Scrapling 请求、在浏览器中查看请求结果docs/cli/interactive-shell.md纯终端抓取可以不写一行代码直接在终端抓 URLdocs/cli/overview.md、docs/cli/extract-commands.md富导航 API父/兄弟/子节点的高级 DOM 遍历增强的文本处理内置正则、清理方法与优化的字符串操作自动生成选择器为任意元素生成稳健的 CSS/XPath 选择器类 Scrapy/BeautifulSoup 的 API沿用 Scrapy/Parsel 的伪元素习惯Scrapy 即插即用集成给 Scrapy 回调加scrapling_response(adaptiveTrue)装饰器即可用 Scrapling 解析器解析 Scrapy 已抓到的响应无需重写集成实现见 scrapling/integrations/scrapy.py指南见 docs/integrations/scrapy.md就绪的 Docker 镜像每次发布自动构建并推送含全部浏览器的镜像。七、文档组织与延伸阅读官方文档遵循 Diátaxis 文档框架组织按教程/操作指南/参考分层。与本文相关的入口导航选择哪个 Fetcherdocs/fetching/choosing.md解析器三大类与选择方式docs/parsing/main_classes.md、docs/parsing/selection.md、docs/parsing/adaptive.mdSpider 入门与架构docs/spiders/getting-started.md、docs/spiders/architecture.md、docs/spiders/sessions.mdCLI 与 Shelldocs/cli/overview.mdMCP Serverdocs/ai/mcp-server.mdAPI 参考docs/api-reference/fetchers、selector、response、proxy-rotation、spiders 等项目元信息BSD-3 许可证LICENSE作者 Karim Shoair当前版本 0.4.13pyproject.toml。小结Scrapling 的价值主张可以浓缩为一条主线——Fetcher/StealthyFetcher/DynamicFetcher负责把页面拿下来含 TLS 指纹、隐身浏览器、代理轮换、XHR 捕获Selector的css(auto_saveTrue)adaptiveTrue负责让选择器活过网站改版Spider则把两者编排成带断点续传、AutoThrottle 与流式输出的工业级爬取。安装上牢记基础包只含解析器、fetcher 依赖需[fetchers]extras 加scrapling install这一分层即可按上文各节路径在当前仓库中深入源码继续学习。【免费下载链接】Scrapling️ An adaptive Web Scraping framework that handles everything from a single request to a full-scale crawl!项目地址: https://gitcode.com/GitHub_Trending/sc/Scrapling创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考