RuyiPage 有四种启动方式，适合不同场景。选对入口是第一步，后面的元素、网络、高风控文档才容易对上实际需求。
launch(headless=False, port=None, browser_path=None, user_dir=None, window_size=None, private=False)新手首选。一行代码启动 Firefox 并返回 page 对象，内部自动创建 FirefoxOptions。
| 参数 | 说明 |
|---|---|
| headless | True 无界面 / False 有界面（调试推荐）。 |
| port | 调试端口，默认自动分配。 |
| browser_path | Firefox 路径，不传则自动查找。 |
| user_dir | 用户数据目录，不传则临时目录。 |
| private | True 开启隐私模式。 |
FirefoxPage(options=None)完整配置入口。先创建 FirefoxOptions 设置所有参数，再传入 FirefoxPage 启动。
| 参数 | 说明 |
|---|---|
| options | FirefoxOptions 实例，不传则使用默认配置。 |
attach(address='127.0.0.1:9222')连接已启动的 Firefox 调试端口，不新开浏览器。适合端口固定的场景。
| 参数 | 说明 |
|---|---|
| address | 调试地址，格式 host:port。 |
auto_attach_exist_browser_by_process(timeout=0.2, max_workers=16, latest_tab=True)自动扫描本机 Firefox 进程，找到调试端口并接管。端口不固定时的最佳选择。
| 参数 | 说明 |
|---|---|
| timeout | 每个端口的连接超时（秒）。 |
| max_workers | 并行扫描线程数。 |
| latest_tab | True 自动切换到最新标签页。 |
opts.set_browser_path(path)指定 Firefox 可执行文件路径。使用指纹浏览器时必须设置。
| 参数 | 说明 |
|---|---|
| path | Firefox 可执行文件的绝对路径。 |
opts.set_user_dir(path)指定用户数据目录（profile），复用登录态和 Cookie。
| 参数 | 说明 |
|---|---|
| path | 目录路径，会自动创建。 |
opts.set_fpfile(path)加载指纹配置文件，含代理认证、浏览器指纹等底层配置。
| 参数 | 说明 |
|---|---|
| path | fpfile 文件路径。 |
opts.set_proxy(proxy)设置 HTTP 代理地址。
| 参数 | 说明 |
|---|---|
| proxy | 代理地址，格式 http://host:port。 |
opts.headless(True)开启无界面模式。
| 参数 | 说明 |
|---|---|
| enable | True 无界面 / False 有界面。 |
opts.private_mode(True)开启隐私浏览模式。
| 参数 | 说明 |
|---|---|
| enable | True 开启。 |
| 方式 | 适合场景 | 需要手动启动浏览器 | 配置灵活度 |
|---|---|---|---|
| launch() | 第一次学习、快速测试 | 否，自动启动 | 低（常用参数直接传） |
| FirefoxOptions + FirefoxPage | 指纹浏览器、代理、fpfile | 否，自动启动 | 高（所有配置都可控） |
| attach(address) | 端口固定的调试场景 | 是 | 无（只连接） |
| auto_attach_exist_browser_by_process() | 端口不固定、指纹浏览器已打开 | 是 | 无（自动扫描） |
from ruyipage import launch
# 一行启动，最少参数
page = launch(headless=False)
page.get("https://example.com")
print(page.title)
page.quit()page = launch(
headless=False,
browser_path=r"C:\Firefox\firefox.exe", # 指定路径
user_dir=r"D:\my_profile", # 复用登录态
private=True, # 隐私模式
)
page.get("https://example.com")
page.quit()from ruyipage import FirefoxOptions, FirefoxPage
opts = FirefoxOptions()
opts.set_browser_path(r"C:\Firefox\firefox.exe")
opts.set_fpfile(r"C:\Firefox\profile1.txt")
opts.set_proxy("http://proxy-jp.example.com:8080")
opts.headless(False)
page = FirefoxPage(opts)
# 启动后叠加仿真
page.emulation.set_geolocation(35.6762, 139.6503)
page.emulation.set_timezone("Asia/Tokyo")
page.emulation.set_locale(["ja-JP", "ja"])
page.network.set_extra_headers({"Accept-Language": "ja-JP,ja;q=0.9"})
page.get("https://www.browserscan.net/zh")
page.wait(5)
page.quit()# 先手动启动 Firefox：
# firefox.exe --remote-debugging-port=9222
from ruyipage import attach
page = attach("127.0.0.1:9222")
print(f"标题: {page.title}")
print(f"URL: {page.url}")
# 接管后正常操作
page.get("https://example.com")from ruyipage import auto_attach_exist_browser_by_process
# 不需要知道端口号，自动扫描所有 Firefox 进程
page = auto_attach_exist_browser_by_process(
timeout=0.2, # 每个端口的超时
max_workers=16, # 并行扫描线程数
latest_tab=True, # 切到最新标签页
)
print(f"已接管: {page.browser.address}")
print(f"当前页: {page.title}")
print(f"标签数: {page.tabs_count}")
# 列出所有标签页
for i, tab_id in enumerate(page.tab_ids, 1):
tab = page.get_tab(i)
print(f" [{i}] {tab.title}")最短可运行的 hello-world 级别示例，适合验证环境和建立第一层心智模型。
源码文件：app/content/ruyipage_examples/01_quickstart.py · 仓库：01_quickstart.py
# =============================
# RuyiPage 示例注释版
# 标题: 一步上手：最少代码完成访问与读取
# 说明: 最短可运行的 hello-world 级别示例，适合验证环境和建立第一层心智模型。
# 你会学到:
# 1. 用 launch() 启动 Firefox
# 2. 访问网页并等待页面稳定
# 3. 读取标题和 H1 文本
# 4. 演示最短退出流程
# 相关 API: launch, page.get, page.wait, page.title, page.ele, ele.text, page.quit
# =============================
# -*- coding: utf-8 -*-
"""
示例01: 一步上手
面向新手：最少代码完成一次页面访问与元素交互。
"""
import io
import sys
if sys.platform == "win32":
sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding="utf-8")
sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding="utf-8")
from ruyipage import launch
def quickstart_demo():
print("=" * 60)
print("示例01: 一步上手")
print("=" * 60)
page = launch(headless=False)
try:
page.get("https://example.com")
page.wait(1)
print(f"标题: {page.title}")
h1 = page.ele("tag:h1")
print(f"H1文本: {h1.text}")
print("\n✓ 快速上手完成")
finally:
page.wait(1)
page.quit()
if __name__ == "__main__":
quickstart_demo()
展示 Firefox 私密浏览模式的两种启动方式，以及它与临时 profile 的区别。
演示如何把 Firefox 指纹浏览器、指纹文件、地理位置、语言和请求头一起接入 RuyiPage。
适合 Firefox、ADS、FlowerBrowser 等已打开实例的自动探测接管场景。