Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

Obscura

面向 AI 智能体与网页抓取的开源无头浏览器（headless browser）。
轻量、隐匿，基于 Rust 构建。

---

Obscura 是一款用 Rust 编写的无头浏览器引擎，专为网页抓取与 AI 智能体自动化而构建。它通过 V8 运行真实的 JavaScript，支持 Chrome DevTools Protocol（CDP），并可作为 headless Chrome 的无缝替代方案，与 Puppeteer 和 Playwright 配合使用。

为什么选择 Obscura 而非 headless Chrome？

为规模化自动化而设计，而非桌面浏览。

指标	Obscura	Headless Chrome
内存	30 MB	200+ MB
二进制体积	70 MB	300+ MB
反检测	内置	无
页面加载	85 ms	~500 ms
启动	即时	~2s
Puppeteer	是	是
Playwright	是	是

🎉 10,000 stars 与后续计划

我们正在开发托管版 Obscura Cloud，提供托管基础设施、住宅代理（residential proxies）和专属支持，面向不想自行运维引擎的用户。

开源引擎仍将保持 Apache-2.0 许可，功能完整。永不进行功能阉割。

加入候补名单 →
📅 预约演示 →

赞助商

Obscura 的发展得益于赞助商的支持，帮助我们保持开发的独立性。

想要赞助？请发送邮件至 hello@obscura.sh。

	🚀 Obscura × SX.org 正在将 Obscura 用于 AI 智能体、浏览器自动化或网页抓取？使用来自 SX.org 的稳定代理为你的工作流赋能。 🌍 覆盖 235 个国家的 1200 万+ IP 🏠 700 万+ 住宅 IP 📱 400 万+ 移动 IP 🏢 100 万+ 企业代理 🔁 轮换与会话保持（sticky sessions） 📍 灵活的地理定位配置 🌐 支持 HTTP、HTTPS 与 SOCKS5 ⚡ 连接成功率最高达 99.97% 🛟 7×24 支持 🎁 使用优惠码 Obscura3gb 可获得 免费 3GB 试用。 稳定代理。更少封禁。最可靠的 Obscura 自动化体验。
	🚀 Obscura × ProxyEmpire 正在将 Obscura 用于 AI 智能体、浏览器自动化或网页抓取？使用来自 ProxyEmpire 的可靠住宅与移动代理为其赋能。 🌍 覆盖 170+ 个国家的 3000 万+ 住宅 IP 📱 4G/5G 移动代理 🔄 轮换与会话保持（sticky sessions） 🎯 城市、地区与 ISP 定向 🔐 支持 HTTP、HTTPS 与 SOCKS5 🎁 使用优惠码 OBSCURA35 可享受 35% 循环折扣。 更优质的代理。更少封禁。更具扩展性的自动化。
	MangoProxy 在 200+ 个国家提供住宅、ISP、数据中心与移动代理。全球企业信赖其稳定连接、快速响应时间与可扩展的代理基础设施。 使用优惠码 OBSCURA 购买 Static ISP Proxies 可享 8% 折扣。
	9Proxy 提供住宅代理， 低至 $0.018/IP 或 $0.68/GB。覆盖 90+ 个国家的 2000 万+ IP。支持会话保持或轮换，可通过桌面或移动应用管理。
	NodeMaven — 市场上最可靠的代理服务商，提供最高质量的 IP。专为自动化、网页抓取、SEO 研究与社交媒体管理而构建。 99.9% 正常运行时间 会话保持最长可达 7 天 每个代理均支持 IP 过滤 无需 KYC 流量返现 — 最高可返还 10% 🎁 使用优惠码 OBSCURA35 购买 Mobile & Residential 可享 35% 折扣，或使用 OBSCURA40 购买 ISP（Static）代理可享 40% 折扣。
	Rapidproxy — 住宅代理平台，覆盖 200+ 个国家的 9000 万+ 真实 IP。支持轮换、地理定向与高并发，提升抓取成功率。立即开始免费试用！ 灵活定价，低至 $0.65/GB 流量永不过期 支持 HTTP / HTTPS / SOCKS5 协议 为规模化打造的高速、低延迟网络 🎁 使用折扣码 RAPID10 可享 10% 折扣。

安装

下载

从 Releases: 获取最新二进制文件。

# Linux x86_64
curl -LO https://github.com/h4ckf0r0day/obscura/releases/latest/download/obscura-x86_64-linux.tar.gz
tar xzf obscura-x86_64-linux.tar.gz
./obscura fetch https://example.com --eval "document.title"

# Linux ARM64 (aarch64)
curl -LO https://github.com/h4ckf0r0day/obscura/releases/latest/download/obscura-aarch64-linux.tar.gz
tar xzf obscura-aarch64-linux.tar.gz

# Arch Linux (AUR)
yay -S obscura-browser

# macOS Apple Silicon
curl -LO https://github.com/h4ckf0r0day/obscura/releases/latest/download/obscura-aarch64-macos.tar.gz
tar xzf obscura-aarch64-macos.tar.gz

# macOS Intel
curl -LO https://github.com/h4ckf0r0day/obscura/releases/latest/download/obscura-x86_64-macos.tar.gz
tar xzf obscura-x86_64-macos.tar.gz

# Windows
Download the `.zip` from the releases page and extract it manually.

无需 Chrome、Node.js 或任何依赖。发布包同时包含 obscura 和 obscura-worker；请将它们放在同一目录下，以便运行并行的 scrape 命令。

Linux 发布构建以 Ubuntu 22.04 为目标，因此下载的二进制文件在搭载 glibc 2.35+ 的常见 LTS 服务器上仍可正常使用。

Docker

docker run -d --name obscura -p 127.0.0.1:9222:9222 h4ckf0r0day/obscura

镜像位于 Docker Hub. 基于 distroless/cc 的多阶段构建，无 shell、无包管理器，压缩后约 57 MB。

从源码构建

git clone https://github.com/h4ckf0r0day/obscura.git
cd obscura
cargo build --release

# With stealth mode (anti-detection + tracker blocking)
cargo build --release --features stealth

需要 Rust 1.75+（rustup.rs). 首次构建约需 5 分钟（V8 从源码编译，之后会缓存）。

快速开始

获取页面

# Get the page title
obscura fetch https://example.com --eval "document.title"

# Extract all links
obscura fetch https://example.com --dump links

# Render JavaScript and dump HTML
obscura fetch https://news.ycombinator.com --dump html

# Write dump or eval output to a file
obscura fetch https://example.com --dump text --output page.txt

# Stream the raw response body verbatim (binary-safe; bypasses the JS/DOM layer).
# Use this for images, JSON, JS, CSS, or any non-HTML resource.
obscura fetch https://picsum.photos/200/300 --dump original > photo.jpg

# List every sub-resource URL the page would fetch (NDJSON; one record per asset)
obscura fetch https://example.com --dump assets

# Fetch through an HTTP or SOCKS proxy
obscura --proxy socks5://127.0.0.1:1080 fetch https://example.com --dump text

# Wait for dynamic content
obscura fetch https://example.com --wait-until networkidle0

# Bound navigation time for slow or broken pages
obscura fetch https://example.com --timeout 10

启动 CDP 服务器

obscura serve --port 9222

# With stealth mode (anti-detection + tracker blocking)
obscura serve --port 9222 --stealth

并行抓取

obscura scrape url1 url2 url3 ... \
  --concurrency 25 \
  --eval "document.querySelector('h1').textContent" \
  --format json

# Suppress scrape progress on stderr for script-friendly output
obscura scrape https://example.com --quiet --format json

# Scrape workers inherit the global proxy
obscura --proxy http://127.0.0.1:8080 scrape https://example.com https://news.ycombinator.com

Puppeteer / Playwright

Puppeteer

npm install puppeteer-core

import puppeteer from 'puppeteer-core';

const browser = await puppeteer.connect({
  browserWSEndpoint: 'ws://127.0.0.1:9222/devtools/browser',
});

const page = await browser.newPage();
await page.goto('https://news.ycombinator.com');

const stories = await page.evaluate(() =>
  Array.from(document.querySelectorAll('.titleline > a'))
    .map(a => ({ title: a.textContent, url: a.href }))
);
console.log(stories);

await browser.disconnect();

Playwright

npm install playwright-core

import { chromium } from 'playwright-core';

const browser = await chromium.connectOverCDP({
  endpointURL: 'ws://127.0.0.1:9222',
});

const page = await browser.newContext().then(ctx => ctx.newPage());
await page.goto('https://en.wikipedia.org/wiki/Web_scraping');
console.log(await page.title());

await browser.close();

表单提交与登录

await page.goto('https://quotes.toscrape.com/login');
await page.evaluate(() => {
  document.querySelector('#username').value = 'admin';
  document.querySelector('#password').value = 'admin';
  document.querySelector('form').submit();
});
// Obscura handles the POST, follows the 302 redirect, maintains cookies

基准测试

页面加载：

页面	Obscura	Chrome
静态 HTML	51 ms	~500 ms
JS + XHR + fetch	84 ms	~800 ms
动态脚本	78 ms	~700 ms

完整基准测试套件（WPT 一致性、障碍赛道、真实世界语料库，以及与 Chrome 的速度对比）位于独立仓库：https://github.com/h4ckf0r0day/obscura-benchmark

隐身模式

通过 --features stealth 启用。

反指纹

• 按会话随机化指纹（GPU、屏幕、canvas、音频、电池）
• 逼真的 navigator.userAgentData（Chrome 145，高熵值）
• 为派发事件提供 event.isTrusted = true
• 隐藏内部属性（Object.keys(window) 安全）
• 原生函数伪装（Function.prototype.toString() → [native code]）
• navigator.webdriver = undefined（与真实 Chrome 一致）

跟踪器拦截

• 拦截 3,520 个域名
• 阻止分析、广告、遥测和指纹脚本
• 彻底阻止跟踪器加载
• 使用 --stealth 时自动启用

CDP API

Obscura 实现了 Chrome DevTools Protocol（CDP），以兼容 Puppeteer/Playwright。

域	方法
Target	createTarget, closeTarget, attachToTarget, createBrowserContext, disposeBrowserContext
Page	navigate, getFrameTree, addScriptToEvaluateOnNewDocument, lifecycleEvents
Runtime	evaluate, callFunctionOn, getProperties, addBinding
DOM	getDocument, querySelector, querySelectorAll, getOuterHTML, resolveNode
Network	enable, setCookies, getCookies, setExtraHTTPHeaders, setUserAgentOverride
Fetch	enable, continueRequest, fulfillRequest, failRequest (live interception), takeResponseBodyAsStream
IO	read, close (stream a large response body in chunks)
Storage	getCookies, setCookies, deleteCookies
Input	dispatchMouseEvent, dispatchKeyEvent
LP	getMarkdown (DOM-to-Markdown conversion)

若要下载大型资源而无需一次性获取巨大的 Network.getResponseBody 数据块，可先调用 Fetch.takeResponseBodyAsStream，再用 IO.read / IO.close 分块读取。超过缓存上限（OBSCURA_NETWORK_BODY_BUFFER_BYTES，默认 2 MiB）的响应体不会被保留，因此若计划流式下载大文件，请提高该上限。

CLI 参考

调整 V8

Obscura 直接嵌入 V8。使用 --v8-flags 可将原始标志直接传递给 V8，语法与 Chromium 的 --js-flags 及 Node 的命令行标志相同。最常见用途是提高堆上限，以修复 JS 密集型页面上的 JavaScript heap out of memory：

obscura --v8-flags "--max-old-space-size=4096" fetch <url>

重型 SPA（脚本执行预算）

Obscura 对页面的脚本执行阶段设有限额，避免单个缓慢或卡住的页面拖垮 worker。默认预算为 30 秒；页面若更早完成会立即返回，因此该上限仅影响持续运行的页面。网络较慢时，非常重的 React/Vue/Angular SPA 可能需要更长时间完成启动并发出数据请求。可通过 OBSCURA_SCRIPT_DEADLINE_MS（毫秒）提高预算，并在 CDP 客户端中设置匹配的导航超时：

OBSCURA_SCRIPT_DEADLINE_MS=60000 obscura serve --port 9222

obscura serve

启动 CDP WebSocket 服务器。

Flag	Default	Description
--port	9222	WebSocket 端口
--proxy	—	HTTP/SOCKS5 代理 URL
--stealth	off	启用反检测 + 跟踪器拦截
--workers	1	并行 worker 进程数量
--obey-robots	off	遵守 robots.txt

obscura fetch <URL>

获取并渲染单个页面。

Flag	Default	Description
--dump	html	输出：html、text、links、markdown、assets（页面引用的每个子资源 URL 的 NDJSON），或 original（原始响应体）
--eval	—	要执行的 JavaScript 表达式
--wait-until	load	等待：load、domcontentloaded、networkidle0
--timeout	30	最大导航时间（秒）
--selector	—	等待 CSS 选择器
--stealth	off	反检测模式
--output	—	将 dump 或 eval 输出写入文件
--quiet	off	隐藏横幅
--proxy	—	继承的全局 HTTP/SOCKS5 代理 URL

obscura scrape <URL...>

使用 worker 进程并行抓取多个 URL。

Flag	Default	Description
--concurrency	10	并行 worker 数量
--eval	—	每个页面的 JS 表达式
--format	json	输出：json 或 text
--quiet	off	在 stderr 上隐藏抓取进度
--proxy	—	所有 worker 继承的全局 HTTP/SOCKS5 代理 URL

MCP (Model Context Protocol)

Obscura 内置 MCP 服务器，向 AI 智能体（Claude Desktop、Cursor 等）暴露浏览器自动化工具。

Start

stdio（默认）——适用于 Claude Desktop 及通过启动子进程连接的 MCP 客户端：

obscura mcp

HTTP——适用于通过网络连接的客户端：

obscura mcp --http --port 8080
# endpoint: http://127.0.0.1:8080/mcp

可选标志（两种传输方式均支持）：

Flag	Description
--proxy <URL>	HTTP/SOCKS5 代理
--user-agent <UA>	自定义 User-Agent 字符串
--stealth	启用反检测模式

Claude Desktop config

{
  "mcpServers": {
    "obscura": {
      "command": "obscura",
      "args": ["mcp"]
    }
  }
}

Tools

Tool	Description
browser_navigate	导航至 URL（url，可选 waitUntil：load / domcontentloaded / networkidle0）
browser_snapshot	返回当前页面的 URL、标题和正文文本
browser_click	通过 CSS 选择器点击元素
browser_fill	设置输入值（触发 input + change 事件）
browser_type	向输入框追加文本
browser_press_key	派发键盘事件（key，可选 selector）
browser_select_option	Select an <option> by value or text
browser_evaluate	执行 JavaScript 表达式并返回结果
browser_wait_for	等待 CSS 选择器出现（selector，可选 timeout，单位为秒）
browser_network_requests	列出当前页面发出的网络请求
browser_console_messages	返回页面记录的 console 消息
browser_close	关闭页面并重置浏览器状态

Integrations

• Hermes agent plugin: run Hermes agent browser tasks on Obscura. 该插件为每个会话启动 obscura serve（或连接到已在运行的服务器），并通过 CDP 驱动，可选使用 --stealth。

License

Apache 2.0

---