invisible_playwright v0.7.0

invisible_playwright，运行在反检测 Firefox 上的 Playwright。一段动画：从 Playwright 切换的两行开关、引擎内部设置的指纹、像手一样移动的鼠标，以及它通过的各项机器人测试。

Playwright 会被反机器人机制和验证码识别出来。
而这一款运行在带有未检测指纹的反检测 Firefox 上，兼容你现有的 Playwright 代码。

invisible_playwright - 5/5 检测套件全部通过

工作原理

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

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

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

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

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

安装

Windows，在 PowerShell 中：

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
$env:Path = "$env:USERPROFILE\.local\bin;$env:Path"
uv init --python ">=3.11" my-project
cd my-project
uv add invisible-playwright
uv run invisible-playwright fetch      # one-time download, sha256-verified: 240 MB, about 550 MB unpacked

Linux：

curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env
uv init --python ">=3.11" my-project
cd my-project
uv add invisible-playwright
uv run invisible-playwright fetch      # one-time download, sha256-verified: 262 MB (x86_64) / 253 MB (arm64), about 550 MB unpacked

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

然后将下面示例之一保存为 my-project 中的 main.py，并用 uv run main.py 运行它。

用法

每个会话随机指纹

Playwright 的 API，同步和异步，无需更改代码。 相同的对象、相同的调用、相同的返回值。少数接口不在支持范围内——tracing、HAR、CDP、API 请求上下文——每一个都会以一句话说明原因来拒绝，而不是悄悄地出错。如果你已经在使用 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")   # mouse arcs to the button on a Bezier curve

异步

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:
    ...   # same GPU, same canvas hash, same audio context, every run

代理

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

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

时区

浏览器时区跟随 timezone=：

# default: timezone is auto-derived from the egress IP (proxy egress if a
# proxy is set, otherwise the host's own public IP)
with InvisiblePlaywright(proxy=proxy) as browser:
    ...

# explicit IANA zone always wins, the only way to force a specific zone
with InvisiblePlaywright(proxy=proxy, timezone="America/New_York") as browser:
    ...

固定特定指纹字段

默认情况下，所有内容都来自 seed。若要在其余部分仍由 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 pin 会从已验证的 persona 中选择一个，而不是设置一个自由字符串，因为约 81 个 getParameter 值和扩展列表会随渲染器名称一起传递，并且检测器会将其与该名称进行交叉核对。如果池中不包含某个名称，则会引发错误，并且错误信息会列出池中确实包含的名称。

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

CLI

安装后的命令是 invisible-playwright，带连字符。python -m invisible_playwright 的作用完全相同，并且不需要 PATH 中有任何内容。

invisible-playwright fetch    # download the engine if missing, check every cached
                              # one against the seal, print the path
invisible-playwright version  # wrapper, core and engine versions, and where the
                              # engine is cached

文档、指南与对比

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

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

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

如果你不知道从哪里开始：让 Playwright 不被检测的三种方式是大多数其他页面都会链接回来的地图，Playwright 在某个网站上被检测为机器人是排查顺序，而 navigator.webdriver 并不是你以为的那个破绽解释了这个领域最著名的属性，以及为什么仅修补它几乎毫无用处。