CloakHQ/CloakBrowser · 上手攻略

• 仓库：CloakHQ/CloakBrowser
• 链接：https://github.com/CloakHQ/CloakBrowser
• 分类：engineering
• 作者：Tom
• 更新：2026-07-08

这是什么

CloakBrowser 是一款"隐身 Chromium"浏览器，专为绕过反机器人检测而设计。与其他工具通过 JavaScript 注入或配置参数"伪装"成浏览器不同，CloakBrowser 在 C++ 源码层面对 Chromium 打补丁，将修改直接编译进二进制，让检测系统看到的是一个"真正的普通浏览器"——因为它本质上就是。

核心卖点：30/30 反检测测试全通过，reCAPTCHA v3 得分 0.9（人类级别），Cloudflare Turnstile 自动通过。

支持 Python（pip）和 JavaScript（npm）两种 SDK，均为 Playwright/Puppeteer 的直接替代品，API 完全兼容，迁移成本极低。

解决什么问题

当前主流反爬/反Bot方案（DuckDuckGo Browser Detection、FingerprintJS、Cloudflare Bot Management、Browsescan 等）检测的核心信号包括：

• navigator.webdriver = true（自动化标志）
• HeadlessChrome UA 字符串泄漏
• Canvas / WebGL 指纹异常
• 插件列表为空（正常 Chrome 有 5 个插件）
• WebRTC IP 泄漏（通过代理时真实 IP 暴露）
• TLS 指纹不匹配
• window.chrome 对象缺失

传统方案（playwright-stealth、undetected-chromedriver、puppeteer-extra）通过 JS 注入或 Chrome 参数绕过检测，但有两个致命缺陷：

1. Chrome 每次更新都可能让这些 hack 失效
2. 检测系统可以识别 JS 注入行为本身

CloakBrowser 用 66 个 C++ 源码补丁从根本上消灭了所有可检测信号，补丁随 Chromium 版本更新同步维护，理论上与上游 Chrome 一样持久。

快速安装

Python（pip）

pip install cloakbrowser

# 可选：GeoIP 依赖（根据代理 IP 自动设置时区和语言）
pip install "cloakbrowser[geoip]"

JavaScript / Node.js

# Playwright 生态
npm install cloakbrowser playwright-core

# Puppeteer 生态
npm install cloakbrowser puppeteer-core

.NET / C

dotnet add package CloakBrowser

注意：.NET 客户端为社区维护，基于 Microsoft.Playwright。

Docker 快速体验（无需本地安装）

docker run --rm cloakhq/cloakbrowser cloaktest

核心用法

3 行代码迁移 Playwright（推荐）

现有 Playwright 代码：

from playwright.sync_api import sync_playwright
pw = sync_playwright().start()
browser = pw.chromium.launch()

替换为：

from cloakbrowser import launch
browser = launch()  # 完全兼容 Playwright API

替换后所有 browser.new_page()、page.goto()、page.click() 等 Playwright API 均无需修改。

基础用法

from cloakbrowser import launch

browser = launch()           # 无头模式，默认开启全部隐身配置
page = browser.new_page()
page.goto("https://example.com")
print(page.title())
browser.close()

带代理 + GeoIP（推荐用于反Bot严格站点）

browser = launch(
    proxy="http://user:pass@residential-proxy:port",  # 住宅代理，不是数据中心 IP
    geoip=True,    # 自动从代理 IP 推断时区和语言
    headless=False,  # 部分站点检测无头模式
    humanize=True,   # 人类行为模拟（鼠标曲线、键盘节奏、滚动）
)

humanize 行为模拟

humanize=True 开启后，所有交互自动具备： - Bézier 曲线鼠标移动（非直线） - 逐字符键盘输入（带随机延迟） - 真实滚动模式（不是一键滚到底）

browser = launch(humanize=True)
# 也可以用预设
browser = launch(humanize=True, human_preset="careful")  # 更慢、更谨慎

持久化会话（保持登录状态）

from cloakbrowser import launch_persistent_context

# 首次运行，保存 cookies 和 localStorage
ctx = launch_persistent_context("./my-profile")
page = ctx.new_page()
page.goto("https://example.com")
ctx.close()  # 自动保存到 ./my-profile

# 下次运行，自动恢复登录状态
ctx = launch_persistent_context("./my-profile")

异步用法（Python）

import asyncio
from cloakbrowser import launch_async

async def main():
    browser = await launch_async()
    page = await browser.new_page()
    await page.goto("https://example.com")
    print(await page.title())
    await browser.close()

asyncio.run(main())

JavaScript / TypeScript

import { launch } from 'cloakbrowser';

const browser = await launch({
    proxy: 'http://user:pass@proxy:port',
    geoip: true,
    humanize: true,
});
const page = await browser.newPage();
await page.goto('https://example.com');
await browser.close();

典型适用场景

场景 1：绕过 Cloudflare Turnstile 自动验证

Cloudflare Turnstile 是替代 reCAPTCHA 的无声验证方案，CloakBrowser v0.4.8 实测自动通过：

browser = launch(headless=False)
page = browser.new_page()
page.goto("https://challenged-site.com")  # Turnstile 自动解析，无需手动点击

场景 2：reCAPTCHA v3 高分通过

browser = launch(license_key="cb_xxxx")  # Pro 版本
page = browser.new_page()
page.goto("https://example.com")
# reCAPTCHA v3 得分：0.9（人类级别，已在服务器端验证）

场景 3：AI Agent 浏览器自动化

from cloakbrowser import launch

browser = launch(humanize=True)  # AI agent 模拟人类操作
page = browser.new_page()
page.goto("https://linkedin.com/search/results/people/")
# 配合 browser-use、Stagehand、LangChain 等 AI 框架使用

场景 4：电商价格监控 / 机票查询

电商和旅游网站对自动化访问极为敏感：

browser = launch(
    proxy="http://residential-proxy:port",
    geoip=True,  # 自动匹配代理 IP 对应的时区和语言
    humanize=True,
)
page = browser.new_page()
page.goto("https://flights.example.com/search?from=PEK&to=SHA")

版本与 Pro 订阅

⚠️ 版本标注说明：Free 版本基于 v146，Pro 基于 v148（截至 2026-07-05）。反Bot 检测更新频繁，Free 版本二进制会逐渐失效，建议生产环境使用 Pro。

Pro 激活方式（任选其一）： - 环境变量：export CLOAKBROWSER_LICENSE_KEY=cb_xxxxxxxx - 参数传入：launch(license_key="cb_xxxxxxxx") - 文件路径：写入 ~/.cloakbrowser/license.key

坑与注意

与同类对比

结论：CloakBrowser 是目前唯一同时做到"C++ 源码级补丁 + Playwright API 完全兼容 + 主动持续维护"的商业级解决方案。Free 版本够用但需定期更新，Pro 版本适合有稳定产出需求的自动化场景。

一句话推荐结论

如果你的爬虫、自动化测试、AI Agent 浏览器任务被 Cloudflare / reCAPTCHA / FingerprintJS 频繁拦截，换用 CloakBrowser 只需改 3 行代码——但换来的是从"Bot 得 0.1 分"到"被当成真正人类得 0.9 分"的质变，生产级稳定运行。

信息来源

• GitHub README：https://github.com/CloakHQ/CloakBrowser
• PyPI：https://pypi.org/project/cloakbrowser/
• npm：https://www.npmjs.com/package/cloakbrowser
• Docker Hub：https://hub.docker.com/r/cloakhq/cloakbrowser
• Pro 版本官网：https://cloakbrowser.dev
• 检测结果实测（BrowserScan）：https://browserscan.net
• 检测结果实测（FingerprintJS）：https://demo.fingerprint.com