obscura

Obscura

将 Obscura 用作轻量、具备隐身能力的 Rust 无头浏览器以进行自动化。它内嵌 V8，掌控 DOM 与渲染管线，并提供 Chrome DevTools Protocol 工作流，无需启动 Chromium。将渲染与隐身视为一等的、互为补充的能力。

构建变体

官方发布的归档文件和 Docker 镜像包含渲染功能。若从源代码检出，请使用 render 特性以发布模式构建：

CARGO_INCREMENTAL=0 CARGO_BUILD_JOBS=2 cargo build --release -p obscura-cli --bins --features render

若需同时启用渲染与隐身功能，以获得 wreq/BoringSSL 传输、浏览器身份保护和追踪器拦截，请这样构建：

CARGO_INCREMENTAL=0 CARGO_BUILD_JOBS=2 cargo build --release -p obscura-cli --bins --features render,stealth

若只需要 DOM、提取或 CDP 自动化，可不带渲染功能进行构建：

CARGO_INCREMENTAL=0 CARGO_BUILD_JOBS=2 cargo build --release -p obscura-cli --bins --no-default-features
CARGO_INCREMENTAL=0 CARGO_BUILD_JOBS=2 cargo build --release -p obscura-cli --bins --no-default-features --features stealth

从源代码工作时，下文命令中请使用 ./target/release/obscura。

使用隐身功能

隐身构建保留完整的渲染、截图、屏幕流、PDF、CDP 和 MCP 功能。它在 TLS、HTTP 请求头、User-Agent、navigator 和 WebGL 等层面提供一致的浏览器指纹；屏蔽 navigator.webdriver；掩盖被修补的原生函数；并拦截内置的追踪器域名列表。

使用全局 --stealth 标志在运行时启用隐身功能。它适用于 fetch、serve、scrape 和 mcp，可以放在子命令之前或之后：

obscura --stealth fetch https://example.com --screenshot page.png
obscura serve --stealth --port 9222

运行时标志需要使用 render,stealth 构建，才能启用 wreq/BoringSSL 传输。

获取、执行与捕获

obscura fetch https://example.com --dump text
obscura fetch https://example.com --eval "document.title"
obscura fetch https://example.com --screenshot page.png
obscura fetch https://example.com \
  --eval "window.scrollTo(0, document.documentElement.scrollHeight)" \
  --screenshot bottom.png

CLI 截图功能会写出 PNG，且只接受一个 URL。省略 --wait 时，将使用自适应等待，上限为五秒。显式指定 --wait N 时，则为 N 秒的固定延迟。--timeout 同样以秒为单位，单独限制导航时长。

若要绕过 DOM 和 JavaScript 处理，获取二进制或原始 HTTP 响应，请使用 --dump original。若需处理大量 URL，且所需输出不要求每个 URL 各生成一张截图，请使用 scrape。

访问本地 http://127.0.0.1:N 需要全局标志 --allow-private-network，它会解除对回环地址、RFC1918 和链路本地地址的拦截；否则获取会失败，并报错 Access to private/internal IP address 127.0.0.1 is not allowed。

驱动 CDP

启动服务：

obscura serve --port 9222

使用 puppeteer-core 连接 Puppeteer，或使用 chromium.connectOverCDP 连接 Playwright。标准的 page.screenshot() 支持视口截图和整页截图；page.pdf() 生成基于光栅的打印输出。当用户需要截取页面下方部分时，请在视口截图前通过页面 JavaScript 滚动页面。

对于 Page.captureScreenshot、Page.startScreencast 和 Page.printToPDF，请使用原始 CDP。屏幕流客户端必须使用 Page.screencastFrameAck 确认每一个 Page.screencastFrame。帧由页面活动驱动，这不是固定帧率的桌面捕获。

PDF 输出支持纸张尺寸、页边距、横向、缩放、背景以及页面范围。目前它不提供可选择的文本、带标签的 PDF、大纲、页眉/页脚，或完整的 CSS 分页媒体行为。

驱动 MCP

使用 obscura mcp 启动 stdio 模式，或使用 obscura mcp --http --port 3000 启动 HTTP 模式。先导航，再检查或与当前页面交互。在导航、点击、滚动或框架重新渲染之后，请刷新快照或可交互元素列表，因为元素引用可能已经变化。

启用渲染的 MCP 构建会将 browser_screenshot 作为 MCP PNG 图像提供，并将 browser_pdf 作为嵌入式 PDF 资源提供。MCP 不会推送屏幕流帧；若需要该工作流，请选择 CDP。

验证视觉行为

先使用确定性的测试夹具隔离待测行为。然后在初始位置和滚动后的位置，对一组广泛的真实站点进行测试。进行引擎对比时，需保持视口、设备缩放比例、User Agent、网络输入、等待稳定策略、滚动、动画时间以及截取边界完全一致。

在解读差异之前，先确认两个引擎都已成功完成导航，并生成了非空白图像。像素指标应视为回归预警信号，而非最终结论。检查资源加载完成情况、盒模型几何、换行、结构边缘、裁剪，以及固定定位和粘性定位的表现；对于确认的真实问题，将其还原为测试夹具。不要引入针对特定主机名的渲染逻辑。

准确设定预期

Obscura 支持许多常见的布局与绘制路径，但它并非内置的 Chrome 构建版本。冷门 CSS、Service Worker、部分 Web API、原生媒体、GPU 或合成器效果、PDF 结构以及平台字体光栅化等方面，可能与 Chromium 存在差异。编辑项目文档时，应保留其既有定位与已发布的基准测试结论。添加或更新性能或保真度测量数据时，请使用基准测试套件及相同的输入。