如何使用 Scrapling 和 Scrapeless 在 Python 中构建生产级网络爬虫

Ava Wilson

Expert in Web Scraping Technologies

25-May-2026

主要要点:

Scrapling 提供三种获取器和自适应选择器。 HTTP Fetcher（带浏览器 TLS 伪装）、Playwright 支持的 DynamicFetcher 和 StealthyFetcher 覆盖了静态页面、JavaScript 渲染页面和中等反机器人措施，整合在一个 Python 库中——而自适应选择器通过结构而非脆弱的 CSS 路径来定位元素。
升级流程是 HTTP → 隐身 → 云浏览器。 从最便宜的有效获取器开始；当本地隐身影响 IP 声誉、先进的机器人管理器或地理限制内容时，您可以无缝升级到云浏览器，而无需重写解析代码。
集成只需一行。 将 Scrapling 的 Playwright 获取器指向 Scrapeless 会话的 CDP —— DynamicFetcher.fetch(url, cdp_url=session.browser_ws_endpoint) —— 渲染、代理出口和指纹识别都在云端进行。
Scrapeless 处理出口和指纹。 Scrapeless 爬虫浏览器通过 195 个国家的住宅代理进行路由，并在每个会话中随机化浏览器指纹，因此云浏览器渲染出本地隐身浏览器被过滤的页面。
自适应选择器能应对 DOM 漂移。 Scrapling 可以在布局更改后通过匹配其先前的属性和位置重新定位元素，因此当目标网站旋转其标记时，爬虫仍然可以继续返回行数据。
免费开始。 新的 Scrapeless 帐户包括免费的爬虫浏览器运行时——可在 Scrapeless 注册。

引言：当本地隐身走到尽头

动态、重 JavaScript 的、保护良好的反机器人页面是简单的 HTTP 爬虫静静失败的地方。一个 requests + BeautifulSoup 脚本返回 HTTP 200 和一个空结果集：它解析的标记从未包含数据，因为价格、列表或评论是在初始响应后由 JavaScript 注入的。页面在浏览器中看起来正常，但在您的爬虫中显得为空。

Scrapling 提升了底线。它是一个快速的 Python 爬虫库，提供三种获取器——一个模拟真实浏览器 TLS 握手的 HTTP Fetcher，一个支持 JavaScript 渲染的 Playwright DynamicFetcher，以及一个增加隐身补丁和 Cloudflare 处理的 StealthyFetcher——同时还有能够应对 DOM 变化的自适应选择器。这涵盖了静态页面和相当数量的中等反机器人。但在您的笔记本电脑上运行的浏览器仍然携带着知名声誉的数据中心或家庭 IP，因此无论页面级的隐身多么干净，先进的机器人管理器仍会指纹识别自动化。此时，页面为人类渲染并接受挑战。

本教程建立了一个由两个层级构成的 Python 流水线。第一层是单独的 Scrapling——这是处理静态和中度保护页面的合适工具。第二层通过 CDP 将 Scrapling 的 DynamicFetcher 路由到 Scrapeless 爬虫浏览器，从而在住宅代理和每个会话的反检测指纹识别之后，在云端进行渲染，同时您的 Scrapling 解析代码保持不变。有关通过代理框架而非获取器驱动的相同 Scrapeless 爬虫浏览器原语，请参见 LangChain 集成帖子。

您可以构建的内容

这种两层模式——前置 Scrapling 获取器，后置 Scrapeless 爬虫浏览器——涵盖了大多数突破普通 HTTP 爬虫的任务：

单页应用商店的价格和库存监测。 渲染在第二个 XHR 中通过的价格被填充的单页应用产品页面，然后提取 Scrapling 从渲染的 DOM 中解析出的数字。
SERP 邻近的提取。 从作为 JavaScript 提交的搜索风格结果页面中提取自然结果块和片段，然后用自适应选择器翻页。
JavaScript 目录中的潜在客户列表。 浏览客户端渲染行的商业列出和会员目录网站，将联系字段收集到带类型的记录中。
通过住宅出口的地理特定快照。 捕捉本地用户所看到的列表、价格或可用性，通过固定 Scrapeless 代理国家，而不是您办公室 IP 解析的内容。
渲染页面的 RAG 摄取。 渲染发布者和文档页面以清理嵌入管道的内容，从而使检索层索引页面实际显示的内容，而不是空壳。
能够应对布局变化的强韧爬虫。 倚靠 Scrapling 的自适应选择器，使计划的爬虫在目标网站重新排列其 DOM 后仍能不断返回行数据，而不是在下一次运行中悄然失败。
面对先进反机器人的硬目标提取。 当网站前置一个本地隐身无法清理的高级机器人管理器时，将相同的 Scrapling 代码提升到 Scrapeless 爬虫浏览器。
在Scrapeless，我们只访问公开可用的数据，并严格遵守适用的法律、法规以及网站隐私政策。本帖子中的内容仅用于演示目的。

为什么将Scrapling与Scrapeless配对

Scrapling负责解析、抓取器的人机工程学和自适应选择器；而Scrapeless抓取浏览器负责本地浏览器无法实现的规避流程。这两者能有效结合，因为交接点是一个单一的CDP端点。

反检测云浏览器。 Scrapeless抓取浏览器运行自开发的Chromium，并进行全云端JavaScript渲染，因此单页应用、无限滚动的动态内容和懒加载面板在Scrapling解析之前就能加载完成。
覆盖195多个国家的住宅代理。 在创建会话时设置proxy_country，云浏览器将从您目标区域的真实住宅IP出口，这样地域限制页面返回的是本地用户所见的内容。
每个会话的指纹随机化。 每个会话都有一个随机的指纹——用户代理、时区、WebGL和画布——因此重复运行不会合并为单一可检测的身份。
cdp_url即插即用。 将Scrapeless会话端点作为cdp_url传递给DynamicFetcher.fetch(...)，Scrapling的API中没有其他变化——选择器、结果对象和解析代码都相同。
通过session_ttl保持会话持久。 通过在创建时设置session_ttl在多个页面加载中保持会话打开，因此温暖的cookies和导航状态在单次运行中的请求之间持续有效。

运行时免费起步，并根据使用情况进行扩展—请查看Scrapeless定价以了解不同级别，并在Scrapeless的免费计划中获取您的API密钥。

Scrapling与requests、BeautifulSoup和Scrapy的比较

如果您当前的技术栈是requests + BeautifulSoup或Scrapy，以下是Scrapling适合的位置，以及Scrapeless云浏览器置于其后时的变化。

工具	渲染JavaScript	反机器人/隐匿	选择器韧性	最佳用途
`requests` + BeautifulSoup	否	无（原始HTTP）	手动；在重新设计时失效	小型静态页面和JSON API
Scrapy	仅通过附加组件（例如Playwright集成）	没有内置	手动；在重新设计时失效	大型异步爬虫，您可以自行构建和托管
Scrapling — `Fetcher`	否	浏览器-TLS伪装	可用的自适应选择器	快速静态抓取，使用指纹感知的HTTP
Scrapling — `DynamicFetcher` / `StealthyFetcher`	是（本地浏览器）	隐匿补丁、Cloudflare处理	自适应选择器	JS页面和中等反机器人，运行在您的机器上
Scrapling + Scrapeless（`cdp_url`）	是（云浏览器）	覆盖195多个国家的住宅代理 + 每个会话的指纹随机化	自适应选择器	大规模的重JS、地域绑定或强反机器人页面

这一过程是累加的。保持requests/BeautifulSoup在已有效的地方使用，当页面需要浏览器或指纹感知的HTTP时，再使用Scrapling的抓取器，并在本地渲染被过滤时，通过cdp_url将Scrapling路由到Scrapeless抓取浏览器。解析代码——page.css(...)，page.xpath(...)——在三者中保持一致。

先决条件

在开始之前，请确保您拥有：

Python 3.10+ — Scrapling 0.4.8需要此版本。
pip — 用于安装以下包。
Scrapeless账号和API密钥 — 在Scrapeless网站注册免费计划，然后从设置 → API密钥管理中获取密钥。
对CSS/XPath选择器和终端的基本了解 — 您将使用这两者来抓取页面并提取值。

安装

您只需要两个包：Scrapling用于抓取和解析，以及官方的Scrapeless SDK用于创建云浏览器会话。

1. 安装Scrapling和Scrapeless SDK

bash Copy

pip install "scrapling[fetchers]" scrapeless
scrapling install   # 抓取本地浏览器以供DynamicFetcher / StealthyFetcher使用（如果您仅通过cdp_url使用远程Scrapeless云浏览器，请跳过此步骤）

scrapling[fetchers]提供抓取和解析层（Fetcher、DynamicFetcher和StealthyFetcher类以及类似parsel的选择器API），而scrapeless是官方SDK，用于创建Scrapeless抓取浏览器会话，并为您提供一个CDP端点以进行连接。

2. 设置您的Scrapeless API密钥

导出您的密钥，以便SDK可以读取：

bash Copy

export SCRAPELESS_API_KEY=your_api_token_here

在Windows上，使用 setx SCRAPELESS_API_KEY "your_api_token_here" （持久化，新shell）或 $env:SCRAPELESS_API_KEY="your_api_token_here" （当前PowerShell会话）。Scrapeless SDK会自动读取此变量——您无需在代码中传递密钥。

3. 测试安装

通过导入三个提取器并从静态页面中提取一些值来确认环境：

python Copy

from scrapling.fetchers import Fetcher, DynamicFetcher, StealthyFetcher

page = Fetcher.get("https://quotes.toscrape.com/")
print(page.status, len(page.css("span.text::text")), "quotes")  # -> 200 10 quotes

如果您看到 200 10 quotes，则表示Scrapling已成功安装并正确解析，您可以开始连接Scrapeless抓取浏览器。

第一步 — 三个Scrapling提取器

Scrapling提供了三个提取器，这些提取器权衡了速度和规避。经验法则是选择返回所需数据的最轻便的提取器，然后仅在请求被阻止或返回为空时升级：对于普通HTTP，首先使用Fetcher，当页面需要JavaScript进行渲染时使用DynamicFetcher，在反机器人层阻碍时使用StealthyFetcher。

提取器	引擎	使用场景
`Fetcher`	通过 `curl_cffi` 的HTTP（浏览器-TLS伪装）	静态页面和JSON API — 不需要JavaScript
`DynamicFetcher`	Playwright	JS渲染页面、单页应用、懒加载内容
`StealthyFetcher`	Stealth Playwright	反机器人防御，例如Cloudflare中断页面

这三者都从同一模块导入，并返回类似parsel的响应，因此选择器API（.css(...)，.xpath(...)）无论是哪个提取器产生页面都是相同的。

python Copy

from scrapling.fetchers import Fetcher

# 使用浏览器-TLS伪装进行HTTP提取；返回类似parsel的响应。
page = Fetcher.get("https://books.toscrape.com/", impersonate="chrome", stealthy_headers=True)
title = page.css("article.product_pod h3 a::attr(title)")  # -> 第一书籍标题

python Copy

from scrapling.fetchers import DynamicFetcher

# Playwright渲染JS，然后将补充页面作为类似parsel的响应返回。
# 需要本地浏览器（运行 `scrapling install`）或通过cdp_url访问的远程浏览器（下一步）。
page = DynamicFetcher.fetch("https://quotes.toscrape.com/js/", network_idle=True)
quotes = page.css("span.text::text")  # -> JS渲染的引用，现在可见

python Copy

from scrapling.fetchers import StealthyFetcher

# Stealth Playwright尝试反机器人握手，然后返回页面。
page = StealthyFetcher.fetch("https://example.com/protected-page",
                             solve_cloudflare=True, block_webrtc=True, hide_canvas=True)
content = page.css("main ::text")  # -> 挑战解除后的页面文本

第二步 — 添加代理（本地隐蔽停止的地方）

干净的数据中心IP是机器人管理器标记的第一件事。通过住宅代理路由请求可以减少这些IP声誉阻止，因为出口地址看起来像普通家庭连接。每个Scrapling提取器都接受通过相同的proxy=参数传递的代理，因此您可以在不更改其余代码的情况下添加代理。

python Copy

from scrapling.fetchers import Fetcher, StealthyFetcher

# 通过proxy=向任何提取器传递代理字符串。
page = Fetcher.get("https://books.toscrape.com/",
                   proxy="http://<user>:<pass>@<host>:<port>")

# StealthyFetcher在处理反机器人挑战时接受相同的参数。
page = StealthyFetcher.fetch("https://example.com/protected-page",
                            proxy="http://<user>:<pass>@<host>:<port>",
                            solve_cloudflare=True)

这就是Scrapeless与代理故事的结合之处。Scrapeless在195个国家提供住宅代理，您可以有两种方式将它们放在Scrapling之前。最简单的路径是在云浏览器会话级别应用它们：当您将DynamicFetcher连接到Scrapeless抓取浏览器会话时，您只需通过proxy_country固定出口，而根本不接触代理字符串。Scrapeless还提供一个独立的代理产品，其网关凭据直接放入Scrapling的proxy=参数中——请参阅Scrapeless代理解决方案以了解产品，并查看docs.scrapeless.com以获取要替换<user>:<pass>@<host>:<port>占位符的确切网关字符串。

好的代理解决了IP声誉问题，但并不能解决所有问题。无论出口IP有多干净，本地隐蔽浏览器仍会被高级机器人管理器过滤，并在重型客户端JavaScript上停滞。这正是Scrapeless云浏览器接管的地方——将在下一步中介绍。

第三步 — 通过Scrapeless云浏览器路由Scrapling（cdp_url）

当本地隐形运行耗尽时——重度客户端渲染、先进的机器人管理器，或仅能从特定国家解析的页面——使用 SDK 创建一个无刮痕会话，并将其 CDP 端点交给 Scrapling。SDK 创建会话；Scrapling 驱动它。住宅代理（proxy_country）和浏览器指纹识别由 Scrapeless 抓取浏览器在云端处理，因此您的 Scrapling 代码保持不变，只需添加一个额外参数：cdp_url。

python Copy

from scrapeless import Scrapeless
from scrapeless.types import ICreateBrowser
from scrapling.fetchers import DynamicFetcher

client = Scrapeless()  # 读取 SCRAPELESS_API_KEY
session = client.browser.create(ICreateBrowser(proxy_country="US", session_ttl=240))

page = DynamicFetcher.fetch(
    "https://quotes.toscrape.com/js/",
    cdp_url=session.browser_ws_endpoint,
    network_idle=True,
)

quotes = page.css("span.text::text")
authors = page.css("small.author::text")

session.browser_ws_endpoint 是一个 WebSocket CDP URL，格式为 wss://browser.scrapeless.com/browser?token=...&proxy...——Scrapling 连接到它的方式与连接本地浏览器完全相同。前后对比是重点：对 https://quotes.toscrape.com/js/ 的简单 Fetcher.get 返回 0 个报价，因为 HTTP 无法执行页面的 JavaScript，而通过 Scrapeless cdp_url 获取的同一页面渲染 10 个报价（以及他们的作者）。这是平台行为，而不是调优技巧——云浏览器运行 JavaScript，然后 Scrapling 解析生成的 DOM。

StealthyFetcher.fetch(...) 在您希望 Scrapling 的隐形层在云浏览器之上时，接受相同模式的 cdp_url。

第 4 步 — 能够适应 DOM 漂移的自适应选择器

选择器是任何抓取器中最脆弱的部分：重新设计重命名了类或移动了元素，每个 css(...) 调用默默返回无效输出。Scrapling 的自适应模式对此进行了一定程度的防范。在获取时传递 adaptive=True（可选 adaptive_domain=...），Scrapling 会存储您选择的每个元素的指纹。当 DOM 发生变化时，它通过相似性重新定位保存的元素，而不是通过精确路径，因此您的选择器在布局变化中仍然有效。

python Copy

from scrapling.fetchers import DynamicFetcher

# 首次运行：正常选择；Scrapling 记住每个元素的外观。
page = DynamicFetcher.fetch(
    "https://quotes.toscrape.com/js/",
    cdp_url=session.browser_ws_endpoint,
    network_idle=True,
    adaptive=True,
    adaptive_domain="quotes.toscrape.com",
)
quotes = page.css("span.text::text")

# 之后，网站重新排列其标记：使用相同的调用重新选择。
# 即使 "span.text" 不再匹配，自适应模式也会重新定位保存的元素。
page = DynamicFetcher.fetch(
    "https://quotes.toscrape.com/js/",
    cdp_url=session.browser_ws_endpoint,
    network_idle=True,
    adaptive=True,
    adaptive_domain="quotes.toscrape.com",
)
quotes = page.css("span.text::text")

在您反复抓取的页面上，以及频繁进行外观更改的页面上使用自适应选择器——它能吸收小的 DOM 变化，因此您只需在真正的重新设计后重新访问选择器。

第 5 步 — 在一个云会话中爬取多个页面

大多数真实任务涉及多个 URL——分页列表、搜索结果、类别树。每个页面创建一个新的云浏览器会丢失温暖的会话并且每次都要重新进行连接握手。Scrapling 的 DynamicSession 保持与 Scrapeless 云浏览器的单一连接打开，并通过它获取每个页面，因此 cookies、住宅身份和导航状态会在整个爬取过程中持续有效。

python Copy

from scrapeless import Scrapeless
from scrapeless.types import ICreateBrowser
from scrapling.fetchers import DynamicSession

client = Scrapeless()
session = client.browser.create(ICreateBrowser(proxy_country="US", session_ttl=300))

rows = []
with DynamicSession(cdp_url=session.browser_ws_endpoint) as crawler:
    for n in range(1, 4):  # 页码 1..3
        url = "https://quotes.toscrape.com/js/" if n == 1 else f"https://quotes.toscrape.com/js/page/{n}/"
        page = crawler.fetch(url, network_idle=True)
        quotes = page.css("span.text::text")
        authors = page.css("small.author::text")
        rows += [{"quote": str(q), "author": str(a)} for q, a in zip(quotes, authors)]

print(len(rows), "rows")  # 每页积累十个报价行

每个页面产生十个报价行，整个过程通过一个重用的云浏览器会话积累到 rows 中。network_idle=True 等待每个页面在提取前完全加载；将短页面或空页面视为重试信号，而不是列表结束的标志。对于列表到详细的爬取，首先抓取列表，使用 page.css("a::attr(href)") 收集详细 URL，然后通过相同的 crawler 获取每个页面——住宅会话和指纹在整个爬取过程中保持不变。

第 6 步 — 生产级加固

从工作脚本转变为可依赖的作业主要涉及回压和恢复。一些规则承载了大部分的重量：

限制并发。 每个主机保持 ≤3 个云浏览器会话。超过这个数量会导致速率限制和连接重置，而额外的失败往往不值得其边际吞吐量。
以回退机制重试瞬态连接错误。 隧道和超时错误，例如 ERR_TUNNEL_CONNECTION_FAILED，本质上是瞬态的。捕获它们，进行指数回退后重试——不要把一次连接失败当作死页。
使用 ProxyRotator 轮换出站代理。 Scrapling 的 ProxyRotator 在请求间轮换代理，这样你就不会从一个IP猛击目标；将其与 Scrapeless 住宅代理结合使用，完成地理限界的工作。
在多个步骤中复用会话。 利用 session_ttl（例如240秒）一次性创建，并在多步骤流程中传递相同的 browser_ws_endpoint——登录、导航、提取——而不是为每个请求支付启动一个新的浏览器的费用。
将缺失字段视为空值。 实际页面在某些行中省略评分、作者或价格。默认缺失选择器为 None，而不是断言它们存在，以免一个稀疏记录导致运行崩溃。

在 免费计划 上获取您的 API 密钥： Scrapeless

您将得到的回复

json Copy

[
  {
    "quote": "我们所创造的世界是我们思维的过程。没有改变我们的思维，就无法改变它。",
    "author": "阿尔伯特·爱因斯坦"
  },
  {
    "quote": "是我们的选择，哈利，展示了我们真正的自我，远比我们的能力更为重要。",
    "author": "J.K.罗琳"
  },
  {
    "quote": "生活只有两种方式。其一是仿佛没有任何事情是奇迹；其二是仿佛一切都是奇迹。",
    "author": "阿尔伯特·爱因斯坦"
  }
]
// 形状反映了第3步的提取；值是示例样本。

从运行此管道中得到的一些诚实观察：

JS 渲染页面需要云浏览器。 对 https://quotes.toscrape.com/js/ 进行普通 HTTP 获取返回 0 行；只有通过 cdp_url 到达的云浏览器才能执行 JavaScript，从而让 Scrapling 可以解析它。
network_idle=True 等待内容加载。 它会保持直到网络稳定，这在那些在第一次绘制后获取内容的页面上很重要。
自适应选择器减少故障，而非验证。 它们吸收轻微的 DOM 变化，但在重大重新设计后，仍应重新运行选择器发现并确认输出。
为地理绑定页面固定 proxy_country。 价格、可用性和同意墙因地区而异；设置 proxy_country 可确保结果与您所针对的本地情况一致。
静态页面不需要这些。 如果 Fetcher.get 已经返回数据，就直接使用——仅当 HTTP 返回为空或被阻塞时，才升级到云浏览器。
瞬态隧道和 5xx 错误可重试。 一次性的 ERR_TUNNEL_CONNECTION_FAILED 或 500 通常是网络噪音，而不是您代码中的错误——进行回退重试。

结论：最轻的获取器优先，阻塞时使用云浏览器

该管道简化为三步。选择最轻的获取器——静态 HTML 的 Fetcher.get。当页面返回为空、被阻塞或地理限制时，通过将 session.browser_ws_endpoint 传递给 Scrapling 的 cdp_url 升级到 Scrapeless Scraping Browser。然后使用自适应选择器解析，以确保提取能够适应下一个布局更改。只有在您真正需要时，才为云浏览器付费——请参见 Scrapeless 定价了解免费层所覆盖的内容——其余代码保持为普通 Scrapling。

在此之后，相同的 cdp_url 模式可以插入更大的系统。有关将云渲染接入代理的更多信息，请查看 LangChain + Scrapeless 指南，以及 Etsy 报价单 walkthrough 了解完整站点构建。在您发布之前：导出 SCRAPELESS_API_KEY，为任何地理绑定页面固定 proxy_country，将并发保持在每个主机 ≤3 个会话，并将缺失字段视为空值。

常见问题

网站抓取是否合法？

抓取公开可用的数据在许多法域中通常是允许的，但法律并不统一。审查每个网站的服务条款，避免收集您没有权利获取的个人或受版权保护的数据，并记住规则因法域而异。如有疑问，请为您的具体用例寻求法律建议。

需要代理吗？

为了规模化的任何事情，是的。住宅出口相比数据中心IP大幅削减了区块，并且对于根据地区限制内容的页面是必需的。Scrapeless在195多个国家提供住宅代理——在您生成会话时设置proxy_country，或者通过代理网关路由——这样您就不必自己获取和轮换IP。

何时需要云浏览器而不是本地Scrapling？

当Fetcher.get返回数据时，请保持本地——这是最快的路径。当页面依赖于客户端JavaScript，且由高级机器人管理器控制，或受地理限制时，请通过cdp_url升级到Scrapeless云浏览器。云浏览器运行JavaScript并执行反检测和住宅出口，而本地获取无法匹敌。

为什么您一直看到`ERR_TUNNEL_CONNECTION_FAILED`或5xx错误？

重试。这些是暂时的连接错误，而不是您脚本中的错误。将获取操作包装在一个具有指数退避和合理上限的重试循环中；大多数情况下，第二或第三次尝试后可以解决。

站点重新设计后，我的选择器坏了。如何修复？

开启自适应选择器（adaptive=True与adaptive_domain=...），让Scrapling通过轻微的DOM变化重新定位保存的元素。在大规模重新设计后，重新运行选择器发现以确认新的标记，然后让自适应模式再次保持稳定。

有需要遵守的并发限制吗？

每个主机保持≤3个云浏览器会话。超出此范围，您将牺牲一些吞吐量，换取大量的速率限制和连接重置。使用有界并发和队列，而不是一次性发出每个请求。

Scrapling自带自己的MCP（`pip install "scrapling[ai]"`）——这与此有何关系？

您可以将两者结合使用。Scrapling的MCP让AI代理对本地库进行直接控制；Scrapeless的MCP服务器为该代理提供云渲染以及反检测和住宅代理。可以一起使用它们，或选择适合您堆栈的一个。此指南采用了库路径——Scrapling通过cdp_url驱动Scrapeless云浏览器——这使得集成保持为一个参数，无需额外的服务器来运行。