3 分钟跑通第一个脚本。先看核心 API，再复制代码运行，最后按场景选择进阶路线。
launch(headless=False, port=None, browser_path=None, user_dir=None, window_size=None)新手首选入口。一行启动 Firefox 并返回 page 对象，内部自动创建 FirefoxOptions。
| 参数 | 说明 |
|---|---|
| headless | True 无界面模式，False 有界面（调试推荐）。 |
| port | 调试端口，默认自动分配。 |
| browser_path | Firefox 可执行文件路径，不传则自动查找。 |
| user_dir | 用户数据目录，不传则使用临时目录。 |
page.get(url, wait='complete')导航到指定 URL。wait 参数控制等待策略。
| 参数 | 说明 |
|---|---|
| url | 目标页面地址。 |
| wait | 'complete'（默认，等 readyState）/ 'interactive' / 'none'。 |
page.ele(locator)查找单个元素，返回 FirefoxElement。支持 'tag:h1'、'css:#id'、'xpath://div' 等定位方式。
| 参数 | 说明 |
|---|---|
| locator | 定位器字符串，前缀决定匹配方式（tag:/css:/xpath:/text: 等）。 |
page.quit()关闭浏览器进程并清理单例缓存。
| API | 说明 |
|---|---|
| page.title | 当前页面标题（str） |
| page.url | 当前页面 URL（str） |
| page.html | 当前页面完整 HTML（str） |
| page.wait(seconds) | 等待指定秒数 |
| page.eles(locator) | 查找所有匹配元素，返回列表 |
| page.refresh() | 刷新当前页面 |
| page.back() / page.forward() | 浏览器前进/后退 |
| ele.text | 元素的文本内容 |
| ele.attr(name) | 获取元素属性值 |
| ele.click() / ele.click_self() | 点击元素 |
| ele.input(text, clear=False) | 向输入框输入文字 |
| attach(address) | 连接已启动的 Firefox 调试端口，不重新启动浏览器 |
| FirefoxOptions() | 显式配置对象，适合需要精细控制的场景 |
| FirefoxPage(opts) | 用配置对象创建页面 |
from ruyipage import launch
# 一行启动 Firefox
page = launch(headless=False)
try:
# 访问页面
page.get("https://example.com")
page.wait(1)
# 读取页面信息
print(f"标题: {page.title}")
print(f"URL: {page.url}")
# 定位元素并读取文本
h1 = page.ele("tag:h1")
print(f"H1: {h1.text}")
finally:
page.quit()from ruyipage import FirefoxPage, Keys
page = FirefoxPage()
try:
page.get("https://cn.bing.com/")
# 输入关键词并搜索
page.ele("#sb_form_q").input("小肩膀教育")
page.actions.press(Keys.ENTER).perform()
page.wait(3)
# 提取搜索结果
items = page.eles("css:#b_results > li.b_algo")
for i, item in enumerate(items[:5], 1):
title = item.ele("css:h2 a")
if title:
print(f"{i}. {title.text}")
print(f" {title.attr('href')}")
finally:
page.quit()from ruyipage import FirefoxPage, FirefoxOptions
opts = FirefoxOptions()
opts.set_browser_path(r"C:\Firefox\firefox.exe") # 指纹浏览器路径
opts.set_fpfile(r"C:\Firefox\profile1.txt") # 指纹配置文件
page = FirefoxPage(opts)
try:
# 叠加地区伪装
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)
finally:
page.quit()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}")
# 接管后正常操作，不会关闭浏览器
page.get("https://example.com")继续看：页面对象 → 元素定位 → 等待机制 → 动作链。
继续看：请求拦截 → 拦截响应 → 网络事件 → Data Collector。
继续看：指纹浏览器接入 → 代理与认证 → Emulation → 高风控场景。
配合 ruyipage-skill 使用：https://github.com/LoseNine/ruyipage-skill
最短可运行的 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()
覆盖最基础的页面访问、前进后退和保存 HTML/PDF。
源码文件：app/content/ruyipage_examples/01_basic_navigation.py · 仓库：01_basic_navigation.py
# =============================
# RuyiPage 示例注释版
# 标题: 基础导航与页面保存
# 说明: 覆盖最基础的页面访问、前进后退和保存 HTML/PDF。
# 你会学到:
# 1. 打开本地文件页面和外部页面
# 2. 读取标题、URL 和 HTML 源码
# 3. 执行前进、后退和刷新
# 4. 保存 HTML 与 PDF
# 相关 API: FirefoxPage, FirefoxOptions, page.get, page.title, page.url, page.html, page.back, page.forward
# =============================
# -*- coding: utf-8 -*-
"""
示例1: 基础导航和页面操作
测试功能：
- 创建浏览器实例
- 页面导航
- 获取标题、URL
- 前进、后退、刷新
- 页面保存
"""
import os
import sys
import io
# 设置控制台输出编码为UTF-8（Windows兼容）
if sys.platform == 'win32':
sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')
sys.stderr = io.TextIOWrapper(sys.stderr.buffer, encoding='utf-8')
sys.path.insert(0, os.path.join(os.path.dirname(__file__), '..'))
from ruyipage import FirefoxPage, FirefoxOptions
def test_basic_navigation():
"""测试基础导航功能"""
print("=" * 60)
print("测试1: 基础导航和页面操作")
print("=" * 60)
# 创建浏览器实例
opts = FirefoxOptions()
opts.headless(False) # 显示浏览器窗口
page = FirefoxPage(opts)
try:
# 1. 导航到测试页面
test_page = os.path.join(os.path.dirname(__file__), 'test_pages', 'test_page.html')
test_url = 'file:///' + os.path.abspath(test_page).replace('\\', '/')
print(f"\n1. 导航到测试页面: {test_url}")
page.get(test_url)
print(f" ✓ 页面加载成功")
# 2. 获取页面信息
print(f"\n2. 获取页面信息:")
print(f" 标题: {page.title}")
print(f" URL: {page.url}")
print(f" HTML长度: {len(page.html)} 字符")
# 3. 导航到其他页面
print(f"\n3. 导航到其他页面:")
page.get('https://www.example.com')
print(f" 当前标题: {page.title}")
print(f" 当前URL: {page.url}")
# 4. 后退
print(f"\n4. 后退到上一页:")
page.back()
page.wait(1)
print(f" 当前标题: {page.title}")
# 5. 前进
print(f"\n5. 前进到下一页:")
page.forward()
page.wait(1)
print(f" 当前标题: {page.title}")
# 6. 刷新页面
print(f"\n6. 刷新页面:")
page.refresh()
page.wait(1)
print(f" ✓ 页面已刷新")
# 7. 保存页面
print(f"\n7. 保存页面:")
save_dir = os.path.join(os.path.dirname(__file__), 'output')
os.makedirs(save_dir, exist_ok=True)
# 保存为HTML
html_path = page.save(path=save_dir, name='example_page', as_pdf=False)
print(f" HTML已保存: {html_path}")
# 保存为PDF
pdf_path = page.save(path=save_dir, name='example_page', as_pdf=True)
print(f" PDF已保存: {pdf_path}")
print("\n" + "=" * 60)
print("✓ 所有基础导航测试通过！")
print("=" * 60)
except Exception as e:
print(f"\n✗ 测试失败: {e}")
import traceback
traceback.print_exc()
finally:
# 关闭浏览器
page.wait(2)
page.quit()
if __name__ == '__main__':
test_basic_navigation()
最接近真实业务脚本的入门示例，展示如何从搜索框输入到结果列表提取。
源码文件：app/content/ruyipage_examples/quickstart_bing_search.py · 仓库：quickstart_bing_search.py
# =============================
# RuyiPage 示例注释版
# 标题: Bing 搜索并抓取前三页结果
# 说明: 最接近真实业务脚本的入门示例，展示如何从搜索框输入到结果列表提取。
# 你会学到:
# 1. 打开搜索引擎主页并定位输入框
# 2. 输入关键词并使用回车提交
# 3. 批量读取搜索结果列表
# 4. 在结果容器内二次定位标题、链接和摘要
# 5. 跨页面翻页抓取结果
# 相关 API: FirefoxOptions, FirefoxPage, page.get, page.ele, page.eles, page.actions.press, ele.attr, ele.text
# =============================
# -*- coding: utf-8 -*-
"""快速开始：Bing 搜索前 3 页。"""
from ruyipage import FirefoxOptions, FirefoxPage, Keys
opts = FirefoxOptions()
# 如果 Firefox 不在默认安装目录，可以取消注释并指定路径。
# opts.set_browser_path(r"D:\Firefox\firefox.exe")
# 如果你想复用登录状态、Cookie、扩展，可以取消注释并指定 userdir。
# opts.set_user_dir(r"D:\ruyipage_userdir")
page = FirefoxPage(opts)
try:
page.get("https://cn.bing.com/")
page.ele("#sb_form_q").input("小肩膀教育")
page.actions.press(Keys.ENTER).perform()
page.wait(3)
for page_no in range(1, 4):
print("=" * 80)
print(f"第 {page_no} 页")
print("=" * 80)
items = page.eles("css:#b_results > li.b_algo")
for i, item in enumerate(items, 1):
title_ele = item.ele("css:h2 a")
if not title_ele:
continue
title = " ".join((title_ele.text or "").split())
url = title_ele.attr("href") or ""
desc_ele = item.ele("css:.b_caption p")
content = desc_ele.text if desc_ele else item.text
content = " ".join((content or "").split())
print(f"{i}. {title}")
print(f" URL: {url}")
print(f" 内容: {content}")
if page_no < 3:
next_btn = page.ele("css:a.sb_pagN")
if not next_btn:
break
next_btn.click_self()
page.wait(2)
finally:
page.quit()
面向高风控站点的快速开始示例，覆盖挑战处理、输入框识别和 Cookie 提取。
源码文件：app/content/ruyipage_examples/quickstart_cloudfare.py · 仓库：quickstart_cloudfare.py
# =============================
# RuyiPage 示例注释版
# 标题: Cloudflare / Copilot 快速开始
# 说明: 面向高风控站点的快速开始示例，覆盖挑战处理、输入框识别和 Cookie 提取。
# 你会学到:
# 1. 访问高风控站点并等待页面完成首屏加载
# 2. 自动尝试处理 Cloudflare 挑战
# 3. 定位输入框并发送问题
# 4. 提取 document.cookie 与完整 Cookie 信息
# 相关 API: FirefoxOptions, FirefoxPage, page.get, page.ele, page.handle_cloudflare_challenge, page.get_cookies
# =============================
# -*- coding: utf-8 -*-
"""快速开始：访问 Copilot，自动尝试通过 Cloudflare，并打印完整 Cookie。"""
from ruyipage import FirefoxOptions, FirefoxPage, Keys
QUESTION = "你好，今天天气怎么样？"
def find_input_box(page: FirefoxPage):
for _ in range(30):
box = page.ele("css:textarea")
if not box:
box = page.ele('css:[contenteditable="true"]')
if not box:
box = page.ele("css:.input-area")
if box:
return box
page.wait(1)
return None
def print_full_cookies(page: FirefoxPage) -> None:
print("\n" + "=" * 60)
print("Cloudflare / 页面 Cookie")
print("=" * 60)
raw_cookie = page.run_js("return document.cookie") or ""
print(f"document.cookie: {raw_cookie}")
cookies = page.get_cookies(all_info=True)
print(f"Cookie 数量: {len(cookies)}")
for i, cookie in enumerate(cookies, 1):
print(f"[{i}] name={cookie.name}")
print(f" value={cookie.value}")
print(f" domain={cookie.domain}")
print(f" path={cookie.path}")
print(f" httpOnly={cookie.http_only}")
print(f" secure={cookie.secure}")
print(f" sameSite={cookie.same_site}")
print(f" expiry={cookie.expiry}")
opts = FirefoxOptions()
# 如果 Firefox 不在默认安装目录，可以取消注释并指定路径。
# opts.set_browser_path(r"D:\Firefox\firefox.exe")
# 如果你想复用登录状态、Cookie、扩展，可以取消注释并指定 userdir。
# opts.set_user_dir(r"D:\ruyipage_userdir")
page = FirefoxPage(opts)
try:
print("=" * 60)
print("copilot.microsoft.com Cloudflare 测试")
print("=" * 60)
print("\n-> 访问 https://copilot.microsoft.com/ ...")
page.get("https://copilot.microsoft.com/", wait="none")
page.wait(5)
print("-> 等待输入框...")
input_box = find_input_box(page)
if input_box:
print("-> 找到输入框，开始输入问题...")
try:
input_box.click()
page.wait(0.8)
input_box.input(QUESTION, clear=True)
page.wait(0.8)
send_btn = page.ele('css:button[aria-label*="Send"]')
if not send_btn:
send_btn = page.ele('css:button[type="submit"]')
if send_btn:
print("-> 点击发送按钮...")
send_btn.click()
else:
print("-> 按 Enter 发送...")
page.actions.press(Keys.ENTER).perform()
print("-> 已发送问题，等待 Cloudflare 触发...")
page.wait(15)
except Exception as e:
print(f"-> 发送失败: {e}")
page.wait(5)
else:
print("-> 未找到输入框，直接等待 Cloudflare...")
page.wait(5)
print("\n-> 开始自动处理 Cloudflare...")
passed = page.handle_cloudflare_challenge(timeout=120, check_interval=2)
print("\n" + "=" * 60)
if passed:
print("✅ 成功通过 Cloudflare！")
print_full_cookies(page)
else:
print("❌ 超时未通过")
print("\n[+] 保持浏览器打开 500 秒...")
page.wait(500)
finally:
page.quit()
展示 Firefox 私密浏览模式的两种启动方式，以及它与临时 profile 的区别。
演示如何把 Firefox 指纹浏览器、指纹文件、地理位置、语言和请求头一起接入 RuyiPage。
适合 Firefox、ADS、FlowerBrowser 等已打开实例的自动探测接管场景。