Jeffx06/playwright-stealth-ultimate
GitHub: Jeffx06/playwright-stealth-ultimate
该框架通过伪装浏览器自动化指纹特征，帮助 Playwright 和 Selenium 脚本绕过 Cloudflare、DataDome 等反 bot 检测系统。
Stars: 0 | Forks: 0
# 🛡️ Playwright Stealth Ultimate
**用于 Playwright 和 Selenium 的反 bot 绕过框架**
[](https://www.python.org/downloads/)
[](https://playwright.dev/python/)
[](LICENSE)
[](tests/)
[](https://pypi.org/project/playwright-stealth-ultimate/)
[](https://github.com/jeffx/playwright-stealth-ultimate)
## 📋 目录
- [🛡️ Playwright Stealth Ultimate](#️-playwright-stealth-ultimate)
- [📋 目录](#-table-des-matières)
- [📖 简介](#-présentation)
- [✨ 功能特性](#-fonctionnalités)
- [📦 安装](#-installation)
- [前置条件](#prérequis)
- [标准安装](#installation-standard)
- [安装包](#installer-le-package)
- [安装 Playwright 浏览器](#installer-les-navigateurs-playwright)
- [克隆仓库](#cloner-le-dépôt)
- [以 editable 模式安装](#installer-en-mode-editable)
- [安装浏览器](#installer-les-navigateurs)
- [✅ 启用 stealth](#-activer-le-stealth)
- [使用说明](#utilisation)
- [✅ 完整配置](#-configuration-complète)
- [应用到页面](#appliquer-à-une-page)
- [✅ 页面配置](#-configuration-des-pages)
- [✅ 抓取](#-scraper)
- [运行所有测试](#exécuter-tous-les-tests)
- [仅单元测试](#tests-unitaires-uniquement)
- [Playwright 集成测试](#tests-dintégration-playwright)
- [快速基准测试 (20 次迭代)](#benchmarks-rapides-20-itérations)
- [完整基准测试 (50 次迭代)](#benchmarks-complets-50-itérations)
- [🛡️ 由 Jeff 精心打造 — 🎯 Playwright Stealth Ultimate © 2026 ⚡](#️-crafted-with-precision-by-jeff---playwright-stealth-ultimate--2026-)
## 📖 简介
**Playwright Stealth Ultimate** 是一个 Python 框架，旨在使用 **Playwright** 或 **Selenium** 进行浏览器自动化时，避免被反 bot 系统（Cloudflare、DataDome、Akamai 等）检测到。
该框架通过修改浏览器原生 API 来隐藏最常见的自动化特征信号：
- `navigator.webdriver`
- `window.chrome.runtime`
- Canvas / Audio / WebGL 指纹
- 插件和 MIME 类型
- 屏幕尺寸
- 系统字体
- WebRTC / 地理定位
- 以及更多...
## ✨ 功能特性
| 类别 | 绕过策略 |
|-----------|----------|
| **浏览器** | `navigator.webdriver`, `navigator.plugins`, `navigator.mimeTypes` |
| **Chrome** | `window.chrome.runtime`, `window.chrome.app`, `window.chrome.csi` |
| **指纹** | Canvas, AudioContext, WebGL, Fonts |
| **网络** | WebRTC, 本地 IP, Permissions |
| **硬件** | `navigator.hardwareConcurrency`, `navigator.deviceMemory` |
| **OS** | `navigator.platform`, `navigator.userAgent`, `navigator.languages` |
| **显示** | `window.outerWidth`, `window.outerHeight`, `screen` |
| **行为** | 鼠标移动、键盘敲击、滚动 |
## 📦 安装
### 前置条件
- Python 3.10 或更高版本
- Playwright 或 Selenium
### 标准安装
# 安装包
pip install playwright-stealth-ultimate
# 安装 Playwright 浏览器
playwright install
用于开发的安装
bash
# 克隆仓库
git clone https://github.com/jeffx/playwright-stealth-ultimate.git
cd playwright-stealth-ultimate
# 以 editable 模式安装
pip install -e .[dev]
# 安装浏览器
playwright install
🚀 快速开始
Playwright 基础示例
python
from playwright.sync_api import sync_playwright
from playwright_stealth import stealth_sync
with sync_playwright() as p:
browser = p.chromium.launch(headless=False)
page = browser.new_page()
```
# ✅ 一行代码激活 stealth
stealth_sync(page)
# 导航到网站
page.goto("https://example.com")
# 验证 stealth 是否激活
result = page.evaluate("() => navigator.webdriver")
print(f"webdriver: {result}") # ✅ undefined
browser.close()
```
Selenium 示例
python
from selenium import webdriver
from playwright_stealth.adapters.selenium import stealth_selenium
driver = webdriver.Chrome()
# ✅ 启用 stealth
stealth_selenium(driver)
driver.get("https://example.com")
print(driver.execute_script("return navigator.webdriver")) # ✅ undefined
driver.quit()
🎯 高级用法
自定义 Profile
python
from playwright.sync_api import sync_playwright
from playwright_stealth import stealth_sync
from playwright_stealth.core.types import HardwareTier, OSType, BrowserVendor
with sync_playwright() as p:
browser = p.chromium.launch()
page = browser.new_page()
```
# ✅ 自定义 Profile (MacBook Pro)
stealth_sync(
page,
hardware_tier=HardwareTier.PREMIUM,
os_type=OSType.MACOS,
browser_vendor=BrowserVendor.CHROME,
custom_seed="a1b2c3d4e5f67890" # Seed pour la reproductibilité
)
page.goto("https://example.com")
browser.close()
```
自定义绕过模块
python
from playwright.sync_api import sync_playwright
from playwright_stealth.core.engine import FingerprintEngine
from playwright_stealth.core.types import EvasionModule
class CustomHeaderModule:
"""用于添加 HTTP headers 的自定义模块"""
name = "custom_header"
priority = 10
dependencies = ()
conflicts = ()
```
def build(self, profile, loader):
return """
(function() {
const originalFetch = window.fetch;
window.fetch = function(url, options) {
options = options || {};
options.headers = options.headers || {};
options.headers['X-Custom-Header'] = 'Stealth-Module';
return originalFetch.call(this, url, options);
};
console.log('🛡️ Custom header module activé');
})();
"""
def validate(self, profile):
return []
```
# 使用说明
with sync_playwright() as p:
browser = p.chromium.launch()
page = browser.new_page()
```
# 使用自定义模块创建 engine
from playwright_stealth.core.profile import FingerprintProfile
from playwright_stealth.services.builder import BuilderService
from playwright_stealth.services.injector import InjectorService
# ... (services)
# 注入
engine.inject(page, enabled_modules=["custom_header"])
page.goto("https://example.com")
browser.close()
```
完整配置
python
from playwright_stealth import FullConfig, PlaywrightStealthClient
# ✅ 完整配置
config = FullConfig(
hardware_tier=HardwareTier.HIGH,
os_type=OSType.WINDOWS,
browser_vendor=BrowserVendor.CHROME,
enabled_modules=["webdriver", "canvas", "audio", "intl"],
consistency="strict",
performance="balanced",
cache_size=2000,
telemetry_enabled=True,
debug=True
)
client = PlaywrightStealthClient(config)
client.initialize()
# 应用到页面
client.apply_to_page(page)
多页面抓取
python
from playwright_stealth import MultiPageScraper, PageConfig
# ✅ 页面配置
pages = [
PageConfig(
url="https://example.com",
name="Example",
selectors={"title": "h1", "description": "p"}
),
PageConfig(
url="https://www.wikipedia.org",
name="Wikipedia",
selectors={"title": "h1", "links": "a"}
)
]
# ✅ 抓取
scraper = MultiPageScraper()
results = scraper.scrape_pages(pages, rotate_profiles=True)
scraper.export_results()
🔧 API
主要函数
函数 描述
stealth_sync(page, ...) 将 stealth 应用到 Playwright 页面 (同步)
stealth_async(page, ...) 将 stealth 应用到 Playwright 页面 (异步)
stealth_selenium(driver, ...) 将 stealth 应用到 Selenium driver
dump_configuration() 显示当前配置
可用类型
类型 描述
HardwareTier LOW, MEDIUM, HIGH, PREMIUM
OSType WINDOWS, MACOS, LINUX
BrowserVendor CHROME, EDGE, BRAVE, OPERA
FingerprintProfile 完整的指纹 Profile
EvasionModule 绕过模块的接口
🧪 测试
bash
# 运行所有测试
python run_all_tests.py
# 仅单元测试
pytest tests/unit/ -v
# Playwright 集成测试
pytest tests/integration/test_injection.py -v -m playwright
📊 基准测试
bash
# 快速基准测试 (20 次迭代)
python examples/advanced/benchmark_runner.py -i 20 -w 3
# 完整基准测试 (50 次迭代)
python examples/advanced/benchmark_runner.py -i 50 -w 5
典型结果
基准测试 平均值 平均耗时 (ms) P95 (ms)
Profile 生成 < 0.10 < 0.50
Plan 构建 (1 个模块) < 0.02 < 0.10
Plan 构建 (5 个模块) < 0.02 < 0.10
Playwright 注入 < 100 < 200
🤝 贡献
欢迎提交贡献！
✅ 遵循 PEP 8 风格
✅ 使用类型提示 (type hints)
📝 许可证
MIT © Jeff - Playwright Stealth Ultimate
## 🛡️ 由 Jeff 精心打造 — 🎯 Playwright Stealth Ultimate © 2026 ⚡
[](https://github.com/jeffx/playwright-stealth-ultimate)
[](https://pypi.org/project/playwright-stealth-ultimate/)
[](LICENSE)
标签：BeEF, Playwright, Selenium, Web自动化, 反机器人检测, 反爬虫对抗, 爬虫, 特征检测, 自定义脚本, 逆向工具