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.com/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.com/obscura/releases/latest/download/obscura-aarch64-macos.tar.gz
tar xzf obscura-aarch64-macos.tar.gz
```bash
验证安装：
```bash
./obscura --version
./obscura fetch https://example.com --eval "document.title" --quiet
```bash
结果输出纯文本格式的页面标题。
## obscura fetch：七种输出格式
`fetch` 是最核心的子命令。`--dump` 参数控制输出格式，共七种。
### --dump html
默认格式。返回 JavaScript 渲染完成后的完整 HTML 字符串。
```bash
obscura fetch https://httpbin.org/anything --dump html
```bash
适用于后续用其他工具解析 HTML 结构的场景。
### --dump text
纯文本格式。去除所有标记、样式和脚本，只保留可见文本。
```bash
obscura fetch https://httpbin.org/anything --dump text
```bash
适合做全文搜索、关键词提取、字数统计。
### --dump markdown
转换为 Markdown 格式。保留标题层级、列表、链接、代码块、图片、表格结构。
```bash
obscura fetch https://example.16yun.cn/help/quickstart/ --dump markdown > page.md
```bash
这是最推荐用于 LLM / RAG 场景的格式——结构清晰、Token 消耗少。
### --dump links
提取页面中所有 `<a href>` 链接，每行一个。URL 去重后输出。
```bash
obscura fetch https://example.com --dump links
```bash
适用于 SEO 分析、外链检查、网站地图构建。
### --dump assets
以 NDJSON 格式输出页面引用的所有子资源 URL，包括：
- 样式表（`<link rel="stylesheet">`）
- 脚本（`<script src>`）
- 图片（`<img src>`）
- 字体、iframe、embed、object
- JavaScript 发起的 fetch/XHR 请求
```bash
obscura fetch https://example.com --dump assets
```bash
每行一个 JSON 对象，便于管道处理。
### --dump original
输出服务器返回的原始 HTTP 响应体，不经过 JavaScript 渲染。二进制安全。
```bash
obscura fetch https://httpbin.org/image/png --dump original > photo.jpg
```bash
适用于获取图片、JSON API、CSS、JS 等非 HTML 资源。
### --dump cookies
输出浏览器 Cookie Jar 中所有 Cookie 的 JSON 数组，包括 HttpOnly 标记的 Cookie（`document.cookie` 看不到的那些）。
```bash
obscura fetch https://example.com --dump cookies
```bash
适用于提取反 Bot 挑战后设置的 Session Token。
## --eval 执行 JavaScript
用 `--eval` 在页面加载后执行任意 JavaScript 表达式，返回结果：
```bash
obscura fetch https://httpbin.org/anything --eval "JSON.stringify(Array.from(document.querySelectorAll('.titleline > a')).map(a => ({title: a.textContent, url: a.href})))"
```bash
注意：如果 `--eval` 以 `const` 开头定义的表达式会返回 `null`（V8 中 `const` 声明的 completion value 为空）。建议用 IIFE 包裹：
```bash
obscura fetch https://example.com --eval "(function(){ return document.title; })()"
```bash
`--eval` 可以单独使用，也可以与 `--dump` 组合——先执行 eval，让异步操作完成，再读取页面内容。
## 等待策略
SPA 页面需要等待 JavaScript 执行完成后才能读取内容。`--wait-until` 控制等待条件：
```bash
# 等待 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
```bash
`--wait` 参数在等待条件满足后再额外停留一段时间，让异步定时器完成：
```bash
obscura fetch https://example.16yun.cn --wait 10
```bash
## --selector 限定区域
用 CSS 选择器限定输出范围，跳过导航、侧栏和页脚：
```bash
obscura fetch https://example.com --selector "main" --dump markdown
obscura fetch https://example.com --selector "article.post" --dump text
```bash
与 `--dump markdown` 组合时特别有用——只提取正文内容。
## --timeout 与进程级硬截止
`--timeout` 控制导航超时时间（默认 30 秒）：
```bash
obscura fetch https://example.16yun.cn --timeout 60
```bash
Obscura 还有一个进程级硬截止线程，在 `timeout + wait + 10` 秒后强制退出进程。这是最后的兜底——V8 watchdog 无法终止已经进入 Rust op 的同步调用，硬截止从操作系统层面保证一个坏页面不会挂死 Worker。
## obscura scrape：并发抓取
`scrape` 命令用 Worker 进程并发抓取多个 URL：
```bash
obscura scrape url1 url2 url3 --concurrency 25 --format json
```bash
参数说明：
- `--concurrency`：并发 Worker 数（默认 10）
- `--format`：输出格式，`json` 或 `text`
- `--timeout`：每个 Worker 的超时时间（默认 60 秒）
- `--eval`：每个页面执行的 JS
- `--quiet`：静默模式，抑制进度输出
从 stdin 读取 URL 列表：
```bash
cat urls.txt | obscura scrape --concurrency 20 --format json -
```bash
要求 `obscura-worker` 与 `obscura` 在同一目录下。
## 输出与管道集成
`--output`（或 `-o`）参数将结果写入文件：
```bash
obscura fetch https://example.com --dump markdown --output page.md
obscura fetch https://example.com --eval "document.title" -o title.txt
```bash
`--quiet` 抑制横幅和日志，使输出适合脚本化：
```bash
obscura fetch https://example.com --dump text --quiet | wc -w
```bash
结合标准的 Unix 管道：
```bash
obscura fetch https://example.com --dump links --quiet | grep 'blog' | head -10
```bash
## 全局参数
以下是适用于所有子命令的全局参数：
| 参数 | 作用 |
|------|------|
| `--proxy <URL>` | HTTP/SOCKS5 代理 |
| `--stealth` | 启用反检测模式 |
| `--user-agent <UA>` | 自定义 UA |
| `--allow-private-network` | 允许访问内网地址（默认禁止） |
| `--v8-flags <FLAGS>` | 传递 V8 参数 |
| `--verbose` | 详细日志 |
```bash
obscura --proxy socks5://127.0.0.1:1080 --stealth fetch https://example.com --dump markdown
```bash
## 完整示例：抓取 SPA 页面并保存 Markdown
这是一个端到端的实用示例：
```bash
# 设置代理和超时
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
```bash
## 环境变量调优
通过环境变量控制超时和资源：
```bash
export OBSCURA_NAV_TIMEOUT_MS=60000
export OBSCURA_FETCH_TIMEOUT_MS=15000
obscura fetch https://example.16yun.cn --dump text
```bash
完整的环境变量列表见官方文档。
## 总结
`obscura fetch` 和 `obscura scrape` 覆盖了从单页抓取到并发批量的全部需求。七种输出格式适配不同的下游处理场景，`--eval` 提供了无上限的灵活性，而等待策略和超时体系确保你能可靠地处理 SPA 和慢页面。需要企业代理方案？
我们可根据目标站点、并发规模与稳定性目标提供定制方案。