scrapling

Scrapling -- 本地隐蔽式网页抓取

100% 本地运行的 Python 库（BSD-3，D4Vinci/Scrapling）。无需 API 密钥，也不依赖云服务。内置 Cloudflare 解决器、TLS 伪装和自适应元素跟踪功能。

何时使用 Scrapling，何时使用 Firecrawl

需求	使用	原因
从 URL 获取干净的 Markdown	firecrawl scrape --only-main-content	针对 LLM Markdown 转换进行了优化
绕过 Cloudflare/反机器人机制	scrapling 隐蔽抓取	内置 Turnstile 解决器和 Patchright 隐蔽功能
提取特定元素	使用 CSS/XPath 选择器的 scrapling	精确到元素级别，并支持自适应跟踪
没有可用的 API 密钥	scrapling	100% 本地运行，无需任何凭据
批量云端抓取	firecrawl crawl / batch-scrape	云基础设施，支持并行处理
适应网站改版	scrapling 自适应模式	基于 SQLite 的相似度匹配
并发抓取整个网站	scrapling Spider 框架	类似 Scrapy，支持暂停/恢复
网页搜索并抓取	firecrawl search --scrape	结合搜索与提取

安装

运行一次即可设置 Scrapling 的所有功能：

~/.claude/skills/scrapling/scripts/scrapling_install.sh

通过 uv 安装 scrapling[all]，下载 Chromium 和系统依赖，并验证所有抓取器均可加载。

快速入门 -- 标准输出包装器

该包装器直接使用 Scrapling 的 Python API（速度快于 CLI，可避免 curl_cffi 证书问题），并将结果输出到标准输出，以便传递给 filter_web_results.py：

# Basic HTTP fetch (fastest, TLS impersonation)
python3 ~/.claude/skills/scrapling/scripts/scrapling_fetch.py https://example.com

# Stealth mode (Patchright, anti-bot bypass)
python3 ~/.claude/skills/scrapling/scripts/scrapling_fetch.py https://protected.site --stealth

# Stealth + Cloudflare solver
python3 ~/.claude/skills/scrapling/scripts/scrapling_fetch.py https://cf-protected.site --stealth --solve-cloudflare

# Dynamic (Playwright Chromium, JS rendering)
python3 ~/.claude/skills/scrapling/scripts/scrapling_fetch.py https://js-heavy.site --dynamic

# With CSS selector for targeted extraction
python3 ~/.claude/skills/scrapling/scripts/scrapling_fetch.py https://example.com --css ".product-list"

# Pipe through firecrawl's filter for token efficiency
python3 ~/.claude/skills/scrapling/scripts/scrapling_fetch.py https://example.com --stealth | \
  python3 ~/.claude/skills/firecrawl/scripts/filter_web_results.py --sections "Pricing" --max-chars 5000

完整路径： python3 ~/.claude/skills/scrapling/scripts/scrapling_fetch.py 参数： --stealth、--dynamic、--css SELECTOR、--solve-cloudflare、--impersonate BROWSER、--format {text,html}、--no-headless、--timeout SECONDS

对于 --network-idle、--real-chrome 或 POST 请求，请使用下面的直接 CLI 方式。

快速入门 -- 直接使用 CLI

对于基于文件的输出（Scrapling 原生 CLI）：

# HTTP fetch -> markdown
scrapling extract get 'https://example.com' content.md

# HTTP with CSS selector and browser impersonation
scrapling extract get 'https://example.com' content.md --css-selector '.main-content' --impersonate chrome

# Dynamic fetch (Playwright, JS rendering)
scrapling extract fetch 'https://example.com' content.md

# Stealth with Cloudflare bypass
scrapling extract stealthy-fetch 'https://protected.site' content.md --solve-cloudflare

# Stealth with CSS selector, visible browser for debugging
scrapling extract stealthy-fetch 'https://site.com' content.md --css-selector '.data' --no-headless

三种抓取器等级

CLI 动词	引擎	隐蔽性	JS	速度
get	curl_cffi（HTTP）	TLS 伪装	否	快
fetch	Playwright/Chromium	中	是	中
stealthy-fetch	Patchright/Chrome	最高	是	较慢

Python API

用于元素级提取、自动化，或 CLI 无法满足需求时：

from scrapling.fetchers import Fetcher, StealthyFetcher, DynamicFetcher

# Simple HTTP fetch with CSS extraction
page = Fetcher.get('https://example.com', impersonate='chrome')
titles = page.css('.item h2::text').getall()
links = page.css('a::attr(href)').getall()

# Stealth with Cloudflare bypass
page = StealthyFetcher.fetch('https://protected.site',
    headless=True, solve_cloudflare=True,
    hide_canvas=True, block_webrtc=True)
data = page.css('.content').get_all_text()

# Page automation (login, click, fill)
def login(page):
    page.fill('#username', 'user')
    page.fill('#password', 'pass')
    page.click('#submit')

page = StealthyFetcher.fetch('https://app.example.com', page_action=login)

解析（不抓取）

from scrapling.parser import Selector

page = Selector("<html>...</html>")
page.css('.item::text').getall()       # CSS with pseudo-elements
page.xpath('//div[@class="item"]')     # XPath
page.find_all('div', class_='item')    # BeautifulSoup-style
page.find_by_text('Add to Cart')       # Text search
page.find_by_regex(r'Price: \$\d+')    # Regex search

自适应抓取

Scrapling 的标志性功能。元素会生成指纹并保存到 SQLite；网站改版后，系统会通过相似度评分重新定位这些元素。

from scrapling.fetchers import Fetcher

Fetcher.adaptive = True
page = Fetcher.get('https://example.com')

# First run: save element fingerprint
products = page.css('.product-list', auto_save=True)

# Later, after site redesign breaks the selector:
products = page.css('.product-list', adaptive=True)  # Still finds it

阅读：references/adaptive-scraping.md

Spider 框架

用于支持并发、暂停/恢复和会话路由的全站抓取：

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

class ResearchSpider(Spider):
    name = "research"
    start_urls = ["https://example.com/"]
    concurrent_requests = 10

    def configure_sessions(self, manager):
        manager.add("fast", FetcherSession(impersonate="chrome"))
        manager.add("stealth", StealthySession(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")
        for item in response.css('.article'):
            yield {"title": item.css('h2::text').get(), "url": response.url}

result = ResearchSpider().start(crawldir="./data")  # Pause/resume enabled
result.items.to_json("output.json")

故障排除

• 找不到浏览器： 运行 scrapling install 下载浏览器依赖
• 抓取器导入错误： 安装完整软件包：uv pip install "scrapling[all]"
• Cloudflare 仍在拦截： 组合使用参数：--solve-cloudflare --block-webrtc --hide-canvas
• HTTP 抓取器出现 SSL 证书错误： curl_cffi 附带的 CA 证书在 macOS/pyenv 上可能已过期。包装器会自动处理此问题（verify=False）。对于 Python API，请向 Fetcher.get() 传入 verify=False。
• 隐蔽抓取速度较慢： 这是预期情况——浏览器自动化本质上比 HTTP 请求慢。无需隐蔽抓取时，请使用 get（HTTP）。

参考文档

文件	内容
references/cli-reference.md	完整的 CLI 提取命令参考（get、post、fetch、stealthy-fetch）
references/python-api-reference.md	Python API（Fetcher、DynamicFetcher、StealthyFetcher、Sessions、Spiders）
references/adaptive-scraping.md	自适应元素跟踪详解（保存、匹配、相似度评分）