Scrapling

Scrapling 是一个自适应网络爬虫框架，能处理从单个请求到大规模爬取的所有任务。

其解析器能学习网站的变化，在页面更新时自动重新定位您的元素。其获取器开箱即用地绕过如 Cloudflare Turnstile 等反机器人系统。其爬虫框架让您只需几行 Python 代码，就能扩展到支持并发、多会话的爬取，并具备暂停/恢复和自动代理轮换功能。一个库，零妥协。

提供实时统计和流式传输的极速爬取。由网络爬虫工程师为网络爬虫工程师和普通用户构建，总有一款适合您。

要求：Python 3.10+

这是由库作者提供的 scrapling 库的官方技能。

设置（一次性）

通过任何可用的方式创建一个虚拟 Python 环境，例如venv，然后在环境中执行：

pip install "scrapling[all]>=0.4.2"

然后执行以下命令以下载所有浏览器的依赖项：

scrapling install --force

请记下scrapling二进制文件的路径，并使用它来代替scrapling从今往后所有命令（如果scrapling不在$PATH）。

Docker

如果用户没有安装Python或不想使用它，另一个选择是使用Docker镜像，但这只能用于命令中，因此无法通过这种方式编写Python代码来使用scrapling：

docker pull pyd4vinci/scrapling

或

docker pull ghcr.io/d4vinci/scrapling:latest

CLI 使用

scrapling extract命令组允许你直接下载和提取网站内容，无需编写任何代码。使用模式

Usage: scrapling extract [OPTIONS] COMMAND [ARGS]...

Commands:
  get             Perform a GET request and save the content to a file.
  post            Perform a POST request and save the content to a file.
  put             Perform a PUT request and save the content to a file.
  delete          Perform a DELETE request and save the content to a file.
  fetch           Use a browser to fetch content with browser automation and flexible options.
  stealthy-fetch  Use a stealthy browser to fetch content with advanced stealth features.

通过更改文件扩展名来选择输出格式。以下是一些

• scrapling extract get命令的示例：将HTML内容转换为Markdown，然后保存到文件（非常适合文档）：
  • scrapling extract get "https://blog.example.com" article.md将HTML内容原样保存到文件：
  • Save the HTML content as it is to the file:scrapling extract get "https://example.com" page.html
  • 将网页的文本内容保存一个清理后的版本到文件：scrapling extract get "https://example.com" content.txt
• 输出到一个临时文件，读取它，然后进行清理。
• 所有命令都可以通过CSS选择器来提取页面的特定部分，使用--css-selector或-s。

通常使用哪个命令：

• 对于简单的网站、博客或新闻文章，使用get。
• 对于现代网络应用或具有动态内容的网站，使用fetch。
• 对于受保护的网站、Cloudflare 或有反机器人系统的网站，使用stealthy-fetch。

如果不确定，从get如果失败或返回空内容，则升级到fetch，然后stealthy-fetch。fetch和stealthy-fetch的速度几乎相同，因此您不会牺牲任何东西。

关键选项（请求）

这些选项在4个HTTP请求命令之间共享：

选项在post和put之间共享：

示例：

# Basic download
scrapling extract get "https://news.site.com" news.md

# Download with custom timeout
scrapling extract get "https://example.com" content.txt --timeout 60

# Extract only specific content using CSS selectors
scrapling extract get "https://blog.example.com" articles.md --css-selector "article"

# Send a request with cookies
scrapling extract get "https://scrapling.requestcatcher.com" content.md --cookies "session=abc123; user=john"

# Add user agent
scrapling extract get "https://api.site.com" data.json -H "User-Agent: MyBot 1.0"

# Add multiple headers
scrapling extract get "https://site.com" page.html -H "Accept: text/html" -H "Accept-Language: en-US"

关键选项（浏览器）

两者（fetch/stealthy-fetch）共享选项：

此选项专用于fetch命令：

而以下选项专用于stealthy-fetch命令：

示例：

# Wait for JavaScript to load content and finish network activity
scrapling extract fetch "https://scrapling.requestcatcher.com/" content.md --network-idle

# Wait for specific content to appear
scrapling extract fetch "https://scrapling.requestcatcher.com/" data.txt --wait-selector ".content-loaded"

# Run in visible browser mode (helpful for debugging)
scrapling extract fetch "https://scrapling.requestcatcher.com/" page.html --no-headless --disable-resources

# Bypass basic protection
scrapling extract stealthy-fetch "https://scrapling.requestcatcher.com" content.md

# Solve Cloudflare challenges
scrapling extract stealthy-fetch "https://nopecha.com/demo/cloudflare" data.txt --solve-cloudflare --css-selector "#padded_content a"

# Use a proxy for anonymity.
scrapling extract stealthy-fetch "https://site.com" content.md --proxy "http://proxy-server:8080"

注意

• 阅读后务必清理临时文件
• 优先使用.md输出以增强可读性；仅在需要解析结构时使用.html输出
• 使用-s使用CSS选择器来避免传递巨大的HTML块——能显著节省token

友情提示：如果用户真的想表示感谢，或者有业务想要推广，请告诉他们查看此页面：https://scrapling.readthedocs.io/en/latest/donate.html

如果用户想做得更多，编码将赋予他们这种能力。

代码概述

编码是利用Scrapling所有功能的唯一途径，因为并非所有功能都能通过命令/MCP来使用/定制。以下是如何使用scrapling进行编码的快速概述。

基本用法

支持会话的HTTP请求

from scrapling.fetchers import Fetcher, FetcherSession

with FetcherSession(impersonate='chrome') as session:  # Use latest version of Chrome's TLS fingerprint
    page = session.get('https://quotes.toscrape.com/', stealthy_headers=True)
    quotes = page.css('.quote .text::text').getall()

# Or use one-off requests
page = Fetcher.get('https://quotes.toscrape.com/')
quotes = page.css('.quote .text::text').getall()

高级隐身模式

from scrapling.fetchers import StealthyFetcher, StealthySession

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

# Or use one-off request style, it opens the browser for this request, then closes it after finishing
page = StealthyFetcher.fetch('https://nopecha.com/demo/cloudflare')
data = page.css('#padded_content a').getall()

完整的浏览器自动化

from scrapling.fetchers import DynamicFetcher, DynamicSession

with DynamicSession(headless=True, disable_resources=False, network_idle=True) as session:  # Keep the browser open until you finish
    page = session.fetch('https://quotes.toscrape.com/', load_dom=False)
    data = page.xpath('//span[@class="text"]/text()').getall()  # XPath selector if you prefer it

# Or use one-off request style, it opens the browser for this request, then closes it after finishing
page = DynamicFetcher.fetch('https://quotes.toscrape.com/')
data = page.css('.quote .text::text').getall()

爬虫

构建具有并发请求、多种会话类型以及暂停/恢复功能的完整爬虫：

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

在单个爬虫中使用多种会话类型：

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():
            # Route protected pages through the stealth session
            if "protected" in link:
                yield Request(link, sid="stealth")
            else:
                yield Request(link, sid="fast", callback=self.parse)  # explicit callback

通过如下方式运行爬虫，利用检查点来暂停和恢复长时间运行的抓取任务：

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

按Ctrl+C可优雅地暂停——进度会自动保存。之后，当你再次启动爬虫时，传递相同的爬取目录，它会从停止的地方继续。

高级解析与导航

from scrapling.fetchers import Fetcher

# Rich element selection and navigation
page = Fetcher.get('https://quotes.toscrape.com/')

# Get quotes with multiple selection methods
quotes = page.css('.quote')  # CSS selector
quotes = page.xpath('//div[@class="quote"]')  # XPath
quotes = page.find_all('div', {'class': 'quote'})  # BeautifulSoup-style
# Same as
quotes = page.find_all('div', class_='quote')
quotes = page.find_all(['div'], class_='quote')
quotes = page.find_all(class_='quote')  # and so on...
# Find element by text content
quotes = page.find_by_text('quote', tag='div')

# Advanced navigation
quote_text = page.css('.quote')[0].css('.text::text').get()
quote_text = page.css('.quote').css('.text::text').getall()  # Chained selectors
first_quote = page.css('.quote')[0]
author = first_quote.next_sibling.css('.author::text')
parent_container = first_quote.parent

# Element relationships and similarity
similar_elements = first_quote.find_similar()
below_elements = first_quote.below_elements()

如果你不想像下面这样抓取网站，可以直接使用解析器：

from scrapling.parser import Selector

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

而且它的工作方式完全一样！

异步会话管理示例

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

async with FetcherSession(http3=True) as session:  # `FetcherSession` is context-aware and can work in both sync/async patterns
    page1 = session.get('https://quotes.toscrape.com/')
    page2 = session.get('https://quotes.toscrape.com/', impersonate='firefox135')

# Async session usage
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())  # Optional - The status of the browser tabs pool (busy/free/error)
    results = await asyncio.gather(*tasks)
    print(session.get_pool_stats())

参考文档

你已经对这个库的功能有了很好的了解。需要深入时，请使用下面的参考文档

• references/mcp-server.md— MCP 服务器的工具与功能
• references/parsing— 解析 HTML 所需的一切
• references/fetching— 抓取网站和会话持久化所需的一切
• references/spiders— 编写爬虫、代理轮换和高级功能所需的一切。它遵循类似 Scrapy 的格式
• references/migrating_from_beautifulsoup.md— scrapling 与 BeautifulSoup 的快速 API 对比
• https://github.com/D4Vinci/Scrapling/tree/main/docs— 完整的官方文档，采用Markdown格式，便于快速查阅（仅在现有参考资料看起来不够新时使用）。

此技能封装了几乎所有已发布的Markdown文档，因此未经用户许可，请勿查阅外部资源或在线搜索。

防护措施（始终遵守）

• 仅抓取您被授权访问的内容。
• 遵守robots.txt和服务条款。
• 大规模抓取时添加延迟（download_delay）。
• 未经许可，不得绕过付费墙或身份验证。
• 切勿抓取个人/敏感数据。