invisible_playwright v0.20.0

工作原理

反机器人系统会问两个问题，reCAPTCHA、hCaptcha 和 Cloudflare Turnstile 会对答案打分。invisible_playwright 对这两个问题都回答“是”。

1. 这是真实浏览器吗？ 是。它是 Firefox，在 C++ 源码层面进行了补丁修改。

• 浏览器指纹在引擎内部设置，而不是注入到页面中：navigator、screen、GPU/WebGL、canvas、字体、音频、WebRTC、时区、网络。无论无头还是有头，取值都相同。
• 没有 JS 垫片，没有覆盖，没有可被读取的接缝。

2. 是真实的人在使用它吗？ 是。操作在驱动层进行了拟人化处理。

• 每一次点击、悬停和拖拽都遵循自然的鼠标轨迹和人类时序，光标不会瞬移。
• 每一次输入都与真实鼠标逐字节一致：真实的输入源、压力、可信事件。

---

安装

pip install invisible-playwright
python -m invisible_playwright fetch      # 一次性下载，经 sha256 校验：240 MB（Windows）/ 262 MB（Linux x86_64）/ 253 MB（Linux arm64），解压后约 550 MB

需要 Python 3.11 或更高版本。

支持的平台：Windows x86_64、Linux x86_64 / arm64。

---

用法

每个会话使用随机指纹

Playwright 的 API，同步和异步，无需修改代码。 相同的对象、相同的调用、相同的返回值。少数接口不在支持范围内——tracing、HAR、CDP、API request context——每一个都会明确拒绝并说明原因，而不是悄悄出错。如果你已经在使用 Playwright，切换只需两行：

- from playwright.sync_api import sync_playwright
- with sync_playwright() as p:
-     browser = p.firefox.launch()
+ from invisible_playwright import InvisiblePlaywright
+ with InvisiblePlaywright() as browser:

每个会话都会获得一个独特的指纹（GPU、音频、字体、屏幕，约 200 个字段）以及贝塞尔曲线鼠标运动。

同步

from invisible_playwright import InvisiblePlaywright

with InvisiblePlaywright(proxy={"server": "socks5://...", "username": "u", "password": "p"}) as browser:
    page = browser.new_page()
    page.goto("https://example.com")
    page.click("#submit")   # 鼠标沿贝塞尔曲线弧线移动到按钮上

异步

from invisible_playwright.async_api import InvisiblePlaywright

async with InvisiblePlaywright(proxy={"server": "socks5://...", "username": "u", "password": "p"}) as browser:
    page = await browser.new_page()
    await page.goto("https://example.com")
    await page.click("#submit")

browser 对象是一个 playwright.sync_api.Browser / playwright.async_api.Browser——每一个 Playwright 方法都可原样使用。

记录种子以重放一次运行：

sf = InvisiblePlaywright()
with sf as browser:
    print("seed =", sf.seed)
    # ...

可复现的指纹

with InvisiblePlaywright(seed=42) as browser:
    ...   # 每次运行都是相同的 GPU、相同的 canvas 哈希、相同的音频上下文

代理

proxy = {
    "server": "socks5://gate.example.com:1080",
    "username": "user",
    "password": "pass",
}
with InvisiblePlaywright(proxy=proxy) as browser:
    ...

支持的协议：socks5、socks4、http、https。DNS 默认通过代理路由，不会本地泄露。

时区

浏览器时区跟随 timezone=：

# 默认：时区根据出口 IP 自动推导（如果设置了代理，则为代理出口，
# 否则为主机自身的公网 IP）
with InvisiblePlaywright(proxy=proxy) as browser:
    ...

# 显式指定的 IANA 时区始终优先，这是强制指定特定时区的唯一方式
with InvisiblePlaywright(proxy=proxy, timezone="America/New_York") as browser:
    ...

固定特定指纹字段

默认情况下所有内容都来自 seed。若要强制指定特定值，同时其余部分仍由种子推导：

with InvisiblePlaywright(
    seed=42,
    pin={
        "gpu.renderer": "ANGLE (AMD, Radeon R9 200 Series Direct3D11 vs_5_0 ps_5_0, D3D11)",
        "gpu.vendor":   "Google Inc. (AMD)",
        "screen.width":  2560,
        "screen.height": 1440,
        "hardware.concurrency": 16,
    },
) as browser:
    ...

GPU 固定值会从已验证的角色中选择一个，而不是设置任意字符串， 因为约 81 个 getParameter 值和扩展列表会随渲染器名称一起变化， 检测器会将它们与该名称交叉核对。如果池中不包含该名称则会报错， 错误信息会列出池中已有的名称。

可固定键的完整列表、固定与贝叶斯采样器的交互方式，以及常见模式，见 docs/pinning.md。

---

CLI

安装后的命令是 invisible-playwright，带连字符。python -m invisible_playwright 效果完全相同，且无需在 PATH 中配置任何内容。

invisible-playwright fetch    # 如果缺失则下载引擎，将每个缓存
                              # 与封印进行校验，打印路径
invisible-playwright version  # wrapper、core 和引擎版本，以及
                              # 引擎的缓存位置

文档、指南与对比

如果你更想用提示词而不是写脚本。 本页面介绍的是引擎，作为一个 Python 库。有两种无需编写代码即可使用它的方式，都只需一行：从你已有的 MCP 客户端 （Claude Code、Claude Desktop、Cursor）中， claude mcp add stealth -- uvx aihawk，见 the MCP server page；或者使用一个 自带界面和模型的版本，只需一个 OpenRouter 密钥， uvx aihawk ui --openrouter-key sk-or-...，见 AIHawk。底层是同一个引擎，后者 是前者的客户端。

所有这些内容在 the wiki 中阅读体验更好，且可搜索， 它被组织为四个部分，而不是一个扁平列表：

• Documentation - 安装、从普通 Playwright 切换的两行代码、代理/时区 配置、固定特定字段、CLI。
• Guides - 检测 实际是如何工作的，分为七组：浏览器身份、canvas/WebGL/字体/ 音频、网络与 WebRTC、自动化层、AI 代理、从源码 解释的检测器本身，以及测试。
• Comparisons - 与 Camoufox、Patchright、nodriver 和 playwright-stealth 的对比，以及 总体上选择 Firefox 而非 Chromium 的理由。
• Integrations - Scrapy、Crawlee、Robot Framework、CodeceptJS、测试运行器、Playwright MCP，以及 它不适用（按名称列出）的框架。

如果你不知道从哪里开始：Three ways to make Playwright undetected 是大多数其他页面都会链接回来的地图，Playwright detected as a bot on one site 是排查顺序，而 navigator.webdriver is not the tell you think it is 解释了这个领域最著名的属性，以及为什么仅修补它几乎 毫无用处。

检测器部分现在按名称涵盖了商业反机器人产品，每一个 都从其自身文档或经确认的逆向工程中解读： Cloudflare Bot Management 和 Turnstile、 DataDome、Kasada、 Akamai Bot Manager、 PerimeterX、hCaptcha、 Imperva，以及 the rest of the set。

相关项目

本项目的其他组成部分。 引擎是三者中的中间部分，围绕它的 两个项目是大多数人接触它的方式：

• invisible_core - 从种子到 指纹再到偏好设置，外加代理和地理位置。本包固定了它。
• AIHawk - 将此引擎作为 MCP 服务器（uvx aihawk，适用于任何自带 模型的客户端），并在同一个包中提供一个自带模型的界面，只需 一条命令。该界面是服务器的客户端，没有通往浏览器的私有路径。

开源邻居们。 哪一个适合取决于你的问题处于哪一层， 以及你需要 Firefox 还是 Chromium： three ways to make Playwright undetected 梳理了 每一层能触及什么，而 AI browser agents and stealth 涵盖了那些替你选择 Chromium 而非 CDP 的框架。

Firefox 阵营

• Camoufox - 同样修补 C++，覆盖面更广，附带一个指纹数据库，而不是从种子推导。 Comparison。
• LibreWolf - 一个默认注重隐私的 Firefox，用于浏览，而非自动化。
• arkenfox/user.js - 通过偏好设置进行加固。当偏好设置足够时，就用它。