能够通过所有机器人检测测试的隐蔽版 Chromium。
|
这不是打过补丁的配置。也不是 JS 注入。这是一个真正的 Chromium 二进制文件,其指纹在 C++ 源代码级别进行了修改。反机器人系统将其评分为普通浏览器——因为它就是一个普通浏览器。
|
Cloudflare Turnstile — 3 live tests passing (headed mode, macOS)
Python 和 JavaScript 的 Playwright/Puppeteer 直接替代方案。
相同的 API,相同的代码——只需更改导入即可。3 行代码,30 秒即可解除封锁。
- **49 个源代码级别的 C++ 补丁** — canvas、WebGL、audio、fonts、GPU、screen、WebRTC、network timing、automation signals、CDP input behavior
- **`humanize=True`** — 类人的鼠标曲线、键盘敲击时间和滚动模式。一个标志,即可通过行为检测
- **0.9 的 reCAPTCHA v3 分数** — 人类级别,服务器验证
- **通过 Cloudflare Turnstile**、FingerprintJS、BrowserScan — 在 30 多个检测网站上测试通过
- **自动更新的二进制文件** — 后台检查更新,始终使用最新的隐蔽构建版本
- **`pip install cloakbrowser`** 或 **`npm install cloakbrowser`** — 二进制文件自动下载,零配置
- **免费且开源** — 无需订阅,无使用限制
**立即尝试** — 无需安装:
```
docker run --rm cloakhq/cloakbrowser cloaktest
```
**Python:**
```
from cloakbrowser import launch
browser = launch()
page = browser.new_page()
page.goto("https://protected-site.com") # no more blocks
browser.close()
```
**JavaScript (Playwright):**
```
import { launch } from 'cloakbrowser';
const browser = await launch();
const page = await browser.newPage();
await page.goto('https://protected-site.com');
await browser.close();
```
也适用于 Puppeteer:`import { launch } from 'cloakbrowser/puppeteer'`([详情](#puppeteer))
## 安装
**Python:**
```
pip install cloakbrowser
```
**JavaScript / Node.js:**
```
# 使用 Playwright
npm install cloakbrowser playwright-core
# 使用 Puppeteer
npm install cloakbrowser puppeteer-core
```
首次运行时,隐蔽的 Chromium 二进制文件会自动下载(约 200MB,在本地缓存)。
**可选:** 从代理 IP 自动检测时区/语言环境:
```
pip install cloakbrowser[geoip]
```
**从 Playwright 迁移?** 一行代码的更改:
```
- from playwright.sync_api import sync_playwright
- pw = sync_playwright().start()
- browser = pw.chromium.launch()
+ from cloakbrowser import launch
+ browser = launch()
page = browser.new_page()
page.goto("https://example.com")
# ... 其余代码无需修改即可运行
```
## 浏览器配置文件管理器
Multilogin、GoLogin 和 AdsPower 的自托管替代方案。创建具有唯一指纹、代理和持久会话的浏览器配置文件。通过 noVNC 在浏览器中启动并与之交互。
```
docker run -p 8080:8080 -v cloakprofiles:/data cloakhq/cloakbrowser-manager
```
打开 [http://localhost:8080](http://localhost:8080)。创建一个配置文件。点击 **Launch**。完成。
→ **[CloakBrowser Manager](https://github.com/CloakHQ/CloakBrowser-Manager)** — 免费开源 (MIT)
## 最新版本:v0.3.26 (Chromium 146.0.7680.177.4)
- **`launch_context_async()`** — `launch_context()` 的异步版本。将关键字参数转发给 `browser.new_context()` 以设置 `storage_state`、`permissions`、`extra_http_headers`,而无需持久的配置文件文件夹。
- **JS `contextOptions` 逃生舱** — 从 `launchContext()` / `launchPersistentContext()` 将任意选项(包括 `storageState`)转发给 Playwright 的 `newContext()`。
- **原生 SOCKS5 代理** — `proxy="socks5://user:pass@host:port"` 可在所有启动函数中直接使用,支持 Python + JS。QUIC/HTTP3 通过 UDP ASSOCIATE 隧道穿透 SOCKS5。
- **Chromium 146 升级** — 将所有补丁从 145.0.7632.x 变基到 146.0.7680.177
- **57 个指纹补丁** — 额外的检测向量覆盖(WebAuthn、AAC audio、window position)以及 WebGL/canvas 一致性修复
- **WebRTC IP 伪装** — `--fingerprint-webrtc-ip=auto` 解析代理的出口 IP 并伪装 WebRTC ICE candidates。在使用 `geoip=True` 时自动注入(无需额外的网络调用)
- **代理信号移除** — DNS/connect/SSL 时间归零,代理缓存头被剥离,Proxy-Connection 头泄漏被移除
- **`cloakserve` CDP 多路复用器** — 重写为具有每个连接独立指纹种子的多连接 CDP 代理
- **Humanize CDP 隔离** — 键盘事件现在使用隔离的世界和受信任的派发,以获得更好的行为隐蔽性
- **`humanize=True`** — 一个标志即可使所有鼠标、键盘和滚动交互表现得像真实用户。贝塞尔曲线、逐字符输入、逼真的滚动模式
- **零标志即可隐身** — 二进制文件在启动时自动生成随机指纹种子。无需配置
- **通过代理 IP 设置时区和语言环境** — `launch(proxy="...", geoip=True)` 自动检测时区和语言环境
- **持久配置文件** — `launch_persistent_context()` 跨会话保留 cookies 和 localStorage,绕过隐身检测
有关详细信息,请参阅完整的 [CHANGELOG.md](CHANGELOG.md)。
## 为什么选择 CloakBrowser?
- **配置级别的补丁容易失效** — `playwright-stealth`、`undetected-chromedriver` 和 `puppeteer-extra` 注入 JavaScript 或调整标志。每次 Chrome 更新都会破坏它们。反机器人系统甚至能检测到补丁本身。
- **CloakBrowser 修改 Chromium 源代码** — 指纹在 C++ 级别被修改,并编译进二进制文件。检测网站看到的是一个真实的浏览器,因为它*就是*一个真实的浏览器。
- **源代码级别的隐身** — C++ 补丁在二进制级别处理指纹(GPU、screen、UA、硬件报告)。没有 JavaScript 注入,没有配置层面的破解。大多数隐身工具只在表面进行修补。
- **到处都是相同的行为** — 在本地、Docker 和 VPS 中的工作方式完全相同。不需要特定于环境的补丁或配置。
- **适用于 AI 代理和自动化框架** — browser-use、Crawl4AI、Scrapling、Stagehand、LangChain、Selenium 等的即插即用隐身方案。请参阅 [集成](#framework-integrations)。
CloakBrowser 并不解决验证码——它从一开始就防止它们出现。没有内置的验证码解决服务,也没有代理轮换——请自带代理,使用你已经熟悉的 Playwright API。
## 测试结果
所有测试均已通过实时检测服务验证。上次测试时间:2026 年 4 月 (Chromium 146)。
| 检测服务 | 原版 Playwright | CloakBrowser | 备注 |
|---|---|---|---|
| **reCAPTCHA v3** | 0.1 (bot) | **0.9** (人类) | 服务器端验证 |
| **Cloudflare Turnstile** (非交互式) | 失败 | **通过** | 自动解决 |
| **Cloudflare Turnstile** (托管式) | 失败 | **通过** | 单击即可 |
| **ShieldSquare** | 阻止 | **通过** | 生产站点 |
| **FingerprintJS** 机器人检测 | 检测到 | **通过** | demo.fingerprint.com |
| **BrowserScan** 机器人检测 | 检测到 | **正常** (4/4) | browserscan.net |
| **bot.incolumitas.com** | 13 项失败 | **1 项失败** | 仅限 WEBDRIVER 规范 |
| **deviceandbrowserinfo.com** | 6 个真实标志 | **0 个真实标志** | `isBot: false` |
| `navigator.webdriver` | `true` | **`false`** | 源代码级别补丁 |
| `navigator.plugins.length` | 0 | **5** | 真实插件列表 |
| `window.chrome` | `undefined` | **`object`** | 像真正的 Chrome 一样存在 |
| UA string | `HeadlessChrome` | **`Chrome/146.0.0.0`** | 没有无头模式泄漏 |
| CDP 检测 | 检测到 | **未检测到** | `isAutomatedWithCDP: false` |
| TLS 指纹 | 不匹配 | **与 Chrome 相同** | ja3n/ja4/akamai 匹配 |
| | | **在 30 多个检测网站上测试通过** | |
### 证明
reCAPTCHA v3 score 0.9 — server-side verified (human-level)
Cloudflare Turnstile non-interactive challenge — auto-resolved
BrowserScan bot detection — NORMAL (4/4 checks passed)
FingerprintJS web-scraping demo — data served, not blocked
deviceandbrowserinfo.com behavioral bot detection — "You are human!" with humanize=True (24/24 signals passed)
## 比较
| 特性 | Playwright | playwright-stealth | undetected-chromedriver | Camoufox | CloakBrowser |
|---|---|---|---|---|---|
| reCAPTCHA v3 分数 | 0.1 | 0.3-0.5 | 0.3-0.7 | 0.7-0.9 | **0.9** |
| Cloudflare Turnstile | 失败 | 有时通过 | 有时通过 | 通过 | **通过** |
| 补丁级别 | 无 | JS 注入 | 配置补丁 | C++ (Firefox) | **C++ (Chromium)** |
| 在 Chrome 更新后不受影响 | 不适用 | 经常失效 | 经常失效 | 是 | **是** |
| 维护状态 | 是 | 停滞 | 停滞 | 不稳定 | **活跃** |
| 浏览器引擎 | Chromium | Chromium | Chrome | Firefox | **Chromium** |
| Playwright API | 原生 | 原生 | 否 | 否 | **原生** |
## 工作原理
CloakBrowser 是一个围绕定制构建的 Chromium 二进制文件的轻量级包装器:
1. **你安装** → `pip install cloakbrowser` 或 `npm install cloakbrowser`
2. **首次启动** → 为你的平台自动下载二进制文件 (Chromium 146)
3. **每次启动** → Playwright 或 Puppeteer 使用我们的二进制文件 + 隐身参数启动
4. **你编写代码** → 标准的 Playwright/Puppeteer API,无需学习新内容
该二进制文件包含 49 个源代码级别的补丁,涵盖 canvas、WebGL、audio、fonts、GPU、screen properties、WebRTC、network timing、hardware reporting、automation signal removal 和 CDP input behavior mimicking。
这些都编译到了 Chromium 二进制文件中——而不是通过 JavaScript 注入,也不是通过标志设置。
二进制文件下载通过 SHA-256 校验和进行验证,以确保完整性。
## API
### `launch()`
```
from cloakbrowser import launch
# 基本 — 无头模式,默认 stealth 配置
browser = launch()
# 有头模式(可见浏览器窗口)
browser = launch(headless=False)
# 使用代理(HTTP 或 SOCKS5)
browser = launch(proxy="http://user:pass@proxy:8080")
browser = launch(proxy="socks5://user:pass@proxy:1080")
# 使用 proxy dict(设置绕过,独立认证字段)
browser = launch(proxy={"server": "http://proxy:8080", "bypass": ".google.com", "username": "user", "password": "pass"})
# 使用额外 Chrome 参数
browser = launch(args=["--disable-gpu"])
# 设置时区和语言区域(设置二进制标志 — 无法被 CDP 检测到模拟)
browser = launch(timezone="America/New_York", locale="en-US")
# 根据代理 IP 自动检测时区/语言区域(需要:pip install cloakbrowser[geoip])
# 同时自动注入 --fingerprint-webrtc-ip 以防止 WebRTC IP 泄露(无需额外开销)
# 注意:会通过你的代理发起 HTTP 请求以解析出口 IP(ipify.org, checkip.amazonaws.com)
browser = launch(proxy="http://proxy:8080", geoip=True)
# 显式指定的时区/语言区域始终优先于自动检测
browser = launch(proxy="http://proxy:8080", geoip=True, timezone="Europe/London")
# 仅伪装 WebRTC IP(无需 geoip 依赖 — 通过代理的 HTTP 请求解析出口 IP)
browser = launch(proxy="http://proxy:8080", args=["--fingerprint-webrtc-ip=auto"])
# 显式 WebRTC IP(无网络请求)
browser = launch(proxy="http://proxy:8080", args=["--fingerprint-webrtc-ip=1.2.3.4"])
# 仿人类的鼠标、键盘和滚动行为
browser = launch(humanize=True)
# 伴随更缓慢、更刻意的移动
browser = launch(humanize=True, human_preset="careful")
# 不带默认 stealth 参数(使用自定义的指纹标志)
browser = launch(stealth_args=False, args=["--fingerprint=12345"])
```
返回一个标准的 Playwright `Browser` 对象。所有 Playwright 方法均可使用:`new_page()`、`new_context()`、`close()` 等。
### `launch_async()`
```
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())
```
### `launch_context()`
这是一个便利函数,通过一次调用即可创建浏览器 + 上下文,并设置 user agent、viewport、locale 和 timezone:
```
from cloakbrowser import launch_context
context = launch_context(
user_agent="Custom UA",
viewport={"width": 1920, "height": 1080},
locale="en-US",
timezone="America/New_York",
)
page = context.new_page()
page.goto("https://protected-site.com")
context.close()
```
额外的关键字参数会被转发给 Playwright 的 `browser.new_context()` — 使用它来设置 `storage_state`、`permissions`、`extra_http_headers` 等,而无需持久的配置文件文件夹:
```
from cloakbrowser import launch_context
# 从 JSON 文件恢复保存的会话(cookies, localStorage)
context = launch_context(storage_state="state.json")
page = context.new_page()
page.goto("https://example.com")
# 保存状态以供下次运行使用
context.storage_state(path="state.json")
context.close()
```
### `launch_context_async()`
`launch_context()` 的异步版本。具有相同的签名和关键字参数转发:
```
import asyncio
from cloakbrowser import launch_context_async
async def main():
ctx = await launch_context_async(storage_state="state.json")
page = await ctx.new_page()
await page.goto("https://example.com")
await ctx.storage_state(path="state.json")
await ctx.close()
asyncio.run(main())
```
### `launch_persistent_context()`
与 `launch_context()` 相同,但带有持久的用户配置文件。Cookies、localStorage 和缓存在会话之间得以保留。
在以下情况下使用此选项:
- 跨运行**保持登录状态**(cookies/sessions 在重启后依然保留)
- **绕过隐身检测**(一些网站会标记空的、临时的配置文件)
- **加载 Chrome 扩展程序**(扩展程序只能从真实的用户数据目录中运行)
- **建立自然的浏览历史**(缓存字体、service workers、IndexedDB 随时间累积,使配置文件看起来更真实)
```
from cloakbrowser import launch_persistent_context
# 首次运行 — 创建配置文件
ctx = launch_persistent_context("./my-profile", headless=False)
page = ctx.new_page()
page.goto("https://protected-site.com")
ctx.close() # profile saved
# 后续运行 — 自动恢复 cookies, localStorage
ctx = launch_persistent_context("./my-profile", headless=False)
```
支持与 `launch_context()` 相同的所有选项:`proxy`、`user_agent`、`viewport`、`locale`、`timezone`、`color_scheme`、`geoip`。
异步版本:`launch_persistent_context_async()`。
**存储配额与检测的权衡:** 默认情况下,二进制文件会对存储配额进行标准化以通过 FingerprintJS,这会阻止报告非隐身配额值的持久上下文。这意味着对隐身模式进行惩罚的检测服务(如 BrowserScan 的 `notPrivate` 检查,-10 分)仍然会对其进行标记。如果你的目标网站惩罚隐身模式但不使用 FingerprintJS,请设置更高的配额以显示为常规配置文件:
```
ctx = launch_persistent_context("./my-profile", args=["--fingerprint-storage-quota=5000"])
```
| 配额设置 | FingerprintJS | BrowserScan `notPrivate` |
|---|---|---|
| 默认 (自动, ~500MB) | 通过 | -10 (被标记为隐身) |
| `--fingerprint-storage-quota=5000` | 可能触发检测 | 通过 (显示为非隐身) |
### CLI
从命令行预下载二进制文件或检查安装:
```
python -m cloakbrowser install # Download binary with progress output
python -m cloakbrowser info # Show version, path, platform
python -m cloakbrowser update # Check for and download newer binary
python -m cloakbrowser clear-cache # Remove cached binaries
```
### 实用工具函数
```
from cloakbrowser import binary_info, clear_cache, ensure_binary
# 检查二进制文件安装状态
print(binary_info())
# {'version': '146.0.7680.177.3', 'platform': 'linux-x64', 'installed': True, ...}
# 强制重新下载
clear_cache()
# 预下载二进制文件(例如,在 Docker 构建期间)
ensure_binary()
```
## JavaScript / Node.js API
CloakBrowser 附带一个包含完整类型定义的 TypeScript 包。请选择 Playwright 或 Puppeteer——底层使用相同的隐身二进制文件。
### Playwright (默认)
```
import { launch, launchContext, launchPersistentContext } from 'cloakbrowser';
// Basic
const browser = await launch();
// With options
const browser = await launch({
headless: false,
proxy: 'http://user:pass@proxy:8080',
args: ['--fingerprint=12345'],
timezone: 'America/New_York',
locale: 'en-US',
humanize: true,
});
// Convenience: browser + context in one call
const context = await launchContext({
userAgent: 'Custom UA',
viewport: { width: 1920, height: 1080 },
locale: 'en-US',
timezone: 'America/New_York',
});
const page = await context.newPage();
// Persistent profile — cookies/localStorage survive restarts, avoids incognito detection
const ctx = await launchPersistentContext({
userDataDir: './chrome-profile',
headless: false,
proxy: 'http://user:pass@proxy:8080',
});
```
所有 Python 选项均适用于 JS:使用 `stealthArgs: false` 禁用默认值,使用 `geoip: true` 从代理 IP 自动检测时区/语言环境。
### Puppeteer
```
import { launch } from 'cloakbrowser/puppeteer';
const browser = await launch({ headless: true });
const page = await browser.newPage();
await page.goto('https://example.com');
await browser.close();
```
### 实用工具函数
```
import { ensureBinary, clearCache, binaryInfo } from 'cloakbrowser';
// Pre-download binary (e.g., during Docker build)
await ensureBinary();
// Check installation status
console.log(binaryInfo());
// Force re-download
clearCache();
```
## 人类行为
传入 `humanize=True` 可使所有鼠标、键盘和滚动交互与真实用户难以区分。所有 Playwright 调用(`page.click()`、`page.fill()`、`page.type()`、`page.mouse.*`、`page.keyboard.*`、Locator API)和 Puppeteer 调用(`page.click()`、`page.type()`、`page.mouse.*`、`page.keyboard.*`、ElementHandle API)都会自动替换为类人的等效操作。无需更改代码。
```
browser = launch(humanize=True)
page = browser.new_page()
page.goto("https://example.com")
page.locator("#email").fill("user@example.com") # per-character timing, thinking pauses
page.locator("button[type=submit]").click() # Bézier curve, realistic aim point
```
```
// Playwright
import { launch } from 'cloakbrowser';
const browser = await launch({ humanize: true });
```
```
// Puppeteer
import { launch } from 'cloakbrowser/puppeteer';
const browser = await launch({ humanize: true });
```
**变化之处:**
| 交互 | 默认 | 启用 `humanize=True` 后 |
|---|---|---|
| 鼠标移动 | 瞬间移动 | 带有缓动和轻微过冲的贝塞尔曲线 |
| 点击 | 瞬间完成 | 逼真的瞄准点 + 按住时长 |
| 键盘 | 瞬间填充 | 逐字符定时、思考停顿、偶尔的拼写错误及自我纠正 |
| 滚动 | 跳跃 | 加速 → 巡航 → 减速的微步进 |
| `fill()` | 瞬间设置值 | 清除现有内容,逐个字符输入 |
**预设** — `default`(正常速度)或 `careful`(较慢、更谨慎、操作之间有空闲的微动作):
```
browser = launch(humanize=True, human_preset="careful")
```
```
const browser = await launch({ humanize: true, humanPreset: 'careful' });
```
**自定义配置** — 覆盖任何参数:
```
browser = launch(humanize=True, human_config={
"mistype_chance": 0.05, # 5% typo rate with self-correction
"typing_delay": 100, # slower typing (ms per character)
"idle_between_actions": True, # micro-movements between clicks
"idle_between_duration": [0.3, 0.8], # idle duration range (seconds)
})
```
```
const browser = await launch({
humanize: true,
humanConfig: {
mistype_chance: 0.05,
typing_delay: 100,
idle_between_actions: true,
idle_between_duration: [0.3, 0.8],
}
});
```
如果你需要特定的原始速度调用,可以在 `page._original` 访问未打补丁的原始 Playwright 页面。
## 配置
| 环境变量 | 默认值 | 描述 |
|---|---|---|
| `CLOAKBROWSER_BINARY_PATH` | — | 跳过下载,使用本地 Chromium 二进制文件 |
| `CLOAKBROWSER_CACHE_DIR` | `~/.cloakbrowser` | 二进制文件缓存目录 |
| `CLOAKBROWSER_DOWNLOAD_URL` | `cloakbrowser.dev` | 二进制文件的自定义下载 URL |
| `CLOAKBROWSER_AUTO_UPDATE` | `true` | 设置为 `false` 以禁用后台更新检查 |
| `CLOAKBROWSER_SKIP_CHECKSUM` | `false` | 设置为 `true` 以跳过下载后的 SHA-256 验证 |
## 指纹管理
该二进制文件**默认处于隐身状态**——无需任何标志。它会在启动时自动生成一个随机指纹种子,并伪造所有可检测的值(GPU、硬件规格、屏幕分辨率、canvas、WebGL、audio、fonts)。每次启动都会产生一个全新的、连贯的身份。
**指纹识别的工作原理:**
| 场景 | 会发生什么 |
|----------|-------------|
| **无标志** | 启动时自动生成随机种子。GPU、屏幕、硬件规格和所有噪点补丁都会自动进行伪造。每次启动都是全新的身份。 |
| **`--fingerprint=seed`** | 基于种子的确定性身份。相同的种子 = 跨启动的指纹相同。将其用于会话持久性(回访的访问者)。 |
| **`--fingerprint=seed` + 显式标志** | 显式标志覆盖单独的自动生成值。种子填充其他所有内容。 |
二进制文件在编译时检测其平台——macOS 二进制文件报告自身为带有 Apple GPU 的 macOS,Linux 二进制文件报告自身为带有 NVIDIA GPU 的 Linux。**包装器**在 Linux 上通过传递 `--fingerprint-platform=windows` 来覆盖此设置,因此会话显示为 Windows 桌面(更常见的指纹,更难被聚类)。在直接运行二进制文件时,请使用 `--fingerprint-platform` 进行跨平台伪装。
### 默认指纹
每次 `launch()` 调用都会自动设置这些参数。**包装器**应用平台感知的默认值——在 Linux 上,它伪装为 Windows 以获得更常见的指纹;在 macOS 上,它作为原生的 Mac 浏览器运行:
| 标志 | Linux/Windows 默认值 | macOS 默认值 | 控制项 |
|------|--------------|---------------|----------|
| `--fingerprint` | 随机 (10000–99999) | 随机 (10000–99999) | canvas、WebGL、audio、fonts、client rects 的主种子 |
| `--fingerprint-platform` | `windows` | `macos` | `navigator.platform`、User-Agent OS、GPU 池选择 |
二进制文件从种子自动生成其他所有内容:GPU、hardware concurrency、device memory 和屏幕分辨率。每个种子都会产生一个独特且一致的指纹。如果需要,可使用显式标志进行覆盖。
### 附加标志
受二进制文件支持但**默认未设置**——通过 `args` 传递以进行自定义:
| 标志 | 控制项 |
|------|----------|
| `--fingerprint-gpu-vendor` | WebGL `UNMASKED_VENDOR_WEBGL`(从种子 + 平台自动生成) |
| `--fingerprint-gpu-renderer` | WebGL `UNMASKED_RENDERER_WEBGL`(从种子 + 平台自动生成) |
| `--fingerprint-hardware-concurrency` | `navigator.hardwareConcurrency`(自动生成:`8`) |
| `--fingerprint-device-memory` | `navigator.deviceMemory`,单位为 GB(自动生成:`8`) |
| `--fingerprint-screen-width` | 屏幕宽度(自动生成:Win/Linux 为 `1920`,macOS 为 `1440`) |
| `--fingerprint-screen-height` | 屏幕高度(自动生成:Win/Linux 为 `1080`,macOS 为 `900`) |
| `--fingerprint-brand` | 浏览器品牌:`Chrome`、`Edge`、`Opera`、`Vivaldi` |
| `--fingerprint-brand-version` | 品牌版本 (UA + Client Hints) |
| `--fingerprint-platform-version` | Client Hints 平台版本 |
| `--fingerprint-location` | 地理位置坐标 |
| `--fingerprint-timezone` | 时区(例如 `America/New_York`) |
| `--fingerprint-locale` | 语言环境(例如 `en-US`) |
| `--fingerprint-storage-quota` | 覆盖存储配额,单位为 MB — 影响 `storage.estimate()`、`storageBuckets` 和旧版 webkit API。设置 `--fingerprint` 时自动标准化 |
| `--fingerprint-taskbar-height` | 覆盖任务栏高度(二进制默认值:Win=48, Mac=95, Linux=0) |
| `--fingerprint-fonts-dir` | 包含目标平台字体的目录路径(参见 [Linux 上的字体设置](#font-setup-on-linux)) |
| `--fingerprint-webrtc-ip` | WebRTC ICE 候选 IP 替换。使用 `auto` 可从代理出口 IP 解析(通过代理发出 HTTP 调用),或传递显式 IP。使用 `geoip=True` 时自动注入 |
| `--fingerprint-noise=false` | 禁用噪点注入(canvas、WebGL、audio、client rects),同时保持确定性指纹种子处于活动状态 |
| `--enable-blink-features=FakeShadowRoot` | 访问关闭的 shadow DOM 元素 |
### Linux 上的字体设置
**强效反机器人网站(Kasada、Akamai)需要。** 这些系统在隐藏的 canvas 上渲染表情符号,并对像素输出进行哈希处理。最小化的 Linux 环境(Docker、云虚拟机)通常缺少表情符号和扩展字体,从而产生与任何真实浏览器都不匹配的哈希值。安装标准字体包以解决此问题:
```
sudo apt install -y fonts-noto-color-emoji fonts-freefont-ttf fonts-unifont \
fonts-ipafont-gothic fonts-wqy-zenhei fonts-tlwg-loma-otf
```
Docker 镜像 (`cloakhq/cloakbrowser`) 预装了这些字体。如果你直接在 Linux 服务器上或在自定义 Docker 镜像中运行二进制文件,请手动安装它们。
**可选:用于 CreepJS 字体枚举的 Windows 字体。** 上面的软件包修复了反机器人 canvas 检查,但不会提高你的 CreepJS 字体分数。为此,你需要 Windows 机器 `C:\Windows\Fonts\` 目录中的真正 Windows 字体(Segoe UI、Calibri、Bahnschrift 等) — `ttf-mscorefonts-installer` 只有旧的 XP 时代字体,这远远不够。
```
mkdir -p ~/.local/share/fonts/windows
cp /path/to/windows/fonts/*.ttf ~/.local/share/fonts/windows/
cp /path/to/windows/fonts/*.TTF ~/.local/share/fonts/windows/
fc-cache -f # mandatory for manually copied fonts
```
```
browser = launch(
args=["--fingerprint-fonts-dir=/home/user/.local/share/fonts/windows"],
)
```
### 示例
```
# 固定 Seed 以保持持久身份
browser = launch(args=["--fingerprint=42069"])
# 完全控制 — 禁用默认设置,手动配置所有内容
browser = launch(stealth_args=False, args=[
"--fingerprint=42069",
"--fingerprint-platform=windows",
])
# 覆盖 GPU 以伪装成特定机器
browser = launch(args=[
"--fingerprint-gpu-vendor=Intel Inc.",
"--fingerprint-gpu-renderer=Intel Iris OpenGL Engine",
])
```
## 示例
**Python** — 请参阅 [`examples/`](examples/):
- [`basic.py`](examples/basic.py) — 启动并加载页面
- [`persistent_context.py`](examples/persistent_context.py) — 带有 cookie/localStorage 持久化的持久配置文件
- [`recaptcha_score.py`](examples/recaptcha_score.py) — 检查你的 reCAPTCHA v3 分数
- [`stealth_test.py`](examples/stealth_test.py) — 针对 6 个检测网站运行测试
- [`fingerprint_scan_test.py`](examples/fingerprint_scan_test.py) — 针对 fingerprint-scan.com 和 CreepJS 进行测试
**JavaScript** — 请参阅 [`js/examples/`](js/examples/):
- [`basic-playwright.ts`](js/examples/basic-playwright.ts) — Playwright 启动并加载
- [`basic-puppeteer.ts`](js/examples/basic-puppeteer.ts) — Puppeteer 启动并加载
- [`stealth-test.ts`](js/examples/stealth-test.ts) — 针对 6 个检测网站运行测试
### 框架集成
CloakBrowser 适用于任何使用 Playwright 或 Chromium 的框架:
```
# 选项 1:框架直接启动我们的二进制文件(Selenium, Stagehand, UC)
from cloakbrowser.download import ensure_binary
from cloakbrowser.config import get_default_stealth_args
binary_path = ensure_binary() # auto-downloads if needed
stealth_args = get_default_stealth_args() # all fingerprint flags
# 选项 2:CloakBrowser 优先启动,框架通过 CDP 连接(browser-use, Crawl4AI, Scrapling)
from cloakbrowser import launch_async
browser = await launch_async(args=["--remote-debugging-port=9242"])
# 将你的框架连接到 http://127.0.0.1:9242 — 所有 stealth 标志均已设置
# 注意:humanize 需要使用包装器(见下文)
```
| 框架 | Stars | 语言 | 示例 |
|-----------|-------|----------|---------|
| [browser-use](https://github.com/browser-use/browser-use) | 70K | Python | [`browser_use_example.py`](examples/integrations/browser_use_example.py) |
| [Crawl4AI](https://github.com/unclecode/crawl4ai) | 58K | Python | [`crawl4ai_example.py`](examples/integrations/crawl4ai_example.py) |
| [Crawlee](https://github.com/apify/crawlee-python) | 8.6K | Python | [`crawlee_example.py`](examples/integrations/crawlee_example.py) |
| [Scrapling](https://github.com/D4Vinci/Scrapling) | 21K | Python | [`scrapling_example.py`](examples/integrations/scrapling_example.py) |
| [Stagehand](https://github.com/browserbase/stagehand) | 21K | TypeScript | [`stagehand.ts`](js/examples/stagehand.ts) |
| [LangChain](https://github.com/langchain-ai/langchain) | 100K+ | Python | [`langchain_loader.py`](examples/integrations/langchain_loader.py) |
| [Selenium](https://github.com/SeleniumHQ/selenium) | — | Python | [`selenium_example.py`](examples/integrations/selenium_example.py) |
| [undetected-chromedriver](https://github.com/ultrafunkamsterdam/undetected-chromedriver) | 12K | Python | [`undetected_chromedriver.py`](examples/integrations/undetected_chromedriver.py) |
| [agent-browser](https://github.com/nichochar/agent-browser) | — | Shell | [`agent_browser.sh`](examples/integrations/agent_browser.sh) |
### 部署集成
| 平台 | 示例 |
|----------|---------|
| [AWS Lambda](https://aws.amazon.com/lambda/) | [`aws_lambda/`](examples/integrations/aws_lambda/) — Lambda(容器镜像)中的一次性抓取 |
## 平台
| 平台 | Chromium | 补丁数 | 状态 |
|---|---|---|---|
| Linux x86_64 | 146 | 57 | ✅ 最新 |
| Linux arm64 (RPi, Graviton) | 146 | 57 | ✅ 最新 |
| macOS arm64 (Apple Silicon) | 145 | 26 | ✅ |
| macOS x86_64 (Intel) | 145 | 26 | ✅ |
| Windows x86_64 | 146 | 57 | ✅ 最新 |
包装器会自动为你的平台下载正确的二进制文件。
**macOS 首次启动:** 二进制文件是临时签名的。首次运行时,macOS Gatekeeper 会阻止它。右键点击该应用 → **打开** → 在对话框中点击 **打开**。这只需要做一次。
## Docker
Docker Hub 上的预构建镜像 — 无需安装,无需设置。
### 快速测试
```
docker run --rm cloakhq/cloakbrowser cloaktest
```
### 运行脚本
```
# 内联脚本
docker run --rm cloakhq/cloakbrowser python -c "
from cloakbrowser import launch
browser = launch()
page = browser.new_page()
page.goto('https://example.com')
print(page.title())
browser.close()
"
# 挂载自定义脚本
docker run --rm -v ./my_script.py:/app/my_script.py cloakhq/cloakbrowser python my_script.py
# 使用代理
docker run --rm cloakhq/cloakbrowser python -c "
from cloakbrowser import launch
browser = launch(proxy='http://user:pass@proxy:8080')
page = browser.new_page()
page.goto('https://example.com')
print(page.title())
browser.close()
"
```
### CDP 服务器模式
启动一个持久的隐身浏览器,并通过 Chrome DevTools Protocol 远程连接到它:
```
docker run -d --name cloak -p 127.0.0.1:9222:9222 cloakhq/cloakbrowser cloakserve
```
然后从你的主机连接:
```
from playwright.sync_api import sync_playwright
pw = sync_playwright().start()
browser = pw.chromium.connect_over_cdp("http://localhost:9222")
page = browser.new_page()
page.goto("https://example.com")
print(page.title())
browser.close()
```
向浏览器传递额外的标志:
停止服务器:
```
docker stop cloak && docker rm cloak
```
### Docker Compose
```
services:
cloakbrowser:
image: cloakhq/cloakbrowser
command: cloakserve
restart: unless-stopped
ports:
- "127.0.0.1:9222:9222"
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:9222/json/version"]
interval: 30s
timeout: 5s
retries: 3
start_period: 10s
```
**每个连接的指纹种子** — 从单个容器运行多个浏览器身份。每个唯一的种子都会生成一个具有独立指纹的单独 Chrome 进程:
```
# 每个 Seed 都会获得唯一的 Canvas 噪点、ClientRects 以及其他浏览器信号
b1 = pw.chromium.connect_over_cdp("http://localhost:9222?fingerprint=11111")
b2 = pw.chromium.connect_over_cdp("http://localhost:9222?fingerprint=22222")
# 通过 query params 完全控制身份
b3 = pw.chromium.connect_over_cdp(
"http://localhost:9222?fingerprint=33333"
"&timezone=Asia/Tokyo&locale=ja-JP&platform=macos"
"&hardware-concurrency=4&device-memory=8"
)
# 根据代理出口 IP 自动检测时区/语言区域
b4 = pw.chromium.connect_over_cdp(
"http://localhost:9222?fingerprint=44444"
"&proxy=http://proxy:8080&geoip=true"
)
```
支持的查询参数:`fingerprint`、`timezone`、`locale`、`platform`、`platform-version`、`brand`、`brand-version`、`gpu-vendor`、`gpu-renderer`、`hardware-concurrency`、`device-memory`、`screen-width`、`screen-height`、`proxy`、`geoip`。相同的种子复用相同的进程(以第一次连接的参数为准)。无种子 = 共享的默认进程(向后兼容)。在 `GET /` 处检查活动进程(返回带有 PIDs、端口和连接数的 JSON)。
**持久配置文件** — 挂载一个卷以在容器重启后保留 cookies 和会话:
```
docker run --rm -v ./my-profile:/profile cloakhq/cloakbrowser python -c "
from cloakbrowser import launch_persistent_context
ctx = launch_persistent_context('/profile')
page = ctx.new_page()
page.goto('https://example.com')
ctx.close()
"
```
使用相同的卷再次运行 — cookies、localStorage 和缓存会自动恢复。
**资源使用:** 空闲时约 190MB 内存,打开 3 个标签页时约 280MB。每增加一个标签页约增加 30MB。
### 使用你自己的镜像进行扩展
```
FROM cloakhq/cloakbrowser
COPY your_script.py /app/
CMD ["python", "your_script.py"]
```
**通过 pip 构建你自己的镜像** — 使用 `python -m cloakbrowser install` 在构建期间下载二进制文件,并可见进度:
```
FROM python:3.12-slim
RUN pip install cloakbrowser && python -m cloakbrowser install
COPY your_script.py /app/
CMD ["python", "/app/your_script.py"]
```
**从源代码构建** — 如果你更喜欢自己构建镜像,还包含了一个 [`Dockerfile`](Dockerfile):
```
docker build -t cloakbrowser .
```
CloakBrowser 在本地、Docker 和 VPS 中的工作方式完全相同。不需要特定于环境的配置。
**注意:** 如果你在带有 uvloop(例如 `uvicorn[standard]`)的 Web 服务器中运行 CloakBrowser,请使用 `--loop asyncio` 以避免子进程管道挂起。
## 故障排除
### 在强效网站 上仍然被阻止?
一些网站即使在我们提供了 C++ 补丁的情况下也能检测到无头模式。请使用带有虚拟显示器的**有头模式**运行:
```
# 安装 Xvfb(虚拟 Framebuffer)
sudo apt install xvfb
# 启动虚拟显示器
Xvfb :99 -screen 0 1920x1080x24 &
export DISPLAY=:99
```
```
from cloakbrowser import launch
# 有头模式 + 住宅代理以实现最大程度的隐蔽
browser = launch(headless=False, proxy="http://your-residential-proxy:port")
page = browser.new_page()
page.goto("https://heavily-protected-site.com") # passes DataDome, etc.
browser.close()
```
这会运行一个渲染在虚拟显示器上的真正有头浏览器——不需要物理显示器。结合下面推荐的配置以实现最大隐身效果。
### 推荐用于反机器人网站的配置
大多数阻止来自于缺少以下三件事之一,而不是因为浏览器指纹检测:
```
browser = launch(
proxy="http://your-residential-proxy:port", # residential IP — datacenter IPs get blocked by reputation alone
geoip=True, # matches timezone + locale to proxy exit IP (without this: UTC + en-US = bot signal)
headless=False, # headed mode — some sites detect headless even with C++ patches
humanize=True, # human-like mouse, keyboard, scroll behavior
)
```
```
const browser = await launch({
proxy: 'http://your-residential-proxy:port',
geoip: true,
headless: false,
humanize: true,
});
```
如果你的代理支持 SOCKS5,请使用它以获得更好的兼容性 — SOCKS5 隧道传输原始 TCP,避免了某些代理在处理 HTTP/2 时出现的 HTTP CONNECT 问题:
```
browser = launch(proxy="socks5://user:pass@proxy:1080", geoip=True, headless=False, humanize=True)
```
如果执行此操作后仍被阻止,请检查下面的字体设置。
### 尽管配置正确,但在 Kasada / Akamai 网站上仍被阻止?
在最小化的 Linux 环境中,缺少字体包会导致 canvas 表情符号渲染产生反机器人系统无法识别的哈希值。在代理、geoip 和有头模式均已正确设置之后,这是在强效网站上被阻止的最常见原因。
请安装上面 [Linux 上的字体设置](#font-setup-on-linux) 中列出的字体包。
### 网站挑战新会话,但在首次访问后正常
一些网站会通过 HTTP/2 挑战没有 cookies 的首次访问者。这会影响所有的 Chromium 浏览器,而不仅仅是 CloakBrowser。请使用持久配置文件一次性预热 cookies,然后跨会话复用:
```
from cloakbrowser import launch_persistent_context
# 首次运行:使用 --disable-http2 进行预热
ctx = launch_persistent_context("./profile", args=["--disable-http2"])
page = ctx.new_page()
page.goto("https://example.com") # warms up cookies
ctx.close()
# 后续运行 — 不再需要 --disable-http2
ctx = launch_persistent_context("./profile")
page = ctx.new_page()
page.goto("https://example.com") # passes with saved cookies
```
```
import { launchPersistentContext } from 'cloakbrowser';
// First run: warm up with --disable-http2
let ctx = await launchPersistentContext({ userDataDir: './profile', args: ['--disable-http2'] });
let page = await ctx.newPage();
await page.goto('https://example.com');
await ctx.close();
// Future runs — no --disable-http2 needed
ctx = await launchPersistentContext({ userDataDir: './profile' });
```
对于无状态/临时用例,`launch(args=["--disable-http2"])` 会强制使用 HTTP/1.1 从而绕过检查。仅在需要的网站上使用此标志——大多数网站使用 HTTP/2 工作正常。如果你的代理支持 SOCKS5,请改用 `proxy="socks5://user:pass@host:port"` — SOCKS5 完全绕过了 HTTP CONNECT。
### 有些功能不正常?请确保你使用的是最新版本
旧版本可能使用了过时的隐身参数或下载了较旧的二进制文件:
```
pip install -U cloakbrowser # Python
npm install cloakbrowser@latest # JavaScript
docker pull cloakhq/cloakbrowser:latest # Docker
```
### 二进制文件下载失败 / 超时
设置自定义下载 URL 或使用本地二进制文件:
```
export CLOAKBROWSER_BINARY_PATH=/path/to/your/chrome
```
### 新更新破坏了某些功能?回滚到以前的版本
安装特定的包装器版本以同时降级包装器及其下载的二进制文件:
```
pip install cloakbrowser==0.3.21 # Python
npm install cloakbrowser@0.3.21 # JavaScript
docker pull cloakhq/cloakbrowser:0.3.21 # Docker
```
每个包装器版本都绑定了其自己的二进制文件版本,因此降级包装器会在下次启动时自动获取匹配的二进制文件。
### macOS: "App 已损坏" 或 Gatekeeper 阻止启动
二进制文件是临时签名的。macOS 会隔离下载的文件。运行一次以清除隔离:
```
xattr -cr ~/.cloakbrowser/chromium-*/Chromium.app
```
### "playwright install" 与 CloakBrowser 二进制文件
你**不需要** `playwright install chromium`。CloakBrowser 会下载它自己的二进制文件。你只需要 Playwright 的系统依赖项:
```
playwright install-deps chromium
```
### macOS: 在某些网站上被阻止,但在 Linux 上通过
macOS 指纹配置文件存在已知的不一致性,会被强效机器人检测捕获。如果某个网站在 macOS 上阻止了你但在 Linux 上正常,请通过传递 `stealth_args=False` 并手动设置带有匹配 GPU 标志的 `--fingerprint-platform=windows` 来切换到 Windows 指纹配置文件(有关完整的标志列表,请参见 [指纹管理](#fingerprint-management))。
### 网站检测到隐身 / 私密浏览模式
默认情况下,`launch()` 会打开一个隐身上下文。一些网站会对此进行惩罚。请使用 `launch_persistent_context()` 来获取带有 cookie 持久性的真实配置文件:
```
from cloakbrowser import launch_persistent_context
ctx = launch_persistent_context("./my-profile", headless=False)
```
如果网站仍然标记隐身模式,请提高存储配额以显示为常规浏览会话。有关这如何影响不同检测服务的详细信息,请参见 [存储配额权衡](#launch_persistent_context)。
### reCAPTCHA v3 分数偏低 (0.1–0.3)
避免使用 `page.wait_for_timeout()` — 它会发送 reCAPTCHA 能检测到的 CDP 协议命令。请改用原生 sleep:
```
# 反面示例 — 发送 CDP 命令,reCAPTCHA 会检测到此行为
page.wait_for_timeout(3000)
# 正面示例 — 对浏览器不可见
import time
time.sleep(3)
```
```
// Bad — sends CDP commands
await page.waitForTimeout(3000);
// Good — invisible to the browser
await new Promise(r => setTimeout(r, 3000));
```
其他最大化 reCAPTCHA 分数的提示:
- **尝试 Patchright 后端** — 在 Playwright 协议层抑制额外的 CDP 自动化信号。使用 `pip install cloakbrowser[patchright]` 安装,然后使用 `launch(backend="patchright")` 或全局设置 `CLOAKBROWSER_BACKEND=patchright`。注意:Patchright 会破坏代理身份验证和 `add_init_script` — 仅在尝试上述步骤后仍然得分较低时才使用它
- **使用 Playwright 而不是 Puppeteer** — Puppeteer 发送更多 reCAPTCHA 能检测到的 CDP 协议流量([详情](#puppeteer))
- **使用住宅代理** — 数据中心 IP 是因为 IP 信誉而被标记的,而不是因为浏览器指纹
- **在触发 reCAPTCHA 之前在页面上停留 15 秒以上** — 短时间访问的分数较低
- **拉开请求间隔** — 同一会话中连续的 `grecaptcha.execute()` 调用会受到惩罚。在有 reCAPTCHA 的页面之间等待 30 秒以上
- **使用固定的指纹种子** 以在会话之间保持一致的设备身份(请参见 [指纹管理](#fingerprint-management))
- **在填写表单时使用 `page.type()` 而不是 `page.fill()`** — `fill()` 直接设置值而没有键盘事件,这会被 reCAPTCHA 的行为分析标记。带有延迟的 `type()` 模拟真实的击键:
page.type("#email", "user@example.com", delay=50)
- **在 reCAPTCHA 检查触发之前尽量减少 `page.evaluate()` 调用** — 每一次调用都会发送 CDP 流量
## 常见问题
**问:这合法吗?**
答:CloakBrowser 是一款基于开源 Chromium 构建的浏览器。我们不容忍非法使用。严禁未经授权的自动化系统、凭证填充和滥用账号创建行为。有关完整条款,请参见 [BINARY-LICENSE.md](https://github.com/CloakHQ/CloakBrowser/blob/main/BINARY-LICENSE.md)。
**问:这跟 Camoufox 有什么区别?**
答:Camoufox 给 Firefox 打补丁。我们给 Chromium 打补丁。Chromium 意味着原生的 Playwright 支持、更大的生态系统以及与真正的 Chrome 匹配的 TLS 指纹。Camoufox 在 2026 年初恢复更新但处于不稳定的 Beta 阶段——CloakBrowser 是生产可用的。
**问:检测网站最终会发现这个吗?**
答:有可能。机器人检测是一场军备竞赛。源代码级别的补丁比配置级别的补丁更难检测,但并非不可能。我们在检测技术演进时会积极监控并更新。
**问:我可以使用自己的代理吗?**
答:可以。将 `proxy="http://user:pass@host:port"` 或 `proxy="socks5://user:pass@host:port"` 传递给 `launch()`。原生支持 HTTP 和 SOCKS5 代理。
## 路线图
| 特性 | 状态 |
|---------|--------|
| Linux x64 — Chromium 146 (57 个补丁) | ✅ 已发布 |
| macOS arm64/x64 — Chromium 145 (26 个补丁) | ✅ 已发布 |
| Windows x64 — Chromium 146 (57 个补丁) | ✅ 已发布 |
| JavaScript/Puppeteer + Playwright 支持 | ✅ 已发布 |
| 每个会话的指纹轮换 | ✅ 已发布 |
| 内置代理轮换 | 📋 计划中 |
## 链接
- 📋 **更新日志** — [CHANGELOG.md](CHANGELOG.md)
- 🌐 **网站** — [cloakbrowser.dev](https://cloakbrowser.dev)
- 🐛 **Bug 报告与功能请求** — [GitHub Issues](https://github.com/CloakHQ/CloakBrowser/issues)
- 📦 **PyPI** — [pypi.org/project/cloakbrowser](https://pypi.org/project/cloakbrowser/)
- 📦 **npm** — [npmjs.com/package/cloakbrowser](https://www.npmjs.com/package/cloakbrowser)
- ☕ **支持** — [ko-fi.com/cloakhq](https://ko-fi.com/cloakhq)
- 📧 **联系方式** — cloakhq@pm.me
## 安全
所有版本均已签名,用于供应链验证。
```
# 验证 GPG 签名(二进制发布标签)
gpg --keyserver keyserver.ubuntu.com --recv-keys C60C0DDC9D0DE2DD
git verify-tag chromium-v146.0.7680.177.3
# 验证 GitHub 二进制证明(Sigstore)
gh attestation verify cloakbrowser-linux-x64.tar.gz --repo CloakHQ/cloakbrowser
# 验证 Docker 镜像签名(Cosign/Sigstore)
cosign verify \
--certificate-identity-regexp "https://github.com/CloakHQ/CloakBrowser/" \
--certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
cloakhq/cloakbrowser:latest
```
## 许可证
- **包装器代码**(本仓库)— MIT。请参见 [LICENSE](https://github.com/CloakHQ/CloakBrowser/blob/main/LICENSE)。
- **CloakBrowser 二进制文件**(编译后的 Chromium)— 免费使用,禁止重新分发。请参见 [BINARY-LICENSE.md](https://github.com/CloakHQ/CloakBrowser/blob/main/BINARY-LICENSE.md)。
## 贡献
欢迎提交 Issues 和 PRs。如果有功能不正常,请[发起一个 issue](https://github.com/CloakHQ/CloakBrowser/issues) — 我们回复得很快。
## 贡献者
- [@evelaa123](https://github.com/evelaa123) — humanize 行为、持久上下文、Windows 修复
- [@yahooguntu](https://github.com/yahooguntu) — 持久上下文
- [@kitiho](https://github.com/kitiho) — null viewport 修复
- [@eofreternal](https://github.com/eofreternal) — humanConfig 类型修复
- [@AlexTech314](https://github.com/AlexTech314) — AWS Lambda 集成