ruyiPage 反检测浏览器实战：Firefox 指纹内核与 fpfile 完全指南

前言#

用 Playwright / Selenium 直连做自动化，第一道墙从来不是验证码本身，而是**「你根本没被当成浏览器」**。

同样一个滑块、同样一次点击，真实用户通过，脚本被秒拒——差别不在结果，在过程。服务端看的是一整条证据链：navigator.webdriver 有没有暴露、WebGL 报的是哪块显卡、Canvas 渲染有没有噪声、时区跟出口 IP 对不对得上、鼠标是贝塞尔曲线还是瞬移。

ruyiPage（仓库 LoseNine/ruyipagedeke）是这条路上一个值得单独讲的方案：它不走 Chromium/Playwright 那条路，而是基于 firefox-fingerprintBrowser 定制内核，用一份声明式的 fpfile.txt 描述整套指纹，指纹在 C++ 原生 getter 层改写，而不是靠 JS 注入打补丁。

这个区别很关键：JS 注入的补丁可以被 Object.getOwnPropertyDescriptor 反查出来，原生 getter 层改写则不会留下可检测的包装痕迹。

本文只讲工具怎么用。文中域名、端口、密钥、路径全部为占位符。

一、安装#

1
pip install ruyipage
2

3
# 安装配套的 Firefox 内核（不是系统 Firefox，是定制内核）
4
python -m ruyipage install
5

6
# 查看内核装在哪了
7
python -m ruyipage path

内核默认落在：

1
Windows:  %LOCALAPPDATA%\ruyipage\browsers\<版本>\firefox\firefox.exe
2
Linux:    ~/.local/share/ruyipage/browsers/<版本>/firefox/firefox

1.1 浏览器路径的解析顺序#

不用手动找路径，resolve_firefox_path() 会按固定优先级探测：

1
1. 显式传入的路径              set_browser_path(r"...")
2
2. 环境变量                    RUYIPAGE_FIREFOX_EXECUTABLE_PATH
3
                              RUYIPAGE_BROWSER_PATH
4
3. ruyipage 托管内核            python -m ruyipage install 装的那份
5
4. 系统 Firefox 兜底            C:\Program Files\Mozilla Firefox\firefox.exe

生产环境建议显式指定第 1 项或第 2 项——第 3、4 项在升级、多版本并存时行为不确定。

极端情况下（比如注册机打包进 Electron 分发）可以自己 glob 探测，新版本优先：

1
import glob, os
2

3
def find_firefox():
4
    candidates = glob.glob(os.path.expandvars(
5
        r"%LOCALAPPDATA%\ruyipage\browsers\*\firefox\firefox.exe"))
6
    candidates += [
7
        os.path.expandvars(r"%ProgramFiles%\Mozilla Firefox\firefox.exe"),
8
        os.path.expandvars(r"%ProgramFiles(x86)%\Mozilla Firefox\firefox.exe"),
9
    ]
10
    for path in sorted(candidates, reverse=True):   # 新版本优先
11
        if os.path.exists(path):
12
            return path
13
    return None

二、快速开始#

2.1 最小可运行#

1
from ruyipage import FirefoxOptions, FirefoxPage
2

3
opts = FirefoxOptions()
4
opts.set_browser_path(find_firefox())
5

6
page = FirefoxPage(opts)
7
page.get("https://example.com")
8
print(page.title)
9
page.quit()

2.2 一键预设：quick_start#

参数多的时候用 quick_start() 一次配齐，省掉十几行链式调用：

1
opts = FirefoxOptions().set_port(9222).quick_start(
2
    browser_path=r"D:\FirefoxPortable\firefox.exe",
3
    user_dir=r"D:\my_firefox_userdir",
4
    proxy="socks5://127.0.0.1:1080",
5
    fpfile=r"D:\my_firefox_userdir\fpfile.txt",
6
    headless=False,
7
    private=False,
8
    human_algorithm="bezier",
9
    window_size=(1280, 800),
10
    xpath_picker=False,
11
    action_visual=False,
12
    trace=False,
13
    failure_snapshot=False,
14
    timeout_base=10,
15
    timeout_page_load=30,
16
    timeout_script=30,
17
)
18

19
page = FirefoxPage(opts)

参数	作用
`browser_path`	Firefox 可执行文件路径
`user_dir`	profile 目录，复用它就能复用登录态 / Cookie
`proxy`	`http://ip:port` 或 `socks5://ip:port`
`fpfile`	指纹配置文件路径
`private`	Firefox 原生私密模式（启动加 `-private`）
`headless`	无头开关
`human_algorithm`	拟人轨迹算法：`"bezier"` / `"windmouse"`
`xpath_picker`	页面里弹 XPath 选择浮窗，调试定位用
`action_visual`	鼠标行为可视化——看轨迹到底长什么样
`trace`	BiDi 命令 / 事件环形缓冲记录
`failure_snapshot`	失败时自动截图 + 存 DOM
`marionette`	Marionette 通道，默认 `True`
`allow_system_access`	是否允许访问特权上下文；`None` = 仅 Windows 提权会话自动开

marionette 这一项要留意：默认开启以兼容历史行为，但某些 Firefox 版本 / 指纹内核 / 机器环境带 --marionette 启动会直接闪退，表现为后续 BiDi 端口连不上。遇到「启动后立刻断开」先试 marionette=False。

allow_system_access 是三元值：None 表示「只在 Windows 提权会话中自动启用」，True/False 是显式覆盖。这一项存在的原因挺实际——提权环境下 Firefox 155 有连接问题，但又不能无条件放大 Remote Agent 权限，所以做成条件启用。

三、核心机制：fpfile.txt#

这是 ruyiPage 与 Chromium 系反检测工具最大的区别。整套指纹写在一个文本文件里，格式是 key:value（注意不是 =），UTF-8 + \n 行尾。

3.1 完整字段结构#

1
# ── 网络与地理自洽 ──
2
timezone:America/Denver
3
language:en-US
4
geolocation.enabled:true
5
geolocation.latitude:39.7392
6
geolocation.longitude:-104.9903
7
geolocation.accuracy:15000
8
geolocation.altitude:
9
geolocation.altitudeAccuracy:
10
geolocation.heading:
11
geolocation.speed:
12
geolocation.timestamp:now
13
geolocation.permission:granted
14

15
# ── 语音合成列表（检测「语音数组是否为空」的经典项）──
16
speech.voices.local:Microsoft David - English (United States)|Microsoft Zira - English (United States)
17
speech.voices.remote:Google US English
18
speech.voices.local.langs:en-US|en-US
19
speech.voices.remote.langs:en-US
20
speech.voices.default.name:Microsoft David - English (United States)
21
speech.voices.default.lang:en-US
22

23
# ── 硬件与 UA ──
24
font_system:windows
25
useragent:Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:155.0) Gecko/20100101 Firefox/155.0
26
hardwareConcurrency:24
27

28
# ── WebGL（必须成套，见 3.3）──
29
webgl.vendor:Mozilla
30
webgl.renderer:
31
webgl.version:WebGL 1.0
32
webgl.glsl_version:WebGL GLSL ES 1.0
33
webgl.unmasked_vendor:Google Inc. (NVIDIA)
34
webgl.unmasked_renderer:ANGLE (NVIDIA, NVIDIA GeForce RTX 4090 Direct3D11 vs_5_0 ps_5_0), or similar
35
webgl.max_texture_size:16384
36
webgl.max_cube_map_texture_size:16384
37
webgl.max_texture_image_units:16
38
webgl.max_vertex_attribs:16
39
webgl.aliased_point_size_max:1024
40
webgl.max_viewport_dim:32767
41

42
# ── Canvas / Audio 噪声（按种子生成，同种子同结果）──
43
canvas.mode:pixel
44
canvas.seed:17592186044416
45
canvas.strength:low
46
canvas.preserveAlpha:true
47
canvas.preserveWhitePoint:true
48
canvas.pngMetadata:false
49
audio.seed:8796093022208
50

51
# ── WebRTC 防泄漏（走代理时必写）──
52
webrtc.ice_proxy_only:true
53

54
# ── 代理认证（按协议选命名空间，见第七节）──
55
httpauth.host:gate.example.com
56
httpauth.port:1000
57
httpauth.username:user
58
httpauth.password:pass

3.2 `navigator.webdriver` 根本不用写#

这是最容易误解的一条：fpfile 里没有 webdriver 这个键。

内核在 C++ 原生 getter 层把 navigator.webdriver 硬编码成 false，写进 fpfile 也是 never-read 的死键，等于 no-op。所以别去翻「webdriver 该填什么」——它压根不吃这个配置。

3.3 WebGL 必须成套配置#

部分伪造比完全不伪造更危险。

假设你只改了 webgl.unmasked_renderer，报自己是 RTX 4090，却漏了 max_texture_size 之类的上限值——那么检测方拿到的画面是：一个自称 4090 的设备，纹理上限却是集显水平。这比老老实实报集显更可疑，因为它证明有人在说谎。

所以内核的字段设计是「一个显卡档案 1:1 映射」，而不是散装开关：

1
{
2
  "id": "win-rtx4090",
3
  "platform": "windows",
4
  "os_token": "Windows NT 10.0; Win64; x64",
5
  "font_system": "windows",
6
  "hardwareConcurrency": 24,
7
  "width": 2560,
8
  "height": 1440,
9
  "webgl": {
10
    "unmasked_vendor": "Google Inc. (NVIDIA)",
11
    "unmasked_renderer": "ANGLE (NVIDIA, NVIDIA GeForce RTX 4090 Direct3D11 vs_5_0 ps_5_0), or similar"
12
  }
13
}

配套的 webgl_common 段（全局共享，不随显卡变）包含完整的 WebGL 1.0 / 2.0 参数与扩展列表：

1
{
2
  "vendor": "Mozilla",
3
  "version": "WebGL 1.0",
4
  "glsl_version": "WebGL GLSL ES 1.0",
5
  "webgl2_version": "WebGL 2.0",
6
  "webgl2_glsl_version": "WebGL GLSL ES 3.00",
7
  "supported_extensions": "ANGLE_instanced_arrays,EXT_blend_minmax,EXT_color_buffer_half_float,..."
8
}

3.4 Canvas 用种子而不是随机#

1
canvas.mode:pixel
2
canvas.seed:17592186044416
3
canvas.strength:low

种子必须落在 [1, 2^64-1] 区间，写入前会校验：

1
def _validate_seed(name, value):
2
    if isinstance(value, bool) or not isinstance(value, int) or not (1 <= value < (1 << 64)):
3
        raise FingerprintError("{} must be an integer in [1, 2**64 - 1]".format(name))
4
    return value

为什么用种子而不是每次随机噪声：真实设备的 Canvas 渲染结果在同一台机器上是稳定的，跨会话一致。如果每次访问都返回不同的噪声，等于告诉服务端「我这个 Canvas 指纹每次都在变」——这在真实硬件上不可能发生，反而是异常信号。

同一种子 → 同一渲染结果，跨会话稳定，这才像一个真机。

3.5 WebRTC：最容易漏掉的一条#

1
webrtc.ice_proxy_only:true

不写这一行，STUN 会绕过代理去探测，srflx 候选直接把你的真实出口 IP 暴露给页面——前面所有代理配置一次归零。

有代理时这一项默认写 true，但如果你手工拼 fpfile，很容易忘。同一组还有四个可选的精确控制项：

1
local_webrtc_ipv4:10.0.0.5          # 主机 ICE 地址，精确白名单
2
local_webrtc_ipv6:
3
public_webrtc_ipv4:203.0.113.7      # srflx / prflx 地址
4
public_webrtc_ipv6:

默认全部省略，走原生 ICE + ice_proxy_only 钉住代理这条路就够了。

3.6 写入是原子的#

这一层实现在库内部，但值得知道为什么：

1
def _atomic_write_text(path, content):
2
    """tmp + os.replace + fsync"""
3
    parent = os.path.dirname(os.path.abspath(path)) or "."
4
    fd, tmp = tempfile.mkstemp(prefix=".fpfile.", suffix=".tmp", dir=parent)
5
    with os.fdopen(fd, "w", encoding="utf-8", newline="\n") as f:
6
        f.write(content)
7
        f.flush()
8
        try:
9
            os.fsync(f.fileno())
10
        except OSError:
11
            pass
12
    os.replace(tmp, path)

为什么必须原子：Firefox 启动时读 fpfile，如果读到写了一半的文件，指纹会静默降级成真机硬件——没有任何报错，只是整个反检测失效了。这是最难排查的一类故障，原子写从根上避免它。

四、智能指纹：smart_fingerprint#

手工填 fpfile 不现实。opts.smart_fingerprint() 把整条链路自动化：

1
opts = FirefoxOptions().set_port(9222)
2
opts.set_browser_path(r"C:/Program Files/Mozilla Firefox/firefox.exe")
3

4
ctx = opts.smart_fingerprint(
5
    proxy_host="proxy.example.com",
6
    proxy_port=8080,
7
    proxy_user="user",
8
    proxy_pwd="pass",
9
    require_country="US",
10
    logger=print,
11
)
12

13
page = FirefoxPage(opts)
14
ctx.apply_emulation(page)          # BiDi 层再盖一层保险

4.1 内部流水线#

1
1. 探测出口 IP 归属地 ── 10 个数据源依次回退
2
                          (geojs / ipapi / ipwho / ip-api / ipinfo / ...)
3
2. 校验国家码 ────────── require_country 不匹配 → CountryMismatchError
4
3. 采样硬件档案 ──────── 22 套 Windows 真机配置中随机取一
5
4. 生成 UA ──────────── Firefox 主版本号与实际二进制对齐
6
5. 生成种子 ──────────── Canvas / Audio 每会话独立
7
6. 写入 fpfile.txt ───── 严格字段顺序，diff 友好
8
7. 配置 FirefoxOptions ─ 代理 / userdir / fpfile / about:blank 启动页

4.2 第 3 步：22 套硬件档案#

覆盖主流独显与集显，全部是 Windows 真机配置：

1
NVIDIA:  win-rtx4090 / 4080 / 4070 / 4060 / 3070 / 3060 / 3050 / 2060
2
         win-gtx1660s / 1650
3
AMD:     win-rx7900xt / 7800xt / 7600 / 6700xt / 6600 / 580
4
Intel:   win-uhd770 / uhd630 / iris-xe / arc-a380 / a750 / hd4600

随机抽取而不是固定一个，是为了让多个并发会话不共享同一套硬件特征。

4.3 第 1 步：国家校验的防呆#

1
COUNTRY_MISMATCH_QUORUM = 2   # 至少两个独立源一致才判「位置不对」

为什么需要 quorum：单个 geo 服务抽风是常事。如果一源误报就直接判失败，你会白白丢掉一个干净 IP。要求两个以上独立数据源一致认定「不在目标国家」才抛错，显著降低误杀。

需要固定出口位置时：

1
ctx = opts.smart_fingerprint(
2
    proxy_host="gate.example.com", proxy_port=1000,
3
    require_country="US",          # 出口不在美国 → 直接抛错
4
    logger=print,
5
)

捕获异常：

1
from ruyipage import CountryMismatchError, GeoError
2

3
try:
4
    ctx = opts.smart_fingerprint(proxy_host=..., require_country="US")
5
except CountryMismatchError as e:
6
    print(f"国家不符: 实际 {e.actual} != 要求 {e.required}")
7
except GeoError as e:
8
    print(f"所有 geo 源都失败: {e}")

GeoError 的 message 里带十个源各自的失败摘要，所以能分辨是网络问题、限流还是解析错误。

4.4 离线兜底：manual_geo#

十个在线源全挂时（内网、被墙、代理屏蔽 geo 服务），用 manual_geo 继续跑：

1
ctx = opts.smart_fingerprint(
2
    proxy_host="proxy.example.com", proxy_port=8080,
3
    manual_geo={
4
        "ip": "75.166.187.10",
5
        "country_code": "US",
6
        "timezone": "America/Denver",
7
        "latitude": 39.7392,
8
        "longitude": -104.9903,
9
    },
10
    logger=print,
11
)

必需字段：ip / country_code / timezone / latitude / longitude。可选：country / region / city / ipv6。

注意优先级：在线 geo 成功时优先用在线结果，manual_geo 只是全部失败后的兜底。想强制指定就得断网或用 coerce_manual_geo() 单独构造。

4.5 智能指纹不覆盖的字段#

内核支持但 smart_fingerprint 不自动填的项，通过 extra 追加：

1
ctx = opts.smart_fingerprint(
2
    proxy_host=..., proxy_port=...,
3
    require_country="US",
4
    profile_id="win-rtx4090",        # 钉死档案，否则 extra 里的宽高对不上
5
    extra={
6
        "touch.maxTouchPoints": "5",
7
        "fonts.whitelist": "Arial|Segoe UI|Microsoft YaHei",
8
        "width": "2560",
9
        "height": "1440",
10
        "screen.devicePixelRatio": "1.25",
11
        "media.devices": "audioinput:1|videoinput:1|audiooutput:1",
12
    },
13
)

不覆盖的完整清单：touch.maxTouchPoints、fonts.whitelist、width / height、screen.devicePixelRatio、media.devices、其余 webgl.* / webgl2.*、webgpu.*。

profile_id 不能省：不指定档案的话，「用哪块显卡」是随机抽的，你写死的 width: 2560 可能配到一个 1080p 的档案上——自相矛盾。要么钉死档案，要么不加宽高。

extra 里不能覆盖保留键，会直接抛 FingerprintError。保留键包括 timezone / language / useragent / hardwareConcurrency / 所有 webgl.* / 所有 speech.voices.* / 所有 canvas.* / 所有 geolocation.* 等。

4.6 纵深防御：apply_emulation#

内核指纹是第一层，BiDi 仿真覆盖是第二层：

1
result = ctx.apply_emulation(
2
    page,
3
    set_screen_size=True,
4
    set_geolocation=True,
5
    set_locale=True,
6
    set_timezone=True,
7
    set_extra_headers=True,
8
)
9
# {'screen': True, 'geolocation': True, 'locale': True, 'timezone': True, 'headers': True}

为什么需要两层：内核指纹写的是底层值，但如果某个检测向量内核字段没覆盖到，BiDi 层的 set_* 会补上。每个子调用独立 try/except，版本不匹配时降级而不是崩。

异步页面用 await ctx.apply_emulation_async(page)。

注意 set_screen_size 对应的是 emulation.set_screen_size(w, h)，不代表外层窗口尺寸。set_window_size_on_opts 已废弃并被忽略——要设窗口大小得显式调 opts.set_window_size()。

五、拟人交互#

5.1 轨迹算法#

1
opts.set_human_algorithm("bezier")     # 默认：贝塞尔，轨迹平滑，支持 style 变体
2
opts.set_human_algorithm("windmouse")  # 风力 + 重力拖拽，路径更飘逸

算法	特点	适用
`bezier`	平滑、可控、支持变形	默认首选，绝大多数场景
`windmouse`	模拟风+重力，路径不规则	需要更强随机性的场景

两个都实现成 page.mouse.* 的底层——也就是页面级点击自动带轨迹，不需要每次手工构造路径。

5.2 拖拽：drag_to#

滑块类验证码的核心操作，实现走 W3C WebDriver BiDi input.performActions，也就是原生事件（isTrusted=true），而不是 dispatchEvent 合成事件。

1
handle = page.ele("#slider-handle")
2
handle.drag_to({"x": 300, "y": 450}, duration=1.2)

支持的三种目标形式：

1
handle.drag_to(target_element)                      # 拖到元素中心（自动滚动）
2
handle.drag_to({"x": 300, "y": 450}, duration=1.0)  # 视口绝对坐标
3
handle.drag_to((300, 450), duration=1.0)            # 同上，元组形式

内部动作序列（所有 pointerMove 用 origin="viewport" 保证坐标绝对精确）：

1
pointerMove(sx, sy, duration=0)     # 先移到起点
2
pointerDown(button=0)
3
pause(80ms)                          # ⚠️ 起手停顿——真人按下不会立刻移动
4
pointerMove × N                      # 分段匀速，steps = clamp(total_ms // 30, 8, 30)
5
pause(80ms)                          # ⚠️ 释放前停顿
6
pointerUp(button=0)

两个 80ms 的 pause 是有意为之：人类按下鼠标后有反应延迟，松开前也有。全程零延迟的完美拖拽是最明显的机器特征。

duration 参数的含义：拖拽动画总时长（秒），越大越平滑。太短（< 0.3）会退化成近似瞬移，建议滑块场景用 1.0 以上。

5.3 触屏兜底#

移动端指纹的场景需要触摸事件支持：

1
opts.set_touch_fallback(enabled=True, max_touch_points=5, profile="mobile")

配套 API：opts.can_install_touch_fallback() 检查是否可用（要求非 existing_only 且有 profile 路径），page.touch() 拿触摸动作对象。

六、元素定位与操作#

6.1 定位语法#

1
page.ele("#phone")                        # CSS
2
page.ele("//button[@type='submit']")      # XPath
3
page.ele("text=获取验证码")               # 文本（支持模糊）
4
page.ele("css:#aliyunCaptcha-checkbox-left")
5
page.eles("css:button")                   # 复数 → list

ele() 返回 FirefoxElement 或 NoneElement（不存在的元素是一个空对象而不是 None），所以链式调用不会崩：

1
# 不会抛 AttributeError
2
text = page.ele("#may-not-exist").text or ""

6.2 常用操作#

1
ele.click_self()                  # 点击自己（滚动到视口内再点）
2
ele.click()                       # 返回 Clicker，可配更多参数
3
ele.input("13800138000")          # 输入（默认先清空）
4
ele.clear()
5
ele.hover()
6
ele.double_click()
7
ele.right_click()
8
ele.drag_to(target, duration=1.0)
9
ele.run_js("(e) => e.textContent")
10
ele.screenshot(path="ele.png")

6.3 属性读取#

1
ele.tag              # 标签名
2
ele.text             # 文本
3
ele.value            # value 属性（输入框）
4
ele.attrs            # 全部属性 dict
5
ele.link             # href
6
ele.src
7
ele.is_displayed     # 是否可见
8
ele.is_enabled
9
ele.is_checked
10
ele.size             # {'width':..., 'height':...}
11
ele.location         # {'x':..., 'y':...}
12
ele.rect             # ElementRect 对象
13
ele.style("color")   # 计算样式

6.4 相对定位#

1
ele.parent()                    # 父元素
2
ele.child("tag:input")          # 子元素
3
ele.children()                  # 全部子元素
4
ele.next()                      # 下一个兄弟
5
ele.prev()                      # 上一个兄弟
6
ele.ele("css:.inner")           # 内部查找
7
ele.eles("css:li")

6.5 Shadow DOM#

处理 Web Components 里的元素：

1
ele.shadow_root                 # 开放的 shadow root
2
ele.closed_shadow_root          # 闭合的（内核能穿透）
3
ele.with_shadow("open")         # 指定模式
4
page.shadow_roots(mode="all", include_frames=True)

6.6 页面级 API#

1
page.get(url)                    # 导航
2
page.title / page.url / page.html
3
page.user_agent
4
page.ready_state
5
page.cookies                     # 读全部
6
page.get_cookies_filtered(name="session", domain="example.com")
7
page.set_cookies([...])
8
page.delete_cookies(name="tracking")
9
page.refresh(ignore_cache=True)
10
page.back() / page.forward()
11
page.wait_loading(timeout=30)
12
page.screenshot(path="shot.png", full_page=True)
13
page.save(path="page.html")      # 存页面，as_pdf=True 存 PDF
14
page.run_js("() => window.__ready")
15
page.run_js_loaded("() => document.readyState")

6.7 多标签#

1
tab = page.new_tab(url="https://example.com")
2
page.tabs_count
3
page.tab_ids
4
tabs = page.get_tabs(title="Login")
5
page.close_other_tabs()
6
page.quit(timeout=5, force=False)

七、代理配置#

7.1 凭据命名空间陷阱#

这是只在 SOCKS5 下才会炸的一个坑，也是排查起来最费时的一个：HTTP 代理和 SOCKS5 代理的账密在 fpfile 里是不同的键。

1
# HTTP 代理 —— httpauth.*
2
httpauth.host:gate.example.com
3
httpauth.port:1000
4
httpauth.username:user
5
httpauth.password:pass

1
# SOCKS5 代理 —— socksauth.*，写在 httpauth 下无效
2
socksauth.host:gate.example.com
3
socksauth.port:1000
4
socksauth.username:user
5
socksauth.password:pass

后果：把 SOCKS5 的账密写进 httpauth.*，Firefox 拿不到可用凭据，会弹出一个原生的用户名/密码对话框——自动化流程就此卡死在无人值守的机器上，而且日志里什么都没有。

库内部会读回 fpfile 校验（_read_httpauth_from_fpfile / _read_socksauth_from_fpfile），所以走 API 配置时它自己会选对命名空间。手工拼 fpfile 时务必注意。

7.2 设置代理#

1
opts.set_proxy("http://127.0.0.1:7890")
2
opts.set_proxy("socks5://user:pass@gate.example.com:1000")

代理是按实例的。多开时每个 FirefoxOptions 各配各的：

1
for proxy in proxy_list:
2
    opts = FirefoxOptions().set_port(0)
3
    opts.quick_start(proxy=proxy, headless=False)
4
    page = FirefoxPage(opts)
5
    ...

7.3 每标签页代理轮换#

这是 ruyiPage 的一个特色能力：同一个浏览器实例内，不同 tab 走不同代理。底层依赖定制内核读 proxy.rotate.* 配置，按 container tab 的 userContextId 分配。

1
opts.set_per_tab_proxies([
2
    "host1:1080:user1:pass1",
3
    "socks5://host2:1080:user2:pass2",
4
    "host3:1080:user3:pass3",
5
], exhausted="wrap")
6

7
# 新手友好别名
8
opts.set_proxy_rotate([...])

代理项支持两种格式：

1
"host:port:username:password"
2
"socks5://host:port:username:password"

耗尽策略 exhausted：

值	行为
`wrap`	用完后从头循环（默认）
`direct`	用完后直连
`none`	不再分配代理
`stop`	停止

配合 container tab 使用——每个 tab 独立 Cookie / 存储，加上独立代理，等于一个实例里的多个隔离身份：

1
tab1 = page.new_container_tab(url="https://example.com")
2
tabs = page.new_container_tabs(5, url="https://example.com")

7.4 geoip 与代理自洽#

代理 IP 和时区必须自洽——这是风控最常查的交叉验证项。smart_fingerprint 会自动做：

1
ctx = opts.smart_fingerprint(
2
    proxy_host="gate.example.com", proxy_port=1000,
3
    proxy_user="user", proxy_pwd="pass",
4
    require_country="US",
5
    logger=print,
6
)

它探测代理出口 IP → 反查归属地 → 映射到语言 / Accept-Language / 语音包 / 时区，全部写进 fpfile。

八、完整实战模板#

把上面的东西拼成一个可复用的启动函数：

1
import glob, os, logging
2
from ruyipage import (
3
    FirefoxOptions, FirefoxPage,
4
    apply_smart_fingerprint, CountryMismatchError, GeoError,
5
)
6

7
logging.basicConfig(level=logging.INFO)
8
log = logging.getLogger("auto")
9

10

11
def find_firefox():
12
    candidates = glob.glob(os.path.expandvars(
13
        r"%LOCALAPPDATA%\ruyipage\browsers\*\firefox\firefox.exe"))
14
    for path in sorted(candidates, reverse=True):
15
        if os.path.exists(path):
16
            return path
17
    return None
18

19

20
def launch(proxy_host=None, proxy_port=None, proxy_user=None, proxy_pwd=None,
21
           require_country="US", user_dir=None, headless=False,
22
           human_algorithm="bezier"):
23
    """启动一个带完整指纹的 Firefox 实例。"""
24
    opts = FirefoxOptions()
25
    opts.set_browser_path(find_firefox())
26
    opts.quick_start(
27
        headless=headless,
28
        human_algorithm=human_algorithm,
29
        window_size=(1920, 1080),
30
        timeout_page_load=45,
31
        failure_snapshot=True,          # 失败自动截图，排查利器
32
        snapshot_dir="./snapshots",
33
    )
34

35
    ctx = None
36
    if proxy_host:
37
        try:
38
            ctx = opts.smart_fingerprint(
39
                proxy_scheme="socks5",
40
                proxy_host=proxy_host, proxy_port=proxy_port,
41
                proxy_user=proxy_user, proxy_pwd=proxy_pwd,
42
                require_country=require_country,
43
                userdir=user_dir,
44
                logger=log.info,
45
            )
46
            log.info("指纹: %s", ctx.summary())
47
        except CountryMismatchError as e:
48
            raise RuntimeError(f"代理位置不符: {e.actual} != {e.required}") from e
49
        except GeoError as e:
50
            log.warning("geo 全部失败，改用 manual_geo: %s", e)
51
            ctx = opts.smart_fingerprint(
52
                proxy_host=proxy_host, proxy_port=proxy_port,
53
                proxy_user=proxy_user, proxy_pwd=proxy_pwd,
54
                manual_geo={
55
                    "ip": "0.0.0.0",
56
                    "country_code": require_country,
57
                    "timezone": "America/Denver",
58
                    "latitude": 39.7392,
59
                    "longitude": -104.9903,
60
                },
61
                logger=log.info,
62
            )
63

64
    page = FirefoxPage(opts)
65
    if ctx:
66
        ctx.apply_emulation(page)       # BiDi 纵深防御层
67
    return page, ctx
68

69

70
def send_code(phone: str):
71
    """示例：打开登录页 → 填号 → 勾协议 → 点发送。"""
72
    page, ctx = launch(
73
        proxy_host="gate.example.com", proxy_port=1000,
74
        proxy_user="user", proxy_pwd="pass",
75
    )
76
    try:
77
        page.get("https://example.com/login")
78

79
        page.ele("#phone").input(phone)
80
        page.run_js(
81
            "() => { const cb = document.querySelector('input[type=\"checkbox\"]');"
82
            " if (cb && !cb.checked) cb.click(); }"
83
        )
84
        page.ele("text=获取验证码").click_self()
85

86
        # 轮询按钮状态：进入倒计时 = 发送成功
87
        import time
88
        deadline = time.time() + 90
89
        while time.time() < deadline:
90
            for b in page.eles("css:button"):
91
                t = (b.text or "").strip()
92
                if "重新" in t or (t and any(c.isdigit() for c in t) and len(t) < 10):
93
                    log.info("发码成功: %s", t)
94
                    return True
95
            time.sleep(2)
96
        return False
97
    finally:
98
        page.quit()

九、调试工具#

反检测出问题时，光看日志基本没线索。ruyiPage 内置了几个专治这个的工具。

9.1 trace：BiDi 全量记录#

1
opts.enable_trace(True)
2

3
page = FirefoxPage(opts)
4
page.get("https://example.com")
5
# ... 操作 ...
6

7
print(page.trace.summary())          # 概览
8
page.trace.dump_json("trace.json")   # 完整导出

开启后所有 BiDi 命令、事件、网络活动记录进内存环形缓冲区。适合排查「命令发出去了但没反应」这类问题——能看到到底发出去了没有、返回了什么。

9.2 failure_snapshot：失败自动存证#

1
opts.enable_failure_snapshot(True)
2
opts.set_snapshot_dir("./snapshots")

出错时自动截图 + 存 DOM。并发或无人值守场景下这个必开——否则失败了你只有一行异常，什么上下文都没有。

9.3 action_visual：把鼠标轨迹画出来#

1
opts.enable_action_visual(True)

在页面上可视化鼠标行为。调拟人轨迹时这个最有用：轨迹到底是不是贝塞尔曲线、过冲有没有、停顿在哪，直接看比读代码快。

9.4 xpath_picker：定位辅助#

1
opts.enable_xpath_picker(True)

页面里弹 XPath 选择浮窗，点元素直接给选择器。写选择器阶段能省不少时间。

这四个都是调试用，生产环境全关——trace、snapshot、visual 都会注入额外脚本，本身就是可检测的痕迹。

十、常见坑速查#

现象	原因	处理
启动后立刻断开 / BiDi 连不上	`--marionette` 与该内核不兼容	`opts.enable_marionette(False)`
弹出原生用户名密码对话框	SOCKS5 账密写进了 `httpauth.*`	改用 `socksauth.*`
指纹静默失效（无报错）	fpfile 读到半个文件	用原子写入（库内已做，别自己写）
代理走了但真实 IP 仍泄漏	缺 `webrtc.ice_proxy_only:true`	补上该行
WebGL 检测通不过	只改了 renderer，其余上限没改	用成套硬件档案
Canvas 指纹每次都变	用了随机而非种子	固定 `canvas.seed`
`extra` 里的宽高和显卡档案对不上	没钉 `profile_id`，档案是随机抽的	显式指定 `profile_id`
提权环境下连接失败	Firefox 155 在提权会话的问题	`allow_system_access=True`
点击被判定为机器人	走了合成事件而非原生事件	用 `drag_to` / `page.mouse.*`
`geoip` 校验总是失败	单个 geo 源抽风	有 quorum=2 保护；持续失败配 `manual_geo`

十一、上线前检查清单#

结语#

ruyiPage 的思路和 Chromium 系反检测工具是两条路：

Chromium 系在运行时打补丁——CDP 注入、hook navigator、重写 page.mouse。优点是生态成熟、Playwright 兼容；缺点是补丁本身可以被反查。

ruyiPage 走内核原生——指纹在 C++ getter 层改写，配置是声明式的 fpfile。优点是痕迹更干净、指纹可控性更强；代价是 API 自成一套、需要理解 fpfile 的字段语义。

选哪条取决于目标站点的判定维度。有一条经验值得记住：如果 Chromium 系（包括反检测的）在某个目标上被整片拒绝，而换内核后有质变——那说明判定发生在内核层，继续调参数是浪费时间。

文中的域名、端口、密钥、路径全部为占位符。请在自己的合法测试环境中使用。

前言#