亿
亿牛云
登录免费注册
博客/技术指南

Obscura CLI 指南——七种输出格式与并发抓取

Obscura 命令行的完整操作手册。fetch 命令的七种 --dump 输出格式、scrape 并发抓取、--eval 执行 JS、等待策略与超时控制。

亿牛云技术团队2026年7月1日5 分钟阅读

一条命令等于一个浏览器

Obscura CLI 是项目最直接的使用方式。你不需要写代码、不需要启动服务、不需要安装 Chrome——下载一个二进制文件，即可开始抓取网页。

CLI 入口是 obscura 命令，由四个子命令组成：

  • obscura fetch <URL> — 抓取单个页面并输出数据
  • obscura serve — 启动 CDP WebSocket 服务，供 Puppeteer/Playwright 连接
  • obscura scrape <URL...> — 并发抓取多个页面
  • obscura mcp — 启动 MCP 服务器，供 AI Agent 使用

本文聚焦 fetch 和 scrape 两个数据提取命令。

安装与验证

从 Releases 下载对应平台的二进制（以下地址为示例，替换为实际发布页地址）：

# Linux x86_64
curl -LO https://example.16yun.cn/obscura/releases/latest/download/obscura-x86_64-linux.tar.gz
tar xzf obscura-x86_64-linux.tar.gz
 
# macOS Apple Silicon
curl -LO https://example.16yun.cn/obscura/releases/latest/download/obscura-aarch64-macos.tar.gz
tar xzf obscura-aarch64-macos.tar.gz

验证安装：

./obscura --version
./obscura fetch https://example.com --eval "document.title" --quiet

结果输出纯文本格式的页面标题。

obscura fetch：七种输出格式

fetch 是最核心的子命令。--dump 参数控制输出格式，共七种。

--dump html

默认格式。返回 JavaScript 渲染完成后的完整 HTML 字符串。

obscura fetch https://httpbin.org/anything --dump html

适用于后续用其他工具解析 HTML 结构的场景。

--dump text

纯文本格式。去除所有标记、样式和脚本，只保留可见文本。

obscura fetch https://httpbin.org/anything --dump text

适合做全文搜索、关键词提取、字数统计。

--dump markdown

转换为 Markdown 格式。保留标题层级、列表、链接、代码块、图片、表格结构。

obscura fetch https://example.16yun.cn/help/quickstart/ --dump markdown > page.md

这是最推荐用于 LLM / RAG 场景的格式——结构清晰、Token 消耗少。

--dump links

提取页面中所有 <a href> 链接，每行一个。URL 去重后输出。

obscura fetch https://example.com --dump links

适用于 SEO 分析、外链检查、网站地图构建。

--dump assets

以 NDJSON 格式输出页面引用的所有子资源 URL，包括：

  • 样式表（<link rel="stylesheet">）
  • 脚本（<script src>）
  • 图片（<img src>）
  • 字体、iframe、embed、object
  • JavaScript 发起的 fetch/XHR 请求
obscura fetch https://example.com --dump assets

每行一个 JSON 对象，便于管道处理。

--dump original

输出服务器返回的原始 HTTP 响应体，不经过 JavaScript 渲染。二进制安全。

obscura fetch https://httpbin.org/image/png --dump original > photo.jpg

适用于获取图片、JSON API、CSS、JS 等非 HTML 资源。

--dump cookies

输出浏览器 Cookie Jar 中所有 Cookie 的 JSON 数组，包括 HttpOnly 标记的 Cookie（document.cookie 看不到的那些）。

obscura fetch https://example.com --dump cookies

适用于提取反 Bot 挑战后设置的 Session Token。

--eval 执行 JavaScript

用 --eval 在页面加载后执行任意 JavaScript 表达式，返回结果：

obscura fetch https://httpbin.org/anything --eval "JSON.stringify(Array.from(document.querySelectorAll('.titleline > a')).map(a => ({title: a.textContent, url: a.href})))"

注意：如果 --eval 以 const 开头定义的表达式会返回 null（V8 中 const 声明的 completion value 为空）。建议用 IIFE 包裹：

obscura fetch https://example.com --eval "(function(){ return document.title; })()"

--eval 可以单独使用，也可以与 --dump 组合——先执行 eval，让异步操作完成，再读取页面内容。

等待策略

SPA 页面需要等待 JavaScript 执行完成后才能读取内容。--wait-until 控制等待条件：

# 等待 load 事件（默认）
obscura fetch https://example.16yun.cn --wait-until load
 
# 等待 DOMContentLoaded
obscura fetch https://example.16yun.cn --wait-until domcontentloaded
 
# 等待网络空闲（无请求 500ms）
obscura fetch https://example.16yun.cn --wait-until networkidle0
 
# 等待网络基本空闲（无请求 500ms，允许 2 个以内连接）
obscura fetch https://example.16yun.cn --wait-until networkidle2

--wait 参数在等待条件满足后再额外停留一段时间，让异步定时器完成：

obscura fetch https://example.16yun.cn --wait 10

--selector 限定区域

用 CSS 选择器限定输出范围，跳过导航、侧栏和页脚：

obscura fetch https://example.com --selector "main" --dump markdown
obscura fetch https://example.com --selector "article.post" --dump text

与 --dump markdown 组合时特别有用——只提取正文内容。

--timeout 与进程级硬截止

--timeout 控制导航超时时间（默认 30 秒）：

obscura fetch https://example.16yun.cn --timeout 60

Obscura 还有一个进程级硬截止线程，在 timeout + wait + 10 秒后强制退出进程。这是最后的兜底——V8 watchdog 无法终止已经进入 Rust op 的同步调用，硬截止从操作系统层面保证一个坏页面不会挂死 Worker。

obscura scrape：并发抓取

scrape 命令用 Worker 进程并发抓取多个 URL：

obscura scrape url1 url2 url3 --concurrency 25 --format json

参数说明：

  • --concurrency：并发 Worker 数（默认 10）
  • --format：输出格式，json 或 text
  • --timeout：每个 Worker 的超时时间（默认 60 秒）
  • --eval：每个页面执行的 JS
  • --quiet：静默模式，抑制进度输出

从 stdin 读取 URL 列表：

cat urls.txt | obscura scrape --concurrency 20 --format json -

要求 obscura-worker 与 obscura 在同一目录下。

输出与管道集成

--output（或 -o）参数将结果写入文件：

obscura fetch https://example.com --dump markdown --output page.md
obscura fetch https://example.com --eval "document.title" -o title.txt

--quiet 抑制横幅和日志，使输出适合脚本化：

obscura fetch https://example.com --dump text --quiet | wc -w

结合标准的 Unix 管道：

obscura fetch https://example.com --dump links --quiet | grep 'blog' | head -10

全局参数

以下是适用于所有子命令的全局参数：

参数作用
--proxy <URL>HTTP/SOCKS5 代理
--stealth启用反检测模式
--user-agent <UA>自定义 UA
--allow-private-network允许访问内网地址（默认禁止）
--v8-flags <FLAGS>传递 V8 参数
--verbose详细日志
obscura --proxy socks5://127.0.0.1:1080 --stealth fetch https://example.com --dump markdown

完整示例：抓取 SPA 页面并保存 Markdown

这是一个端到端的实用示例：

# 设置代理和超时
export OBSCURA_PROXY=http://user:pass@proxy.16yun.cn:8888
 
# 抓取 SPA 页面，等待 networkidle0，提取正文为 Markdown
obscura fetch https://example.16yun.cn \
  --wait-until networkidle0 \
  --selector "main" \
  --dump markdown \
  --output article.md \
  --stealth
 
# 提取页面标题
obscura fetch https://example.16yun.cn \
  --eval "document.title" \
  --quiet

环境变量调优

通过环境变量控制超时和资源：

export OBSCURA_NAV_TIMEOUT_MS=60000
export OBSCURA_FETCH_TIMEOUT_MS=15000
obscura fetch https://example.16yun.cn --dump text

完整的环境变量列表见官方文档。

总结

obscura fetch 和 obscura scrape 覆盖了从单页抓取到并发批量的全部需求。七种输出格式适配不同的下游处理场景，--eval 提供了无上限的灵活性，而等待策略和超时体系确保你能可靠地处理 SPA 和慢页面。

需要企业代理方案？

我们可根据目标站点、并发规模与稳定性目标提供定制方案。

预约咨询查看套餐