## 项目概述

Scrapling 是一个自适应 Web Scraping 框架，旨在处理从单个 HTTP 请求到大规模并发爬取的各种需求。它提供了一套完整的工具，包括智能解析器、多种网页获取器（Fetcher）、以及一个功能强大的爬虫（Spider）框架。Scrapling 的核心优势在于其自适应能力：解析器能够学习网站结构的变化并自动重新定位元素，获取器能够绕过 Cloudflare Turnstile 等反机器人系统，爬虫框架则支持并发、多会话、暂停/恢复以及自动代理轮换。此外，Scrapling 还集成了 AI 功能，如 MCP 服务器、Agent Skill 和 RAG 就绪的 Markdown 转换，使其成为现代 Web 数据采集的强大工具。

## 核心功能

- **自适应解析**：智能元素跟踪，在网站结构变化后自动重新定位元素；支持 CSS、XPath、文本、正则等多种选择方式；可查找相似元素。
- **多种网页获取器**：`Fetcher`（HTTP 请求，可模拟浏览器 TLS 指纹）、`DynamicFetcher`（完整浏览器自动化）、`StealthyFetcher`（高级反检测，可绕过 Cloudflare）。
- **会话管理**：支持持久化会话（`FetcherSession`、`DynamicSession`、`StealthySession`），管理 Cookies 和状态。
- **代理轮换**：内置 `ProxyRotator`，支持循环或自定义策略。
- **爬虫框架**：类 Scrapy 的 API，支持并发、多会话、暂停/恢复、流式输出、自动限速（AutoThrottle）、robots.txt 合规等。
- **现成爬虫模板**：`CrawlSpider`、`SitemapSpider`、`XMLFeedSpider`、`CSVFeedSpider`、`ShopifySpider` 等。
- **AI 集成**：内置 MCP 服务器，供 AI 智能体调用；提供 Agent Skill 供编码智能体学习；支持将网页转换为干净的 Markdown 用于 RAG。
- **命令行工具**：提供交互式 Shell 和 `extract` 命令，无需编写代码即可抓取网页。
- **高性能**：解析器性能优于大多数 Python 抓取库，内存占用低。

## 适用与不适用场景

**适用场景：**

- 需要从简单到复杂的网页数据采集，包括静态和动态内容。
- 需要绕过 Cloudflare 等反机器人保护。
- 需要大规模、并发、可中断恢复的爬虫任务。
- 需要将网页内容转换为干净的 Markdown 用于 LLM 或 RAG 系统。
- 希望为 AI 智能体（如 Claude、Cursor）提供网页抓取能力。

**不适用场景：**

- 仅需简单、一次性的 HTTP 请求，可能使用更轻量的库（如 `requests`）即可。
- 需要严格遵守网站服务条款，且网站明确禁止爬虫的场景（请务必遵守 robots.txt 和法律法规）。
- 对抓取行为的合法性有严格限制的企业环境，需自行评估风险。

## 技术架构与依赖

- **编程语言**：Python 3.10+
- **核心依赖**：`lxml`（解析）、`curl_cffi`（HTTP 请求）、`Playwright`/`Patchright`（浏览器自动化）、`anyio`（异步支持）等。
- **可选依赖**：`scrapling[fetchers]`（获取器和爬虫）、`scrapling[ai]`（MCP 服务器）、`scrapling[rag]`（Markdown 转换）、`scrapling[shell]`（命令行工具）、`scrapling[all]`（全部）。
- **浏览器**：需要下载 Chromium 等浏览器（通过 `scrapling install` 命令）。
- **Docker**：提供包含所有浏览器和依赖的 Docker 镜像。

## 安装与快速开始

**安装：**

```bash
pip install scrapling
```

> **注意**：基础安装仅包含解析器。如需使用获取器、爬虫、AI 等功能，需安装额外依赖：

```bash
pip install "scrapling[fetchers]"  # 获取器和爬虫
pip install "scrapling[ai]"       # MCP 服务器
pip install "scrapling[rag]"      # RAG 支持
pip install "scrapling[shell]"    # 命令行工具
pip install "scrapling[all]"      # 全部功能
```

安装浏览器依赖：

```bash
scrapling install
```

**快速开始：**

```python
from scrapling.fetchers import Fetcher

# 获取网页并解析
page = Fetcher.get('https://example.com')
quotes = page.css('.quote .text::text').getall()
print(quotes)
```

## 典型使用方法

**1. 使用 StealthyFetcher 绕过 Cloudflare：**

```python
from scrapling.fetchers import StealthyFetcher

page = StealthyFetcher.fetch('https://protected-site.com', solve_cloudflare=True)
data = page.css('#content').getall()
```

**2. 定义爬虫进行大规模抓取：**

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

**3. 将网页转换为 Markdown 用于 RAG：**

```python
from scrapling.fetchers import Fetcher

markdown = Fetcher.get("https://example.com").markdown(main_content_only=True)
```

**4. 使用 MCP 服务器：**

```bash
scrapling-mcp
```

然后在支持 MCP 的客户端（如 Claude Desktop）中配置并对话式地请求抓取。

## 配置与部署要点

- **浏览器依赖**：使用浏览器相关功能前，必须运行 `scrapling install` 下载浏览器。
- **代理配置**：可通过 `proxy` 参数或 `ProxyRotator` 配置代理，支持 HTTP、SOCKS 等。
- **反检测配置**：`StealthyFetcher` 可配置 `headless`、`solve_cloudflare` 等参数。
- **爬虫配置**：可通过类属性配置并发数、延迟、超时、robots.txt 合规等。
- **MCP 服务器安全**：HTTP 传输模式默认要求认证（`--auth-token`），并默认绑定 localhost。
- **Docker 部署**：可使用 `pyd4vinci/scrapling` 镜像，包含所有浏览器和依赖。

## 限制、风险与许可证

- **法律风险**：本项目仅供教育和研究目的。使用者需遵守当地法律和网站服务条款，尊重 robots.txt。作者不对滥用负责。
- **反爬虫对抗**：绕过反机器人系统可能违反网站条款，存在账号封禁等风险。
- **许可证**：BSD-3-Clause。

## 官方链接

- **GitHub 仓库**：[https://github.com/D4Vinci/Scrapling](https://github.com/D4Vinci/Scrapling)
- **文档**：[https://scrapling.readthedocs.io](https://scrapling.readthedocs.io)
- **PyPI**：[https://pypi.org/project/scrapling/](https://pypi.org/project/scrapling/)
- **Docker Hub**：[https://hub.docker.com/r/pyd4vinci/scrapling](https://hub.docker.com/r/pyd4vinci/scrapling)

## 信息来源和分析时间

- **信息来源**：GitHub 仓库 README、文档、CHANGELOG。
- **分析时间**：2026-08-23（基于最新 release v0.4.15）。