CloakBrowser使用教程

CloakBrowser使用教程
DreamCollector一、CloakBrowser 是什么
CloakBrowser 是一个反检测的隐身 Chromium 浏览器,通过 71 个 C++ 源码级补丁修改浏览器指纹(Canvas、WebGL、音频、字体、GPU、WebRTC、navigator.* 等),让反爬系统识别为”正常浏览器”。
核心特点:
- C++ 二进制级改造:不是 JS 注入,不是配置补丁,是真正编译进 Chromium 的修改
- API 兼容 Playwright:会 Playwright 就会 CloakBrowser,迁移成本极低
- 能过主流反爬:Cloudflare Turnstile、reCAPTCHA v3(得分 0.9)、FingerprintJS、DataDome
- 多语言支持:Python / JavaScript / .NET
项目地址:https://github.com/CloakHQ/CloakBrowser
二、与 Selenium 的区别
| 维度 | CloakBrowser | Selenium |
|---|---|---|
| 本质 | 反检测隐身浏览器(Chromium 改造版) | 浏览器自动化框架(驱动外部浏览器) |
| 反爬能力 | C++ 源码级指纹伪装,过 Cloudflare/reCAPTCHA | 留下 navigator.webdriver=true 等痕迹,普通反爬即可识别 |
| 协议 | CDP(Chrome DevTools Protocol) | W3C WebDriver |
| 速度 | 快(单进程直连) | 较慢(HTTP 协议) |
| 多浏览器 | 仅 Chromium 系 | Chrome/Firefox/Edge/Safari |
| API 风格 | Playwright 现代 API(auto-waiting) | 传统 WebDriver API(需手动显式等待) |
| 价格 | 免费版(旧版 v146)/ 付费版(最新版需 license) | 完全免费(Apache 2.0) |
| 生态 | 新兴(2024+),社区小 | 老牌(2004+),社区庞大 |
选择建议:
- 抓取有反爬保护的网站 → CloakBrowser
- Web UI 自动化测试、跨浏览器兼容测试 → Selenium
三、环境准备
1. 操作系统
支持 Windows / macOS / Linux。本教程以 Windows 为例。
2. 安装 Python 3.12
重要:不要使用 Python 3.13+ 或 3.15 beta 版本!实测 Python 3.15.0b3 的 sync API 会在
launch()时崩溃(退出码0xC0000005),需降级到 3.12 稳定版。
下载:访问 https://www.python.org/downloads/release/python-31210/
下载 Windows installer (64-bit):python-3.12.10-amd64.exe
静默安装到指定路径(PowerShell 管理员模式):
1 | $installer = "python-3.12.10-amd64.exe" |
坑点提醒:
TargetDir路径含空格时必须用双引号包裹,否则会被解析到D:\Program\错误位置。
验证安装:
1 | & "D:\Program Files\Python\python.exe" --version |
3. 验证 PATH
新开一个 PowerShell 窗口(让 PATH 生效),执行:
1 | python --version |
应输出 Python 3.12.10。如果仍指向旧版本,重启系统或手动刷新 PATH:
1 | $env:PATH = [System.Environment]::GetEnvironmentVariable("PATH","Machine") + ";" + [System.Environment]::GetEnvironmentVariable("PATH","User") |
四、安装 CloakBrowser
1. 安装主包
1 | pip install cloakbrowser |
可选依赖:自动根据代理 IP 检测时区/语言(需下载约 70MB GeoLite2 数据库):
1 | pip install 'cloakbrowser[geoip]' |
2. 验证安装
1 | python -c "import cloakbrowser; print('cloakbrowser installed')" |
3. 首次运行说明
首次调用 launch() 时,CloakBrowser 会自动下载约 200MB 的 Chromium 二进制文件并缓存到:
- Windows:
%USERPROFILE%\.cloakbrowser\ - macOS/Linux:
~/.cloakbrowser/
下载完成后,后续启动将直接使用本地缓存,无需再次下载。
4. License 说明(可选)
免费版使用 v146 旧版 Chromium 二进制,无需任何配置即可使用。
若需使用最新版二进制(更强的反检测能力),需登录获取免费 license key:
1 | # 通过 GitHub 登录获取免费 key |
也可在代码中传入:
1 | from cloakbrowser import launch |
五、快速开始:5 分钟入门
1. 最简示例:打开百度
创建文件 cloak_baidu_demo.py:
1 | """ |
2. 运行
1 | python cloak_baidu_demo.py |
预期输出:
1 | 正在打开百度... |
并生成 baidu_screenshot.png 截图文件。
六、核心 API 详解
1. launch() 参数说明
1 | from cloakbrowser import launch |
2. Page 常用方法
| 方法 | 说明 |
|---|---|
page.goto(url) |
打开 URL |
page.title() |
获取页面标题 |
page.content() |
获取页面 HTML |
page.screenshot(path="x.png") |
截图保存 |
page.fill(selector, text) |
在输入框中填入文本 |
page.click(selector) |
点击元素 |
page.query_selector(selector) |
查询单个元素 |
page.query_selector_all(selector) |
查询所有匹配元素 |
page.wait_for_selector(selector, state="visible") |
等待元素可见 |
page.wait_for_timeout(ms) |
等待指定毫秒 |
page.evaluate(js_expr) |
执行 JavaScript |
page.set_viewport_size({"width": 1280, "height": 800}) |
设置视口大小 |
3. 元素操作
1 | # 获取元素文本 |
七、实用场景示例
1. 无头模式后台运行
适合服务器环境或无需观察的场景:
1 | from cloakbrowser import launch |
2. 元素选择与文本提取
1 | from cloakbrowser import launch |
实测输出:
1 | h1: Example Domain |
3. 人类化操作(humanize)
模拟真人鼠标移动轨迹、键盘节奏、滚动行为,绕过行为分析类反爬:
1 | from cloakbrowser import launch |
实测输出:
1 | title after click: Loading https://iana.org/domains/example |
4. 反爬能力自检
访问反爬检测网站 bot.sannysoft.com,验证浏览器指纹是否被识别为自动化:
1 | from cloakbrowser import launch |
实测输出:
1 | navigator.webdriver: False |
关键指标:
navigator.webdriver为False表示未检测到自动化痕迹。
原生 Selenium/Playwright 此处会显示True,立即被反爬系统识别。
八、反爬场景配置
1. 完整反爬配置
针对 Cloudflare、Akamai 等强反爬网站,推荐配置:
1 | from cloakbrowser import launch |
2. 配置参数详解
| 参数 | 作用 | 适用场景 |
|---|---|---|
headless=False |
显示浏览器窗口 | 部分网站检测无头模式 |
humanize=True |
人类化操作 | 行为分析类反爬(鼠标轨迹、键盘节奏) |
human_preset="careful" |
谨慎预设 | 高强度反爬(操作更慢更稳) |
proxy="..." |
代理 IP | 频率限制、IP 封禁 |
geoip=True |
时区/语言自动匹配代理 IP | 时区不一致会触发检测 |
timezone="..." |
显式设置时区 | 不用代理但需伪装时区 |
locale="..." |
显式设置语言 | 不用代理但需伪装语言 |
3. humanize 预设对比
| 预设 | 特点 | 适用场景 |
|---|---|---|
default |
默认平衡(速度 vs 拟真) | 一般反爬场景 |
careful |
操作更慢、轨迹更复杂 | 高强度反爬(Cloudflare Turnstile) |
九、常见问题与排错
Q1: 运行脚本无任何输出就退出
现象:执行 python script.py 后立即退出,无错误信息,退出码 3221225477 (0xC0000005)。
原因:Python 版本不兼容。Python 3.13+ 或 3.15 beta 的 sync API 在 launch() 时崩溃。
解决:降级到 Python 3.12 稳定版(参考第 3 节)。
临时方案:使用 async API 替代 sync API:
1 | import asyncio |
Q2: 首次启动卡在下载 Chromium
现象:launch() 调用后长时间无响应。
原因:首次使用需下载约 200MB Chromium 二进制。
解决:检查网络,或手动下载放到 %USERPROFILE%\.cloakbrowser\ 目录下。
Q3: humanize 模式下输入框报 “element is not visible”
现象:page.fill(selector, text) 抛出 ElementNotVisibleError。
原因:humanize 模式对元素可见性检查更严格,部分网站对自动化浏览器返回不同 DOM。
解决:
- 设置视口大小:
page.set_viewport_size({"width": 1280, "height": 800}) - 显式等待元素可见:
page.wait_for_selector(selector, state="visible", timeout=10000) - 换用更稳定的网站测试,或对目标网站先做 DOM 分析
Q4: humanize 模式下点击报 “element is covered”
现象:page.click(selector) 抛出 ElementNotReceivingEventsError: element is covered。
原因:目标元素被覆盖层(如 cookie 同意弹窗、广告)遮挡。
解决:
- 先关闭覆盖层:
page.click('.cookie-consent-button') - 使用
force=True强制点击:page.click(selector, force=True) - 用 JS 直接执行:
page.evaluate('document.querySelector("selector").click()')
Q5: Windows 安装 Python 时路径含空格被错误解析
现象:指定 TargetDir=D:\Program Files\Python 静默安装后,Python 装到了 D:\Program\。
原因:PowerShell 中未用双引号包裹含空格的路径。
解决:使用双引号包裹:
1 | $argList = '/quiet InstallAllUsers=1 "TargetDir=D:\Program Files\Python" PrependPath=1' |
Q6: greenlet 导入失败(ImportError)
现象:从其他 Python 版本迁移后,import greenlet 报 DLL 加载失败或 undefined symbol。
原因:旧 site-packages 中的 C 扩展是其他 Python 版本编译的。
解决:强制重装含 C 扩展的包:
1 | pip install --force-reinstall --no-cache-dir greenlet cffi cryptography pycparser |
Q7: 如何查看当前 navigator.webdriver 值
1 | from cloakbrowser import launch |



