Scrapling extract 命令完全指南：零代码在终端下载网页并转换为 Markdown/HTML/纯文本

本文围绕 Scrapling 的 scrapling extract 命令组展开，系统讲解如何在完全不编写 Python 代码的前提下，从终端发起 GET/POST/PUT/DELETE 请求或启动真实浏览器抓取网页，并按输出文件扩展名自动将结果保存为 HTML、Markdown 或纯文本。读完后，你可以直接使用 get/post/put/delete/fetch/stealthy-fetch 六个子命令完成从简单博客到带 Cloudflare 防护站点的快速数据提取，并理解 --css-selector、--impersonate、--ai-targeted 等关键选项在源码中的真实行为。

1. 前置准备与适用前提

extract 命令自 v0.3 起内置于 Scrapling 的命令行接口中（见 CLI 总览），使用它之前需要完成两步安装：

# 安装带 shell 额外依赖组的 Scrapling（CLI 依赖 Click、IPython 等）
pip install "scrapling[shell]"

# 下载 Playwright 浏览器、系统依赖及指纹操作依赖（fetch/stealthy-fetch 需要）
scrapling install

从 CLI 源码 可以看到，若未安装任何 extras 导致 click 缺失，导入 scrapling.cli 会直接抛出 ModuleNotFoundError，提示需要先以 extras 方式安装——这解释了为什么 pip install scrapling 的裸安装无法使用 extract。

此外，建议先阅读以下文档页面，理解命令背后涉及的核心对象：

• Fetchers 基础：理解 Response 对象是什么、该选哪个 fetcher；
• 查询元素：理解如何用 CSS 选择器从 Selector/Response 对象中提取内容；
• 主类说明：了解 Response 从 Selector 继承了哪些属性/方法；
• 以及至少一页 fetcher 文档用于实际发请求：HTTP 请求、动态网站 或 强防护动态网站。

2. extract 命令组是什么

scrapling extract 是一组“终端即爬虫”的工具，核心能力包括：

• 下载网页：抓取页面内容并保存到文件；
• 格式转换：把 HTML 转为 Markdown、原样保留 HTML、或只抽取纯文本内容；
• CSS 选择器提取：通过 --css-selector（或 -s）只提取页面的特定部分；
• HTTP 请求与浏览器抓取双通道：既支持底层 HTTP 四方法，也支持通过浏览器执行 JS；
• 高度可定制：自定义 headers、cookies、代理等，代码中几乎可用的所有选项都在命令行上暴露。

用 scrapling extract --help 可以查看完整的命令列表：

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

  Fetch web pages using various fetchers and extract full/selected HTML content as HTML, Markdown, or extract text content.

Options:
  --help  Show this message and exit.

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 DynamicFetcher to fetch content with browser...
  stealthy-fetch  Use StealthyFetcher to fetch content with advanced...

从 cli.py 的源码结构 看，extract 是一个 Click group，六个子命令分别注册在其下；scrapling install、scrapling shell、scrapling mcp 则注册在顶层 main group 中（cli.py#L688-L698）。

快速上手

基础下载——对网页发起 HTTP GET 请求，把正文文本存成文件：

scrapling extract get "https://example.com" page_content.txt

按扩展名选择输出格式：

# HTML 转 Markdown 后保存（适合文档场景）
scrapling extract get "https://blog.example.com" article.md

# 原样保存 HTML 内容
scrapling extract get "https://example.com" page.html

# 保存网页的干净纯文本版本
scrapling extract get "https://example.com" content.txt

# 使用 Docker 镜像时的等价用法
docker run -v $(pwd)/output:/output pyd4vinci/scrapling extract get "https://blog.example.com" /output/article.md

提取特定内容——所有命令都支持 -s/--css-selector 参数，只提取匹配节点（返回全部匹配项）。

3. 输出格式与文件扩展名的映射关系

“按扩展名决定输出格式”并不是 CLI 层的魔法，而是由 Convertor 类 实现的。其扩展名映射表如下（shell.py#L577-L581）：

文件扩展名	提取类型	底层实现
.md	markdown	调用 markdownify 库把 HTML 转成 Markdown（shell.py#L583-L588）
.html	html	直接输出节点的 html_content
.txt	text	调用 page.get_all_text(strip=True, ignore_tags=("script","style","noscript","svg","iframe"))，并对换行、回车、制表符、空格做连续空白压缩（shell.py#L643-L654）

write_content_to_file 会对文件名做严格校验：不是 .md/.html/.txt 结尾会直接抛出 ValueError: Unknown file type（shell.py#L662-L667），文件以响应自身的编码写入。

CLI 侧的调用链在 __Request_and_Save：先把相对输出路径解析为基于当前工作目录的绝对路径，调用对应 fetcher 发起请求，再交给 Convertor.write_content_to_file 落盘。所有六个 extract 子命令最终都汇聚到这一个函数。

4. HTTP 请求命令详解（get / post / put / delete）

四个 HTTP 命令共享同一套选项（由 _common_http_options 装饰器工厂统一注入），底层通过 Fetcher 类 发起请求——该类基于 curl_cffi 实现，因此支持浏览器指纹伪装（--impersonate）。

4.1 get 命令

scrapling extract get [URL] [OUTPUT_FILE] [OPTIONS]

常用示例：

# 基础下载
scrapling extract get "https://news.site.com" news.md

# 自定义超时
scrapling extract get "https://example.com" content.txt --timeout 60

# 使用 CSS 选择器只提取特定内容
scrapling extract get "https://blog.example.com" articles.md --css-selector "article"

# 携带 cookies 发请求
scrapling extract get "https://scrapling.requestcatcher.com" content.md --cookies "session=abc123; user=john"

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

# 添加多个 headers
scrapling extract get "https://site.com" page.html -H "Accept: text/html" -H "Accept-Language: en-US"

scrapling extract get --help 输出的完整选项：

选项	说明
-H, --headers TEXT	HTTP 头，格式 "Key: Value"（可多次使用）
--cookies TEXT	Cookies 字符串，格式 "name1=value1;name2=value2"
--timeout INTEGER	请求超时（秒），默认 30
--proxy TEXT	代理 URL，格式 "http://username:password@host:port"
-s, --css-selector TEXT	CSS 选择器，提取页面特定内容，返回全部匹配
-p, --params TEXT	查询参数，格式 "key=value"（可多次使用）
--follow-redirects / --no-follow-redirects	是否跟随重定向（默认 True）
--verify / --no-verify	是否校验 SSL 证书（默认 True）
--impersonate TEXT	要伪装的浏览器（如 chrome、firefox）
--stealthy-headers / --no-stealthy-headers	使用伪装浏览器头（默认 True）
--ai-targeted	只提取正文并清理隐藏元素，供 AI 消费（默认 False）

4.2 post / put 命令（额外支持请求体）

scrapling extract post [URL] [OUTPUT_FILE] [OPTIONS]
scrapling extract put  [URL] [OUTPUT_FILE] [OPTIONS]

post/put 在 HTTP 公共选项之外，多两个由 _data_options 注入的选项：

选项	说明
-d, --data TEXT	请求体表单数据，字符串形式，如 "param1=value1&param2=value2"
-j, --json TEXT	请求体 JSON 数据（字符串）

示例：

# POST：提交表单数据
scrapling extract post "https://api.site.com/search" results.html --data "query=python&type=tutorial"

# POST：发送 JSON 数据
scrapling extract post "https://api.site.com" response.json --json '{"username": "test", "action": "search"}'

# PUT：发送数据（配合浏览器伪装）
scrapling extract put "https://scrapling.requestcatcher.com/put" results.html --data "update=info" --impersonate "firefox"

# PUT：发送 JSON 数据
scrapling extract put "https://scrapling.requestcatcher.com/put" response.json --json '{"username": "test", "action": "search"}'

源码中 JSON 字符串先经 __ParseJSONData 用 orjson 解析，非法 JSON 会抛出带原始内容的 ValueError；解析结果连同 headers、cookies、params 一起由 __BuildRequest 组装成请求参数。注意 GET 与 DELETE 不传 data/json，因此它们没有 -d/-j 选项。

4.3 delete 命令

scrapling extract delete [URL] [OUTPUT_FILE] [OPTIONS]

选项与 get 完全一致（无请求体选项）。示例：

# 发送数据
scrapling extract delete "https://scrapling.requestcatcher.com/delete" results.html

# 带浏览器伪装
scrapling extract delete "https://scrapling.requestcatcher.com/" response.txt --impersonate "chrome"

4.4 --impersonate 的隐藏能力：随机挑选浏览器

help 文本只说 --impersonate 接受单个浏览器名，但源码里有一处额外的解析逻辑（cli.py#L103-L105）：如果传入值包含逗号，会被切分成列表再交给 Fetcher，实现随机挑选一个浏览器指纹发送请求：

# 从 chrome/firefox/safari 中随机挑选一种指纹
scrapling extract get "https://example.com" out.html --impersonate "chrome,firefox,safari"

该行为有对应的测试用例 test_impersonate_comma_separated 验证：传入 "chrome,firefox,safari" 后，Fetcher 实际收到的 impersonate 是列表 ["chrome", "firefox", "safari"]；而单个值则保持字符串形式（test_impersonate_single_browser）。

5. 浏览器抓取命令详解（fetch / stealthy-fetch）

当页面靠 JavaScript 动态加载内容或有防护时，改用浏览器通道。两个命令的选项由 _common_browser_options 统一注入，参数经 __build_browser_kwargs 组装后分别传给 DynamicFetcher.fetch 与 StealthyFetcher.fetch（cli.py#L570-L685）。

5.1 fetch —— 处理动态内容

面向“用 JS 动态加载内容或防护较轻”的网站：

scrapling extract fetch [URL] [OUTPUT_FILE] [OPTIONS]

示例：

# 等待 JS 加载完成且网络空闲
scrapling extract fetch "https://scrapling.requestcatcher.com/" content.md --network-idle

# 等待特定内容出现后再提取
scrapling extract fetch "https://scrapling.requestcatcher.com/" data.txt --wait-selector ".content-loaded"

# 有头模式运行（调试友好），同时丢弃无用资源提速
scrapling extract fetch "https://scrapling.requestcatcher.com/" page.html --no-headless --disable-resources

完整选项：

选项	说明
--headless / --no-headless	无头模式运行（默认 True）
--disable-resources / --enable-resources	丢弃图片/媒体等资源提速（默认 False）
--network-idle / --no-network-idle	等待网络空闲（默认 False）
--timeout INTEGER	超时（毫秒），默认 30000
--wait INTEGER	页面加载后的额外等待毫秒数（默认 0）
-s, --css-selector TEXT	CSS 选择器，返回全部匹配
--wait-selector TEXT	继续执行前等待的 CSS 选择器
--locale TEXT	用户 locale，默认取系统 locale
--real-chrome / --no-real-chrome	使用本机已安装的 Chrome 浏览器实例（默认 False）
--proxy TEXT	代理 URL，格式 "http://username:password@host:port"
-H, --extra-headers TEXT	额外 headers，格式 "Key: Value"（可多次使用）
--dns-over-https / --no-dns-over-https	DNS 走 Cloudflare DoH，防止使用代理时 DNS 泄漏（默认 False）
--block-ads / --no-block-ads	拦截已知广告/追踪域名请求（默认 False）
--executable-path TEXT	自定义 Chromium 兼容浏览器可执行文件路径，未设置时回退到 SCRAPLING_EXECUTABLE_PATH 环境变量
--ai-targeted	只提取正文并清理隐藏元素（默认 False）

两个源码级细节值得注意：

1. --wait 与 --wait-selector 是按需传递的：只有 wait > 0 或提供了 wait_selector 时才会写入 kwargs（cli.py#L556-L559），避免用 0/空值覆盖 fetcher 的默认行为；
2. 可执行文件路径有双通道：--executable-path 优先，否则回退环境变量 SCRAPLING_EXECUTABLE_PATH（cli.py#L564-L566），tests/cli/test_cli.py 中有对“传参”“环境变量回退”“两者皆无”三种场景的测试。

5.2 stealthy-fetch —— 绕过强防护

面向反爬/Cloudflare 防护站点：

scrapling extract stealthy-fetch [URL] [OUTPUT_FILE] [OPTIONS]

示例：

# 绕过基础防护
scrapling extract stealthy-fetch "https://scrapling.requestcatcher.com" content.md

# 求解 Cloudflare 质询并只提取目标节点
scrapling extract stealthy-fetch "https://nopecha.com/demo/cloudflare" data.txt --solve-cloudflare --css-selector "#padded_content a"

# 使用代理保持匿名
scrapling extract stealthy-fetch "https://site.com" content.md --proxy "http://proxy-server:8080"

stealthy-fetch 拥有与 fetch 相同的全部公共浏览器选项，另加 4 个专属反指纹开关（cli.py#L615-L633）：

选项	说明
--block-webrtc / --allow-webrtc	完全阻断 WebRTC（默认 False）
--solve-cloudflare / --no-solve-cloudflare	自动求解 Cloudflare 质询（默认 False）
--allow-webgl / --block-webgl	是否允许 WebGL（默认 True）
--hide-canvas / --show-canvas	给 canvas 操作加噪（默认 False）

6. --ai-targeted：面向 AI 消费的正文清洗模式

所有 extract 命令都支持 --ai-targeted 标志。启用后，CLI 会做三件事：

1. 自动开启广告拦截：在 __Request_and_Save 中 kwargs.setdefault("block_ads", True)，对浏览器命令（fetch/stealthy-fetch）自动屏蔽广告与追踪域名请求；
2. 只保留正文：先取 <body> 首个节点，再调用 _strip_noise_tags 移除 script、style、noscript、svg 噪声标签；
3. 防提示注入清洗：_sanitize_for_ai 会删除 CSS 隐藏、aria-hidden、<template> 等隐藏元素（这类内容常被用来做 prompt injection），剥离零宽 Unicode 字符与控制字符，并以 keep_comments=False 去掉 HTML 注释。

实现入口在 _extract_content：当 main_content_only=True 时依次执行 css("body").first → _strip_noise_tags → _sanitize_for_ai，然后才进入格式转换与（可选的）CSS 选择器提取。也就是说 --ai-targeted 与 -s/--css-selector 可以叠加使用——先清洗正文，再在正文内按选择器定位。

7. 如何选择合适的命令

如果不是爬虫专家、拿不准选哪个，可以套用这条决策公式：

• 简单网站、博客、新闻文章 → get（也可按需使用 post/put/delete）；
• 现代 Web 应用、动态内容站点 → fetch；
• 受保护站点、Cloudflare、反爬系统 → stealthy-fetch。

各通道对应的底层实现分别是：HTTP 命令走 Fetcher（curl_cffi），fetch 走 DynamicFetcher，stealthy-fetch 走 StealthyFetcher，三者最终都返回同一个可查询的 Response/Selector 对象，再统一交给 Convertor 落盘。

8. 法律与道德准则

原文档同时强调，使用这些命令时必须遵守以下准则：

• 检查 robots.txt：访问 https://网站/robots.txt 查看抓取规则；
• 尊重速率限制：不要以过大的请求量冲击服务器；
• 服务条款：阅读并遵守目标网站条款；
• 版权：尊重知识产权；
• 隐私：注意个人数据保护法规；
• 商业用途：确保已获得商业使用授权。

始终尊重网站政策并遵守所有适用法律法规。

9. 小结

scrapling extract 把 Scrapling 的核心抓取与解析能力完整暴露到了终端：六个子命令覆盖“HTTP 四方法 + 双浏览器通道”，三种输出格式由文件扩展名自动决定，-s 选择器、--impersonate（支持逗号分隔随机指纹）、--ai-targeted（正文清洗 + 防提示注入 + 自动广告拦截）等选项让零代码场景也能做到精细控制。所有命令的选项均可通过 scrapling extract <command> --help 现场核对；其实现细节集中在 scrapling/cli.py 与 scrapling/core/shell.py 的 Convertor 类，行为验证可参考 tests/cli/test_cli.py。