CloakBrowser使用教程

一、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
2
3
$installer = "python-3.12.10-amd64.exe"
$argList = '/quiet InstallAllUsers=1 "TargetDir=D:\Program Files\Python" PrependPath=1 Include_test=0 Include_doc=0 Include_launcher=1 InstallLauncherAllUsers=1'
Start-Process -FilePath $installer -ArgumentList $argList -Wait

坑点提醒TargetDir 路径含空格时必须用双引号包裹,否则会被解析到 D:\Program\ 错误位置。

验证安装

1
2
3
4
5
& "D:\Program Files\Python\python.exe" --version
# 输出应为:Python 3.12.10

& "D:\Program Files\Python\python.exe" -m pip --version
# 输出应为:pip 25.0.1 ...

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
2
3
4
5
# 通过 GitHub 登录获取免费 key
cloakbrowser login

# 或设置环境变量
set CLOAKBROWSER_LICENSE_KEY=cb_xxxxxxxx

也可在代码中传入:

1
2
from cloakbrowser import launch
browser = launch(license_key="cb_xxxxxxxx")

五、快速开始:5 分钟入门

1. 最简示例:打开百度

创建文件 cloak_baidu_demo.py

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
"""
CloakBrowser 示例:打开百度网站
"""
from cloakbrowser import launch


def main():
# 启动隐身浏览器(有头模式,方便观察)
browser = launch(headless=False)

try:
page = browser.new_page()
print("正在打开百度...")
page.goto("https://www.baidu.com", wait_until="domcontentloaded")

# 打印页面标题
title = page.title()
print(f"页面标题: {title}")

# 截图保存
page.screenshot(path="baidu_screenshot.png")
print("截图已保存: baidu_screenshot.png")

# 暂停 5 秒方便观察
page.wait_for_timeout(5000)
finally:
browser.close()
print("浏览器已关闭。")


if __name__ == "__main__":
main()

2. 运行

1
python cloak_baidu_demo.py

预期输出

1
2
3
4
正在打开百度...
页面标题: 百度一下,你就知道
截图已保存: baidu_screenshot.png
浏览器已关闭。

并生成 baidu_screenshot.png 截图文件。


六、核心 API 详解

1. launch() 参数说明

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
from cloakbrowser import launch

browser = launch(
headless=False, # 是否无头模式(默认 True)
proxy="http://user:pass@host:port", # 代理 URL
args=["--start-maximized"], # 额外的 Chromium 命令行参数
timezone="America/New_York", # IANA 时区
locale="en-US", # BCP 47 语言
geoip=True, # 根据代理 IP 自动设置时区/语言
humanize=True, # 启用人类化鼠标/键盘/滚动
human_preset="default", # 人类化预设:'default' 或 'careful'
human_config={...}, # 自定义人类化参数
stealth_args=True, # 启用默认隐身指纹参数(默认 True)
extension_paths=["..."], # 加载的 Chrome 扩展路径列表
license_key="cb_xxx", # 使用最新版二进制
)

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
2
3
4
5
6
7
8
9
# 获取元素文本
element = page.query_selector('h1')
text = element.inner_text()

# 获取属性
href = element.get_attribute('href')

# 在元素上执行 JS
result = page.evaluate('() => navigator.webdriver')

七、实用场景示例

1. 无头模式后台运行

适合服务器环境或无需观察的场景:

1
2
3
4
5
6
7
8
from cloakbrowser import launch

browser = launch(headless=True) # 无头模式
page = browser.new_page()
page.goto("https://example.com", wait_until="domcontentloaded")
print("title:", page.title())
page.screenshot(path="headless.png")
browser.close()

2. 元素选择与文本提取

1
2
3
4
5
6
7
8
9
10
11
12
13
from cloakbrowser import launch

browser = launch(headless=True)
try:
page = browser.new_page()
page.goto("https://example.com", wait_until="domcontentloaded")

h1 = page.query_selector('h1').inner_text()
para = page.query_selector('p').inner_text()
print("h1:", h1)
print("p:", para)
finally:
browser.close()

实测输出

1
2
h1: Example Domain
p: This domain is for use in documentation examples without needing permission. ...

3. 人类化操作(humanize)

模拟真人鼠标移动轨迹、键盘节奏、滚动行为,绕过行为分析类反爬:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
from cloakbrowser import launch

browser = launch(
headless=False,
humanize=True,
args=["--start-maximized"]
)
try:
page = browser.new_page()
page.set_viewport_size({"width": 1280, "height": 800})
# 用 example.com 测试 humanize 鼠标点击(页面简单无遮挡)
page.goto("https://example.com", wait_until="domcontentloaded")
page.wait_for_selector('a', state="visible", timeout=10000)
# humanize 会模拟真人鼠标轨迹移动到链接并点击
page.click('a')
page.wait_for_load_state("domcontentloaded")

print("title after click:", page.title())
page.screenshot(path="humanize.png")
finally:
browser.close()

实测输出

1
title after click: Loading https://iana.org/domains/example

4. 反爬能力自检

访问反爬检测网站 bot.sannysoft.com,验证浏览器指纹是否被识别为自动化:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
from cloakbrowser import launch

browser = launch(headless=False)
try:
page = browser.new_page()
page.set_viewport_size({"width": 1280, "height": 800})
page.goto("https://bot.sannysoft.com", wait_until="networkidle", timeout=30000)
page.wait_for_timeout(3000)

metrics = page.evaluate("""() => ({
webdriver: navigator.webdriver,
languages: navigator.languages,
platform: navigator.platform
})""")
print("navigator.webdriver:", metrics['webdriver'])
print("navigator.languages:", metrics['languages'])
print("navigator.platform:", metrics['platform'])

page.screenshot(path="fingerprint.png", full_page=True)
finally:
browser.close()

实测输出

1
2
3
navigator.webdriver: False
navigator.languages: ['zh-CN']
navigator.platform: Win32

关键指标:navigator.webdriverFalse 表示未检测到自动化痕迹。
原生 Selenium/Playwright 此处会显示 True,立即被反爬系统识别。


八、反爬场景配置

1. 完整反爬配置

针对 Cloudflare、Akamai 等强反爬网站,推荐配置:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
from cloakbrowser import launch

browser = launch(
headless=False, # 有头模式(部分网站检测无头)
proxy="http://user:pass@residential-proxy:port", # 住宅代理 IP
geoip=True, # 自动匹配代理 IP 的时区+语言
humanize=True, # 人类化鼠标/键盘/滚动
human_preset="careful", # 谨慎预设(更接近真人)
args=["--start-maximized"], # 窗口最大化
)

try:
page = browser.new_page()
page.set_viewport_size({"width": 1280, "height": 800})
page.goto("https://protected-site.com", wait_until="domcontentloaded")
# ... 业务操作
finally:
browser.close()

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
2
3
4
5
6
7
8
9
10
11
12
13
import asyncio
from cloakbrowser import launch_async

async def main():
browser = await launch_async(headless=False)
try:
page = await browser.new_page()
await page.goto("https://www.baidu.com")
print("title:", await page.title())
finally:
await browser.close()

asyncio.run(main())

Q2: 首次启动卡在下载 Chromium

现象launch() 调用后长时间无响应。

原因:首次使用需下载约 200MB Chromium 二进制。

解决:检查网络,或手动下载放到 %USERPROFILE%\.cloakbrowser\ 目录下。

Q3: humanize 模式下输入框报 “element is not visible”

现象page.fill(selector, text) 抛出 ElementNotVisibleError

原因:humanize 模式对元素可见性检查更严格,部分网站对自动化浏览器返回不同 DOM。

解决

  1. 设置视口大小:page.set_viewport_size({"width": 1280, "height": 800})
  2. 显式等待元素可见:page.wait_for_selector(selector, state="visible", timeout=10000)
  3. 换用更稳定的网站测试,或对目标网站先做 DOM 分析

Q4: humanize 模式下点击报 “element is covered”

现象page.click(selector) 抛出 ElementNotReceivingEventsError: element is covered

原因:目标元素被覆盖层(如 cookie 同意弹窗、广告)遮挡。

解决

  1. 先关闭覆盖层:page.click('.cookie-consent-button')
  2. 使用 force=True 强制点击:page.click(selector, force=True)
  3. 用 JS 直接执行:page.evaluate('document.querySelector("selector").click()')

Q5: Windows 安装 Python 时路径含空格被错误解析

现象:指定 TargetDir=D:\Program Files\Python 静默安装后,Python 装到了 D:\Program\

原因:PowerShell 中未用双引号包裹含空格的路径。

解决:使用双引号包裹:

1
2
$argList = '/quiet InstallAllUsers=1 "TargetDir=D:\Program Files\Python" PrependPath=1'
Start-Process -FilePath $installer -ArgumentList $argList -Wait

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
2
3
4
5
6
7
8
9
from cloakbrowser import launch

browser = launch()
page = browser.new_page()
page.goto("https://example.com")
print(page.evaluate('() => navigator.webdriver'))
# CloakBrowser 输出:False
# 原生 Selenium/Playwright 输出:True
browser.close()