Scrapling

通过稳健的选择器模式、自适应定位和针对目标的正确抓取模式，从网站中提取结构化数据。

工作流程

1. 编写代码前先识别目标类型：

- 静态页面或类似 API 的 HTML 响应使用 Fetcher。

- 需要 JavaScript 渲染时使用 DynamicFetcher。

- 可能存在反爬虫保护或浏览器指纹检测时使用 StealthyFetcher。

1. 优先选择输出格式：

- 用于流水线或自动化任务时返回 JSON。

- 用于摘要生成或 RAG 数据摄入时返回 Markdown 或纯文本。

- 即使选择器策略变更，也保持字段名称稳定。

1. 按照以下顺序实现选择器：

- 优先使用 CSS 选择器和伪元素（例如 ::text、::attr(href)）。

- 当 DOM 结构模糊时回退到 XPath。

- 对于脆弱或频繁变化的页面启用自适应定位功能。

1. 添加安全控制措施：

- 尊重目标站点的使用条款与法律边界。

- 设置超时时间、重试机制并添加明确的错误处理。

- 记录状态码、URL 和选择器未匹配的情况以供调试。

1. 至少在两个页面上进行验证：

- 测试一个正常流程页面和一个边缘情况页面。

- 确保必填字段不为空。

- 保持提取过程确定性（避免隐藏的随机行为）。

快速设置

1. 安装基础包：

- pip install scrapling

1. 在需要基于浏览器的抓取时安装抓取器：

- pip install "scrapling[fetchers]"

- scrapling install

- python3 -m playwright install（DynamicFetcher 和 StealthyFetcher 所需）

1. 根据需要安装可选扩展：

- pip install "scrapling[shell]" 以获得 shell 命令行 + extract 功能

- pip install "scrapling[ai]" 以支持 MCP 能力

执行模式

模式：一次性终端提取

使用 Scrapling CLI 实现最快无代码提取：

scrapling extract get "https://example.com" content.md --css-selector "main"

模式：Python 提取脚本

使用内置辅助脚本：

# 静态页面（默认）
python scripts/extract_with_scrapling.py --url "https://example.com" --css "h1::text"

# JavaScript 渲染页面
python scripts/extract_with_scrapling.py --url "https://example.com" --fetcher dynamic --css "h1::text"

# 反爬虫保护页面
python scripts/extract_with_scrapling.py --url "https://example.com" --fetcher stealthy --css "h1::text"

模式：会话级抓取

当需要跨请求保持 Cookie 或状态时，使用会话类：

from scrapling.fetchers import FetcherSession

session = FetcherSession()
login_page = session.post("https://example.com/login", data={"user": "...", "pass": "..."})
protected_page = session.get("https://example.com/dashboard")
headline = protected_page.css_first("h1::text")

对于反爬虫或 JavaScript 渲染的目标，可直接替换为 StealthySession 或 DynamicSession。

模式：DOM 变化容错

在首次抓取时启用 auto_save=True，并在后续运行中使用自适应选择以应对选择器失效的情况：

from scrapling.fetchers import Fetcher

# 首次运行：保存 DOM 快照，以便后续自适应定位生效
page = Fetcher.auto_match("https://example.com", auto_save=True, disable_adaptive=False)
price = page.css_first(".price::text")

# 后续运行：即使 DOM 结构发生变化，也能自动重新定位选择器
page = Fetcher.auto_match("https://example.com", auto_save=False, disable_adaptive=False)
price = page.css_first(".price::text")

参考资料

• 使用 [scrapling-reference.md](references/scrapling-reference.md) 查看抓取器/API 示例及选择器模式。
• 使用 [extract_with_scrapling.py](scripts/extract_with_scrapling.py) 获取可复用的 CLI 脚本模板。