obscura:基于 Rust 的无头浏览器引擎项目

Obscura

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

原生渲染已经到来，无需 Chromium。🎉

使用 Obscura 直接截图、录制实时页面并导出 PDF。

---

Obscura 是一款使用 Rust 编写的无头浏览器引擎，专为网页抓取与 AI 智能体自动化而构建。它通过 V8 执行真实 JavaScript，支持 Chrome DevTools Protocol，可直接替代 Puppeteer 与 Playwright 中的无头 Chrome。

相比无头 Chrome，为什么选择 Obscura？

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

Obscura 启发了 Cloudflare Kitesurf 的第一个原型 在开发其全新的 Agent 优先浏览器时，Cloudflare 先将 Obscura 移植到了 Workers。 阅读 Cloudflare 的工程故事 →

Obscura Cloud

我们正在打造 Obscura Cloud 托管版本，提供托管基础设施、住宅代理和专属支持。适合希望使用引擎而无需自行运维的用户。

开源引擎将始终保持 Apache-2.0 许可，并完整提供全部功能。永不进行功能限制。

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

赞助商

Obscura 获得多家组织支持，它们帮助我们构建独立的开源浏览器基础设施。

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

	NodeMaven：面向网页抓取与自动化的最高效代理服务商，提供市场上质量最高的 IP。 为什么选择 NodeMaven？ ZIP 码定向 99.9% 在线率 IP 筛选：所有代理的欺诈评分均低于 97% 无需 KYC 独家免费工具：代理带宽检测、Meta 标签检测、IP 查询等！ 🎁 Obscura 用户专属优惠码： OBSCURA35 - 移动代理与住宅代理享 85 折 OBSCURA40 - ISP（静态）代理享 6 折
	🚀 Obscura × ProxyEmpire 正在使用 Obscura 构建 AI 智能体、浏览器自动化或网页抓取？使用来自 ProxyEmpire 的可靠住宅代理和移动代理为其提供动力。 🌍 覆盖 170+ 个国家的 30M+ 住宅 IP 📱 4G/5G 移动代理 🔄 轮换 & 粘性会话 🎯 城市、地区 & ISP 定向 🔐 HTTP、HTTPS & SOCKS5 支持 🎁 使用优惠码 OBSCURA35 可享 85 折续费折扣。 更优质的代理，更少的拦截，更可扩展的自动化。
	NiuProxy 轮换住宅代理 — 特惠：10TB 低至 $0.35/GB | 1TB 低至 $0.50/GB。 🎁 使用优惠码 PAY2，充值享 9 折。

安装

下载

从 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

# NixOS
nix-env -iA nixpkgs.obscura

# 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 命令时，请将二者保留在同一目录。

归档后缀	渲染	隐身传输
无	支持	不支持
-stealth	支持	支持
-no-render	不支持	不支持
-no-render-stealth	不支持	支持

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

# Rendering
cargo build --release -p obscura-cli --bins --features render

# Rendering and stealth
cargo build --release -p obscura-cli --bins --features render,stealth

# No rendering
cargo build --release -p obscura-cli --bins --no-default-features

# No rendering, with stealth
cargo build --release -p obscura-cli --bins --no-default-features --features stealth

需要 Rust 1.75+（rustup.rs）。首次构建约需 5 分钟（V8 从源码编译，后续会缓存）。 stealth build 还会编译 BoringSSL 并生成 bindings，因此需要 CMake、Clang 以及 libclang/LLVM 开发库。在 Ubuntu/Debian 上：

sudo apt-get install build-essential cmake clang libclang-dev llvm-dev

渲染构建使用 rustls。渲染与隐身构建使用 wreq/BoringSSL，因此需要上述额外的构建工具。

快速开始

获取页面

# 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

# Capture the settled page as PNG
obscura fetch https://example.com --screenshot page.png

# The screenshot flag also has a short form
obscura fetch https://example.com -s page.png

### Testing against localhost / LAN dev servers

Obscura blocks fetches to private/internal IPs by default (SSRF protection).
To point it at a local dev server, pass `--allow-private-network` (or set
`OBSCURA_ALLOW_PRIVATE_NETWORK=1`):

```bash
obscura fetch http://127.0.0.1:3000 --allow-private-network --dump text

# Works on any subcommand, e.g. the CDP server for local Puppeteer/Playwright:
obscura serve --port 9222 --allow-private-network

请参阅 docs/Environment-variables.md 查看完整的 允许/拒绝规则（包括 DNS 解析时的检查）。

## Rendering

Official release archives and the Docker image include the rendering engine.
It provides CSS layout and paint, viewport and full-page screenshots,
scroll-aware fixed and sticky geometry, activity-driven CDP screencasting, and
raster PDF export without starting Chromium.

```javascript
await page.setViewport({ width: 1440, height: 1000 });
await page.goto('https://example.com', { waitUntil: 'load' });
await page.screenshot({ path: 'page.png', fullPage: true });
await page.pdf({ path: 'page.pdf', format: 'A4', printBackground: true });

当前实现覆盖了块级、行内、flex、grid、表格、浮动、定位、溢出、transform、文本、图像、SVG、canvas、背景、边框以及动画渲染路径。它仍是一个不断演进的独立引擎：长尾 CSS、部分 Web API、媒体播放、合成器效果以及平台字体光栅化可能与 Chromium 存在差异。现有的 Puppeteer、Playwright 以及 MCP 指南涵盖了各自的捕获 API 与限制。

启动 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 render,stealth 构建，然后在运行时通过全局 --stealth 参数启用隐身模式。隐身版本包含完整渲染引擎；启用隐身模式不会移除截图、屏幕录制、PDF、CDP 或 MCP 功能。

反指纹识别

• 按会话进行指纹随机化（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，以兼容 Puppeteer/Playwright。

域	方法
Target	createTarget, closeTarget, attachToTarget, createBrowserContext, disposeBrowserContext
Page	navigate, getFrameTree, lifecycleEvents, captureScreenshot, start/stopScreencast, printToPDF
Runtime	evaluate, callFunctionOn, getProperties, addBinding
DOM	getDocument, querySelector, querySelectorAll, getOuterHTML, resolveNode
Network	enable, setCookies, getCookies, setExtraHTTPHeaders, setUserAgentOverride
Fetch	enable, continueRequest, fulfillRequest, failRequest（实时拦截）, takeResponseBodyAsStream
IO	read, close（分块流式读取大型响应体）
Storage	getCookies, setCookies, deleteCookies
Input	dispatchMouseEvent, dispatchKeyEvent
LP	getMarkdown（DOM 到 Markdown 转换）

若不想通过一个巨大的 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 的命令行参数一致。最常见的用法是提高堆内存上限，以修复 JavaScript 密集型页面中出现的 JavaScript heap out of memory 问题：

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

重型 SPA（脚本执行预算）

Obscura 会限制页面的脚本执行阶段，避免某个缓慢或挂起的页面阻塞 worker。默认预算为 30s；提前完成的页面会立即返回，因此该上限只影响仍在运行的页面。在慢速网络下，非常庞大的 React/Vue/Angular SPA 可能需要更长时间完成启动，之后才会发出数据请求。可通过 OBSCURA_SCRIPT_DEADLINE_MS（毫秒）提高预算，并在 CDP 客户端中设置相应的导航超时：

OBSCURA_SCRIPT_DEADLINE_MS=60000 obscura serve --port 9222

用于增强已渲染页面的模块具有每个模块独立的 3 秒预算，因此单个非关键模块不会阻塞导航。对于合法的长时间运行模块（如 Vite HMR 客户端），可提高该预算：

OBSCURA_MODULE_BUDGET_MS=10000 obscura serve --port 9222

未挂载的 SPA 外壳已为其应用模块提供完整的 OBSCURA_SCRIPT_DEADLINE_MS 预算。OBSCURA_FETCH_TIMEOUT_MS 控制模块的网络请求，而非其执行时间。完整的超时模型见 环境变量。

obscura serve

启动 CDP WebSocket 服务器。

选项	默认值	说明
--port	9222	WebSocket 端口
--proxy	—	HTTP/SOCKS5 代理 URL
--stealth	off	启用反检测 + 跟踪器拦截
--workers	1	并行工作进程数量
--obey-robots	off	遵守 robots.txt

obscura fetch <URL>

抓取并渲染单个页面。

选项	默认值	说明
--dump	html	输出：html、text、links、markdown、assets（页面引用的所有子资源 URL，NDJSON 格式）或 original（原始响应体）
--eval	—	要执行的 JavaScript 表达式
--wait-until	load	等待：load、domcontentloaded、networkidle0
--timeout	30	最大导航时间（秒）
--wait	自适应，最长 5	加载后稳定；显式值为固定延迟（秒）
--selector	—	等待 CSS 选择器
-s, --screenshot	—	写入 PNG 截图（仅限单个 URL；已启用渲染的构建）
--stealth	off	反检测模式
--output	—	将 dump 或 eval 输出写入文件
--quiet	off	隐藏横幅
--proxy	—	继承全局 HTTP/SOCKS5 代理 URL

obscura scrape <URL...>

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

选项	默认值	说明
--concurrency	10	并行工作进程
--eval	—	每页执行的 JS 表达式
--format	json	输出：json 或 text
--quiet	off	抑制 stderr 上的抓取进度
--proxy	—	供所有工作进程继承的全局 HTTP/SOCKS5 代理 URL

MCP (Model Context Protocol)

Obscura 内置 MCP 服务器，可向 AI 代理提供浏览器自动化工具（Claude Desktop、Cursor 等）。

启动

stdio（默认） — 适用于会启动子进程的 Claude Desktop 和 MCP 客户端：

obscura mcp

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

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

可选参数（两种传输方式通用）：

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

Claude Desktop 配置

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

工具

工具	描述
browser_navigate	导航至指定 URL（url，可选 waitUntil：load / domcontentloaded / networkidle0）
browser_snapshot	返回当前页面的 URL、标题、可读正文文本以及元素引用
browser_screenshot	将当前页面作为 MCP PNG 图像返回（启用渲染的构建版本）
browser_pdf	将当前页面作为内嵌 PDF 资源返回（启用渲染的构建版本）
browser_click	通过当前快照引用或 CSS 选择器进行点击
browser_fill	通过引用或选择器设置输入值（触发 input + change）
browser_type	向输入框追加文本
browser_press_key	派发键盘事件（key，可选 selector）
browser_select_option	通过 value 或 text 选择 <option>
browser_evaluate	执行 JavaScript 表达式并返回结果
browser_wait_for	等待某个 CSS 选择器出现（selector，可选 timeout，单位为秒）
browser_network_requests	列出当前页面发出的网络请求
browser_console_messages	返回页面记录的控制台消息
browser_close	关闭页面并重置浏览器状态

MCP 服务器支持静态图像和 PDF 输出。若需使用流式 Page.startScreencast 协议，请使用 CDP。

集成

• Hermes 智能体插件：在 Obscura 上运行 Hermes 智能体浏览器任务。该插件会为每个会话启动 obscura serve（或连接一个已在运行的服务器），并通过 CDP 控制，可选使用 --stealth。

许可证

Apache 2.0

---