cutetailbud/ff-ruyijs

选用指南

AI 根据 README 整理 · 2026/10/29 10:01:12

适用场景

适用于网页抓取、JS 逆向工程、数据收集以及需要绕过验证码或反爬挑战的场景，例如处理 Akamai、DataDome 等验证系统。

查看 README 依据

- **Truly headless.** No window, no layout, no renderer. A pure JavaScript + Web API environment that starts fast and stays light. - **Isolated and reproducible.** Each `Context` is its own process with a persistent JavaScript world and its own proxy, so sessions never leak into each other. - **Offline when you need it.** Serve scripts and responses yourself and replay a whole captured flow with no network. If you scrape, reverse-engineer web JavaScript, or collect data behind a challenge, it's for you. If a plain HTTP client already gets your pages, you don't need it.

from ruyijs import Context, JSError with Context(timeout=10) as context: try: context.eval("throw new TypeError('bad input')", filename="demo.js") except JSError as error: print(error.name, error.message) # TypeError bad input print(error.stack) ``` ## 🛡️ Verification systems it defeats Each example drives the site's own JavaScript to produce the parameters it demands, then completes the flow end to end. All ship runnable in the package: `python -m ruyijs.examples <name>`. | System | Category | Example | | :-- | :-- | :-- |

目标用户

面向需要自动化处理网站 JavaScript 的研究人员和开发者，尤其是进行网页抓取、JS 逆向或数据采集的用户。

查看 README 依据

**[Install](#-installation)** &nbsp;·&nbsp; **[Features](#-features)** &nbsp;·&nbsp; **[Verification systems](#-verification-systems-it-defeats)** &nbsp;·&nbsp; **[Examples](#-examples)** &nbsp;·&nbsp; **[FAQ](#-faq--troubleshooting)** &nbsp;·&nbsp; **[Contact](#-contact)** &nbsp;·&nbsp; **[LinuxDO](https://linux.do/t/topic/3078486)** &nbsp;·&nbsp; **English** · [简体中文](README.zh-CN.md)

- **Truly headless.** No window, no layout, no renderer. A pure JavaScript + Web API environment that starts fast and stays light. - **Isolated and reproducible.** Each `Context` is its own process with a persistent JavaScript world and its own proxy, so sessions never leak into each other. - **Offline when you need it.** Serve scripts and responses yourself and replay a whole captured flow with no network. If you scrape, reverse-engineer web JavaScript, or collect data behind a challenge, it's for you. If a plain HTTP client already gets your pages, you don't need it.

使用方式

通过 Python API 使用，可创建 Context 实例，调用 eval、load_page、navigate 等方法执行 JS 和加载页面，支持配置代理和时钟。

查看 README 依据

print(ruyijs.__version__) # 0.1.6 ``` ## 🚀 Quick start **1 · Open a context and run JavaScript.** Variables and functions persist across `eval` calls within the same context. ```python from ruyijs import Context with Context() as context: context.eval("let count = 40") print(context.eval("count += 2")) # 42 print(context.eval("navigator.userAgent")) ``` **3 · Point it at a real target.** Configure the environment, load the page, and let the site's own JavaScript mint whatever token it demands. ```python with Context(proxy="http://127.0.0.1:7890") as context:

context.configure_fingerprint({ "navigator": {"language": "zh-CN", "hardwareConcurrency": 8}, "locale": {"timezone": "Asia/Shanghai"}, }) context.load_page("https://target.example/", html) token = context.eval("window.__sign(payload)") # run the page's signer print(token) ``` ## 🏗️ How it fits together ``` Python ──► ruyiJS Context (isolated process) ──► Target site ├─ SpiderMonkey — Firefox 159 JS engine ├─ 38 browser contexts — DOM · Canvas · Workers · iframes · …

Execute scripts in a persistent context, load real HTML with iframes and classic scripts, and query the resulting DOM. References to live JS objects come back as `JSObject` / `JSFunction` you can call from Python. | Capability | How | | :-- | :-- | | Execute JS, keep state | `context.eval(src)` — variables and functions persist | | Get a callable back | `context.eval(src, to_py=False)` → `JSFunction` | | Load a page | `context.load_page(url, html)` — relative URLs resolve against `url` | | Top-level navigation | `context.navigate(url)` — no Referer, `Sec-Fetch-Site: none` |

部署要求

需要 Windows x64 和 Python 3.10 或更高版本，无需额外下载浏览器，wheel 包含运行时。

查看 README 依据

Runs on **Windows x64** with **Python 3.10+** (verified on Python 3.14). The wheel bundles the pinned native runtime, so there's nothing else to download. ## 📦 Installation ```sh python -m pip install ruyijs ``` **Requirements:** Python 3.10+ on Windows x64 (64-bit). Verified on Python 3.10 – 3.14. The wheel ships the SHA256-pinned SpiderMonkey + Necko runtime (~42 MB). Local scripts run offline right after install — no browser download, no external dependencies. To upgrade: ```sh python -m pip install --upgrade ruyijs ``` To verify the installation: ```python import ruyijs

Python 3.10 and above on Windows x64 (64-bit). Tested up to Python 3.14. </details> <details> <summary><b>Does it work on macOS or Linux?</b></summary> Not yet — currently Windows x64 only. Cross-platform support is planned. </details> <details> <summary><b>Do I need to download a browser?</b></summary> No. The wheel bundles the pinned SpiderMonkey + Necko runtime. Everything works offline right after `pip install ruyijs`. </details> <details> <summary><b>Context hangs or doesn't respond</b></summary>

已知限制

目前仅支持 Windows x64，无浏览器窗口，无完整页面布局和渲染；仅用于研究目的，禁止非法使用，商业使用需授权。

查看 README 依据

## 📏 Scope & limitations ruyiJS provides JavaScript execution and a broad Web API environment on **Windows x64**. It has **no browser window and no full page layout or rendering** — it is a tool for automation, analysis, and research. Use it in compliance with the terms of service of any site you interact with and with applicable law. **Related:** [**ruyiHttp**](https://gitee.com/losenine888/ruyiHttp) — a Requests-style Python HTTP library built on Firefox's native networking components. ## ❓ FAQ / Troubleshooting <details> <summary><b>What Python versions are supported?</b></summary>

> **⚠️ Disclaimer:** This project is for researching next-generation AI browsers. Any form of brute-force reverse engineering is strictly rejected. The source code is fully open-source. Unauthorized commercial use is prohibited. <br> <picture> <source media="(prefers-color-scheme: dark)" srcset="assets/architecture-dark.svg"> <img src="assets/architecture.svg" width="880" alt="ruyiJS architecture: your Python code drives a ruyiJS Context — an isolated process holding the SpiderMonkey JS engine, 38 browser contexts, and the Necko network stack — which talks to the target site.">

> The group QR refreshes periodically; if it has expired, add the author on WeChat (如意) for an invite. ## 📄 License Licensed under the **[ff-ruyijs Source Available License v1.0](LICENSE)**. - ✅ Free for personal learning, research, and non-commercial use - ✅ Modifications **must be open-sourced** when distributed - ❌ Commercial use **requires written authorization** from the author To request a commercial license, contact via WeChat (ID: **如意**) or open an issue on [GitHub](https://github.com/cutetailbud/ff-ruyijs). See [`NOTICE`](NOTICE) for third-party attributions.