Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

可绕过各类机器人检测测试的隐身 Chromium。

不是打过补丁的配置。也不是 JS 注入。而是在 C++ 源码层修改指纹的真实 Chromium 二进制。反机器人系统会把它判为普通浏览器——因为它本来就是普通浏览器。

Cloudflare Turnstile — 3 项线上测试通过（headed 模式，macOS）

适用于 Python 和 JavaScript 的即插即用 Playwright/Puppeteer 替代方案。
相同 API、相同代码——只需替换 import。3 行代码，30 秒解除拦截。

• 66 项源码级 C++ 补丁 — canvas、WebGL、audio、fonts、GPU、screen、WebRTC、网络时序、自动化信号、CDP 输入行为
• humanize=True — 类人鼠标曲线、键盘时序与滚动模式。一个开关即可通过行为检测
• Pro：reCAPTCHA v3 得分 0.9 — 人类水平，经服务端验证
• 通过 Cloudflare Turnstile、FingerprintJS、BrowserScan — 已在 30+ 个检测站点上测试
• 自动下载正确二进制 — 按许可证自动选择免费版或 Pro
• pip install cloakbrowser 或 npm install cloakbrowser — 二进制自动下载，零配置
• 开源封装 — 免费 v146 二进制，Pro 提供最新构建

立即试用 — 无需安装：

docker run --rm cloakhq/cloakbrowser cloaktest

Python：

from cloakbrowser import launch

browser = launch()
page = browser.new_page()
page.goto("https://example.com")
browser.close()

JavaScript（Playwright）：

import { launch } from 'cloakbrowser';

const browser = await launch();
const page = await browser.newPage();
await page.goto('https://example.com');
await browser.close();

也支持 Puppeteer：import { launch } from 'cloakbrowser/puppeteer'（详情）

对于带有反机器人保护的站点，请添加住宅代理及以下标志：

browser = launch(
    proxy="http://user:pass@residential-proxy:port",  # residential IP, not datacenter
    geoip=True,       # match timezone + locale to proxy IP
    headless=False,    # some sites detect headless even with C++ patches
    humanize=True,     # human-like mouse, keyboard, scroll
)

const browser = await launch({
    proxy: 'http://user:pass@residential-proxy:port',
    geoip: true,
    headless: false,
    humanize: true,
});

特定站点问题（FingerprintJS、Kasada、reCAPTCHA）请参见 故障排除。

安装

Python：

pip install cloakbrowser

JavaScript / Node.js：

# With Playwright
npm install cloakbrowser playwright-core

# With Puppeteer
npm install cloakbrowser puppeteer-core

.NET / C#：

dotnet add package CloakBrowser

基于 Microsoft.Playwright 的社区维护 .NET 客户端。完整 API 见 dotnet/README.md。

---

首次运行时，隐身 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")
# ... rest of your code works unchanged

⭐ Star 以示支持 — 关注 releases 以便在有新构建时收到通知。

---

最新：v0.4.10 — 66 项源码级隐身补丁（Chromium 148.0.7778.215.5 — Windows + Linux；macOS 随后跟进）

• CloakBrowser Pro — 最新二进制（Chromium 148.0.7778.215.5，66 项源码级补丁）已面向 Pro 订阅用户在 Windows 和 Linux 上提供（macOS 为 148.0.7778.215.3，下一构建将跟进）。设置 license_key（JS 中为 licenseKey）或 CLOAKBROWSER_LICENSE_KEY 环境变量后，封装会自动拉取最新构建。参见 CloakBrowser Pro
• .NET 8 / C# 客户端 — CloakBrowser 现已作为 NuGet 包发布（CloakBrowser），与 Python 和 JS 封装对齐。
• 66 项指纹补丁 — 改进 Linux 与 Windows 的渲染一致性，校正 GPU/显示/图形参数以匹配原版 Chrome 配置文件
• Windows 原生 GPU 透传 — 真实硬件值直接透传而非伪造，行为与真实浏览器一致
• HTTP 代理内联凭据 — 网络层新增对带内联认证代理的支持
• extension_paths — 在所有启动函数中加载 Chrome 扩展
• Humanize 可操作性 — 在拟人化操作前自动等待元素可见、可用且稳定
• 按次调用的 human_config — 可在单次方法调用上覆盖 humanize 设置
• 可组合 JS 辅助函数 — buildLaunchOptions() 与 humanizeBrowser()，用于自定义 Playwright 集成
• 原生 SOCKS5 代理 — proxy="socks5://user:pass@host:port" 可在所有启动函数中直接使用，Python + JS 均支持。QUIC/HTTP3 通过 SOCKS5 的 UDP ASSOCIATE 隧道传输
• 代理特征清除 — DNS/连接/SSL 时序归零，剥离代理缓存头，移除 Proxy-Connection 头泄露
• 升级至 Chromium 146 — 将全部补丁从 145.0.7632.x 变基至 146.0.7680.177
• WebRTC IP 伪造 — --fingerprint-webrtc-ip=auto 解析代理出口 IP 并伪造 WebRTC ICE 候选。使用 geoip=True 时自动注入（无额外网络请求）
• humanize=True — 一个开关让所有鼠标、键盘与滚动交互表现得像真实用户。贝塞尔曲线、逐字符输入、逼真滚动模式
• 零标志即隐身 — 二进制启动时自动生成随机指纹种子。无需配置
• 根据代理 IP 设置时区与语言区域 — launch(proxy="...", geoip=True) 自动检测时区与语言区域
• 持久化配置文件 — launch_persistent_context() 可在会话间保留 cookies 与 localStorage，绕过无痕模式检测

详情见完整 CHANGELOG.md。

为什么选择 CloakBrowser？

• 配置级补丁会失效 — playwright-stealth、undetected-chromedriver 和 puppeteer-extra 通过注入 JavaScript 或调整标志实现。每次 Chrome 更新都会破坏它们。反机器人系统会直接检测这些补丁本身。
• CloakBrowser 修改 Chromium 源码 — 指纹在 C++ 层被修改并编译进二进制。检测站点看到的是真实浏览器，因为它本来就是真实浏览器。
• 源码级隐身 — C++ 补丁在二进制层处理指纹（GPU、screen、UA、硬件上报）。无 JavaScript 注入，无配置级技巧。多数隐身工具仅在表层打补丁。
• 行为处处一致 — 在本地、Docker 与 VPS 上表现相同。无需针对环境的补丁或配置。
• 适用于 AI agent 与自动化框架 — 可为 browser-use、Crawl4AI、Scrapling、Stagehand、LangChain、Selenium 等提供即插即用隐身能力。参见 集成。

CloakBrowser 不会解决 CAPTCHA——它会阻止 CAPTCHA 出现。无需 CAPTCHA 求解服务，也不内置代理轮换——请自备代理，使用你已熟悉的 Playwright API。

CloakBrowser Pro

封装层（Python + JS）采用 MIT 许可，永久免费。二进制文件采用延迟免费发布模式：

• Free（v146） — 上一版二进制文件，见 GitHub Releases. 随着检测技术演进，数周内即会过时。
• Pro（最新版，Chromium 148.0.7778.215.5） — 优先获得最新补丁与 Chromium 升级，从而在反机器人系统变化时，让下方测试结果保持绿色。支持 Linux、Windows 和 macOS（Apple Silicon + Intel）。

反机器人检测不断更新，旧版二进制文件会迅速退化。 Pro 让你始终使用针对最新检测积极维护的构建版本。

若 CloakBrowser 用于生产级抓取、QA、监控或自动化，而陈旧的浏览器指纹会浪费你的时间或导致运行被拦截，请使用 Pro。

新功能：免费试用最新 Pro 二进制文件（Chromium 148）7 天 — 看看它在你目标站点上的表现。随时可取消。

使用许可证密钥激活（环境变量、license_key= 参数或 ~/.cloakbrowser/license.key）：

export CLOAKBROWSER_LICENSE_KEY=cb_xxxxxxxx

Pro 方案与免费试用 → cloakbrowser.dev

测试结果

所有测试均针对实时检测服务验证。除非另有说明，下方结果为最新 Pro/当前构建版本。最近测试：2026 年 7 月（Chromium 148）。

检测服务	原版 Playwright	CloakBrowser	备注
reCAPTCHA v3	0.1（机器人）	0.9（人类）	Pro/当前构建；服务端已验证
Cloudflare Turnstile（非交互式）	FAIL	PASS	自动解决
Cloudflare Turnstile（托管式）	FAIL	PASS	单击一次
ShieldSquare	BLOCKED	PASS	生产站点
FingerprintJS 机器人检测	DETECTED	PASS	Pro/当前构建；demo.fingerprint.com
BrowserScan 机器人检测	DETECTED	NORMAL（4/4）	browserscan.net
bot.incolumitas.com	13 fails	1 fail	仅 WEBDRIVER 规范
deviceandbrowserinfo.com	6 true flags	0 true flags	isBot: false
navigator.webdriver	true	false	源码级补丁
navigator.plugins.length	0	5	真实插件列表
window.chrome	undefined	object	与真实 Chrome 一致
UA string	HeadlessChrome	Chrome/146.0.0.0	无 headless 泄露
CDP detection	Detected	Not detected	isAutomatedWithCDP: false
TLS fingerprint	Mismatch	Identical to Chrome	ja3n/ja4/akamai 匹配
		已在 30+ 检测站点上测试

证明

Pro/最新构建：reCAPTCHA v3 得分 0.9 — 服务端已验证（人类级别）

Cloudflare Turnstile 非交互式挑战 — 自动解决

BrowserScan 机器人检测 — NORMAL（4/4 项检查通过）

Pro/最新构建：FingerprintJS 网页抓取演示 — 数据正常返回，未被拦截

deviceandbrowserinfo.com 行为机器人检测 — 在 humanize=True 下显示 "You are human!"（24/24 项信号通过）

对比

功能	Playwright	playwright-stealth	undetected-chromedriver	Camoufox	CloakBrowser
reCAPTCHA v3 得分（Pro/当前）	0.1	0.3-0.5	0.3-0.7	0.7-0.9	0.9
Cloudflare Turnstile	Fail	Sometimes	Sometimes	Pass	Pass
补丁层级	None	JS injection	Config patches	C++ (Firefox)	C++ (Chromium)
能否经受 Chrome 更新	N/A	Breaks often	Breaks often	Yes	Yes
维护状态	Yes	Stale	Stale	Unstable	Active
浏览器引擎	Chromium	Chromium	Chrome	Firefox	Chromium
Playwright API	Native	Native	No (Selenium)	No	Native

工作原理

CloakBrowser 是围绕自定义构建的 Chromium 二进制文件的轻量封装层（Python + JavaScript）：

1. 你安装 → pip install cloakbrowser 或 npm install cloakbrowser
2. 首次启动 → 二进制文件自动为你的平台下载（Chromium 146）
3. 每次启动 → Playwright 或 Puppeteer 使用我们的二进制文件 + 隐身参数启动
4. 你编写代码 → 标准 Playwright/Puppeteer API，无需学习新接口

该二进制文件包含 66 项源码级补丁，覆盖 canvas、WebGL、audio、fonts、GPU、screen properties、WebRTC、network timing、hardware reporting、automation signal removal，以及模拟 CDP input behavior。

这些补丁编译进 Chromium 二进制文件——并非通过 JavaScript 注入，也不是通过启动参数设置。

二进制下载在解压前会针对已发布的校验和上的固定 Ed25519 签名进行验证，从而确认下载来源真实（确为我们发布）且未被篡改。被入侵的镜像无法提供被篡改或降级的二进制文件。

API

launch()

from cloakbrowser import launch

# Basic — headless, default stealth config
browser = launch()

# Headed mode (see the browser window)
browser = launch(headless=False)

# Pro — use the latest binary (or set CLOAKBROWSER_LICENSE_KEY env var)
browser = launch(license_key="cb_xxxxxxxx")

# With proxy (HTTP or SOCKS5)
browser = launch(proxy="http://user:pass@proxy:8080")
browser = launch(proxy="socks5://user:pass@proxy:1080")

# With proxy dict (bypass, separate auth fields)
browser = launch(proxy={"server": "http://proxy:8080", "bypass": ".google.com", "username": "user", "password": "pass"})

# With extra Chrome args
browser = launch(args=["--disable-gpu"])

# With timezone and locale (sets binary flags — no detectable CDP emulation)
browser = launch(timezone="America/New_York", locale="en-US")

# Auto-detect timezone/locale from proxy IP (requires: pip install cloakbrowser[geoip])
# Also auto-injects --fingerprint-webrtc-ip to prevent WebRTC IP leaks (no extra cost)
# Note: makes HTTP calls through your proxy to resolve exit IP (ipify.org, checkip.amazonaws.com)
browser = launch(proxy="http://proxy:8080", geoip=True)

# Explicit timezone/locale always win over auto-detection
browser = launch(proxy="http://proxy:8080", geoip=True, timezone="Europe/London")

# WebRTC IP spoofing only (no geoip dep needed — resolves exit IP via HTTP call through proxy)
browser = launch(proxy="http://proxy:8080", args=["--fingerprint-webrtc-ip=auto"])

# Explicit WebRTC IP (no network call)
browser = launch(proxy="http://proxy:8080", args=["--fingerprint-webrtc-ip=1.2.3.4"])

# Human-like mouse, keyboard, and scroll behavior
browser = launch(humanize=True)

# With slower, more deliberate movements
browser = launch(humanize=True, human_preset="careful")

# Without default stealth args (bring your own fingerprint flags)
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()

便捷函数，一次调用即可创建 browser + 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()

额外的 kwargs 会转发给 Playwright 的 browser.new_context()——可用于 storage_state、permissions、extra_http_headers 等场景，且无需持久化 profile 文件夹：

from cloakbrowser import launch_context

# Restore a saved session (cookies, localStorage) from a JSON file
context = launch_context(storage_state="state.json")
page = context.new_page()
page.goto("https://example.com")
# Save state back for next run
context.storage_state(path="state.json")
context.close()

launch_context_async()

launch_context() 的异步版本。签名相同，并同样转发 kwargs：

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() 相同，但使用持久化用户 profile。Cookies、localStorage 和缓存在多次会话之间保持。

在以下场景中使用：

• 保持登录状态：多次运行之间 cookies/会话不丢失
• 绕过无痕模式检测：部分站点会标记空的临时 profile
• 加载 Chrome 扩展：扩展只能从真实的用户数据目录加载
• 构建自然的浏览历史：缓存字体、service workers、IndexedDB 会随时间累积，使 profile 看起来更真实
• 播放受 DRM 保护的视频（Widevine）——配合 sideload 的 CDM，封装层会在首次启动时启用 Widevine（参见 Widevine / DRM）

from cloakbrowser import launch_persistent_context

# First run — creates the profile
ctx = launch_persistent_context("./my-profile", headless=False)
page = ctx.new_page()
page.goto("https://protected-site.com")
ctx.close()  # profile saved

# Next run — cookies, localStorage restored automatically
ctx = launch_persistent_context("./my-profile", headless=False)

# Load Chrome extensions
ctx = launch_persistent_context(
    "./my-profile",
    headless=False,
    extension_paths=["./my-extension"],
)

支持与 launch_context() 相同的全部选项：proxy、user_agent、viewport、locale、timezone、color_scheme、geoip、extension_paths。

异步版本：launch_persistent_context_async()。

存储配额与无痕模式检测： 二进制默认会规范化存储配额（同时也会隐藏真实磁盘大小）。通过配额推断隐私/无痕模式的检测器——例如 BrowserScan 的无痕检测（−10%）——会将默认值判为无痕。提高配额以呈现为普通 profile：

ctx = launch_persistent_context("./my-profile", args=["--fingerprint-storage-quota=5000"])

Widevine / DRM

该二进制内置 Widevine 支持，但 Widevine CDM 是 Google 的专有组件，我们无法再分发。可通过以下两种方式获取（完整背景见 #96):

拉取——无需安装 Chrome；从 Google 组件服务器下载 CDM（仅 Linux x86-64；经 SHA-256 + CRX3 签名校验）。文件会落到 ~/.cloakbrowser/WidevineCdm，封装层会自动检测——无需设置环境变量：

python3 bin/fetch-widevine.py

或从现有 Chrome 安装复制，放在二进制文件旁边：

cp -r /opt/google/chrome/WidevineCdm ~/.cloakbrowser/chromium-<version>/WidevineCdm

（在 Docker 中，只需传入 -e CLOAKBROWSER_FETCH_WIDEVINE=1——入口脚本会自动执行拉取；详见下文 Docker 说明。）

CDM 就位后，launch_persistent_context() 会在首次启动时启用 Widevine——封装层会自动将 CDM 提示文件写入 profile，因此无需手动两次启动的变通方案。这样即可播放受 DRM 保护的视频（例如 Netflix、Spotify Web）。

from cloakbrowser import launch_persistent_context

# WidevineCdm sideloaded next to the binary -> Widevine works on first launch
ctx = launch_persistent_context("./my-profile", headless=False)

• 仅 Linux。 Chromium 的 hint-file 机制仅适用于 Linux/ChromeOS。在 Windows 上 CDM 无法初始化（DRM 主机验证），macOS 使用不同目录结构，因此在这些平台上 seeding 无效。
• 按存在自动启用。 无需标志——sideload 的 CDM 即表示选择启用。使用 CLOAKBROWSER_WIDEVINE_CDM=/path/to/WidevineCdm 指向非默认位置的 CDM，或使用 CLOAKBROWSER_WIDEVINE=0 完全禁用 seeding。
• Docker——自动拉取（可选）。 镜像内没有可复制的 Chrome，因此官方镜像可代为拉取 CDM。运行时传入 -e CLOAKBROWSER_FETCH_WIDEVINE=1，首次启动时会从 Google 组件服务器（与 Chrome 相同来源）拉取 CDM，并缓存在挂载卷中的 ~/.cloakbrowser/WidevineCdm，封装层会自动检测——免费版与 Pro 二进制，以及 docker exec 脚本均适用。默认关闭——除非你主动启用，否则不会发起网络请求——且为尽力而为，拉取失败不会阻止启动。安装前会校验签名与 checksum。裸机 Linux 用户可直接运行同一拉取器：python3 bin/fetch-widevine.py（仅 pip 安装可从仓库获取该独立文件）。

CLI

预下载二进制、诊断环境，或从命令行管理缓存：

python -m cloakbrowser install      # Download binary with progress output
python -m cloakbrowser info         # Diagnostics: binary that will launch, license tier, env checks
python -m cloakbrowser update       # Check for and download newer binary
python -m cloakbrowser clear-cache  # Remove cached binaries

info 会报告根据你的许可证实际将启动的二进制，执行快速启动测试（并在 Linux 上标记缺失的系统库），显示许可证层级，并检查字体、GeoIP 及可选依赖。添加 --quick 可跳过启动测试，或使用 --json 获取机器可读输出。相同命令也可通过 npx cloakbrowser <command>（JS）和 cloakbrowser CLI（.NET）使用。

工具函数

from cloakbrowser import binary_info, clear_cache, ensure_binary

# Check binary installation status
print(binary_info())
# {'version': '146.0.7680.177.5', 'platform': 'linux-x64', 'installed': True, ...}

# Force re-download
clear_cache()

# Pre-download binary (e.g., during Docker build)
ensure_binary()

JavaScript / Node.js API

CloakBrowser 提供带完整类型定义的 TypeScript 包。可选择 Playwright 或 Puppeteer——底层使用相同的 stealth 二进制。

Playwright（默认）

import { launch, launchContext, launchPersistentContext } from 'cloakbrowser';

// Basic
const browser = await launch();

// Pro — use the latest binary (or set CLOAKBROWSER_LICENSE_KEY env var)
const browser = await launch({ licenseKey: 'cb_xxxxxxxx' });

// 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',
});

注意： 以上每个示例均为独立片段——不应作为一个代码块整体运行。

JS 中可使用全部 Python 选项：stealthArgs: false 用于禁用默认值，geoip: true 用于根据代理 IP 自动检测时区/区域设置。

Puppeteer

注意： 对于使用 reCAPTCHA Enterprise 的站点，建议使用 Playwright 封装。Puppeteer 的 CDP 协议会泄露自动化信号，reCAPTCHA Enterprise 可据此检测，导致间歇性 403 错误。这是 Puppeteer 的已知限制，并非 CloakBrowser 特有。为获得最佳效果，请使用 Playwright。

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();

工具函数（JS）

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
鼠标移动	瞬间传送	带缓动与轻微过冲的 Bézier 曲线
点击	瞬间完成	逼真瞄准点 + 按住时长
键盘	瞬间填充	逐字符节奏、思考停顿、偶发打字错误并自我纠正
滚动	跳跃式	加速 → 匀速 → 减速的微步滚动
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 页面。

注意（Playwright）： 请始终使用 page.click(selector)、page.type(selector, text)、page.hover(selector) 或 page.locator(selector).* — 这些会经过完整的类人化（humanize）流水线。请避免使用 page.query_selector() — ElementHandle 对象会绕过所有补丁，导致鼠标瞬间传送、键盘事件无节奏触发，且滚动没有类人曲线。

注意（Puppeteer）： 基于选择器的方法（page.click()、page.type()）和 ElementHandle 方法（el.click()、el.type()）均已完全类人化。page.$()、page.$$() 和 page.waitForSelector() 会自动返回已打补丁的句柄。

贡献者：@evelaa123 — 完整覆盖 Playwright 与 Puppeteer API。

配置

环境变量	默认值	说明
CLOAKBROWSER_BINARY_PATH	—	跳过下载，使用本地 Chromium 二进制文件
CLOAKBROWSER_CACHE_DIR	~/.cloakbrowser	二进制缓存目录
CLOAKBROWSER_DOWNLOAD_URL	cloakbrowser.dev	二进制文件的自定义下载 URL
CLOAKBROWSER_AUTO_UPDATE	true	设为 false 可禁用后台更新检查
CLOAKBROWSER_SKIP_CHECKSUM	false	仅适用于自定义 CLOAKBROWSER_DOWNLOAD_URL：设为 true 可跳过其校验和检查。官方下载路径上的签名校验为强制项，无法跳过。
CLOAKBROWSER_GEOIP_TIMEOUT_SECONDS	5	GeoIP 解析的最大等待秒数，超时后继续运行但不使用 GeoIP
CLOAKBROWSER_WIDEVINE_CDM	—	旁加载 WidevineCdm 目录的路径（覆盖二进制文件旁自动检测）。参见 Widevine / DRM
CLOAKBROWSER_WIDEVINE	1	设为 0 可禁用持久化上下文的自动 Widevine 提示文件播种
CLOAKBROWSER_FETCH_WIDEVINE	0	仅 Docker：设为 1 可在容器启动时自动获取 Widevine CDM（仅 Linux x86-64）。参见 Widevine / DRM
CLOAKBROWSER_VERSION	—	锁定到精确的 Chromium 版本以便回滚（例如 148.0.7778.215.2）。适用于 Free 与 Pro 二进制文件

指纹管理

该二进制文件默认具备隐匿性 — 无需任何标志。启动时会自动生成随机指纹种子，并伪造所有可检测值（GPU、硬件规格、屏幕尺寸、canvas、WebGL、音频、字体）。每次启动都会生成全新的、一致的身份。

指纹工作原理：

场景	行为
无标志	启动时自动生成随机种子。GPU、屏幕、硬件规格及所有噪声补丁均自动伪造。每次启动都是全新身份。
--fingerprint=seed	由种子生成确定性身份。相同种子 = 跨启动相同指纹。用于会话持久化（回访用户）。
--fingerprint=seed + 显式标志	显式标志覆盖各自动生成的值。种子填充其余部分。

该二进制文件在编译时检测平台 — macOS 二进制报告为带 Apple GPU 的 macOS，Linux 二进制报告为带 NVIDIA GPU 的 Linux。wrapper 在 Linux 上通过传入 --fingerprint-platform=windows 覆盖此行为，使会话呈现为 Windows 桌面（更常见的指纹，更难聚类）。直接运行二进制文件时，可使用 --fingerprint-platform 进行跨平台伪造。

提示：回访同一站点时请使用固定种子。 随机种子会让每次会话看起来像不同设备 — 从同一 IP 反复访问同一站点时可能显得可疑。对于 reCAPTCHA v3 Enterprise 及类似评分系统，固定种子可在跨会话产生一致指纹，使你看起来像回访用户：

browser = launch(args=["--fingerprint=12345"])

const browser = await launch({ args: ['--fingerprint=12345'] });

默认指纹

每次 launch() 调用都会自动设置这些。wrapper 应用平台感知默认值 — 在 Linux 上伪装为 Windows 以获得更常见的指纹，在 macOS 上以原生 Mac 浏览器运行：

标志	Linux/Windows 默认值	macOS 默认值	控制项
--fingerprint	随机（10000–99999）	随机（10000–99999）	canvas、WebGL、音频、字体、client rects 的主种子
--fingerprint-platform	windows	macos	navigator.platform、User-Agent OS、GPU 池选择

该二进制文件从种子自动生成其余一切：GPU、硬件并发数、设备内存和屏幕尺寸。每个种子产生唯一且一致的指纹。如需可改用显式标志覆盖。

直接运行二进制文件？ 零标志即可开箱即用 — 二进制会自动伪造一切。传入 --fingerprint=seed 可获得持久身份，或使用 --fingerprint-gpu-renderer 等显式标志覆盖任意自动生成值。

附加标志

二进制支持但默认不设置 — 通过 args 传入以自定义：

标志	控制项
--fingerprint-gpu-vendor	WebGL UNMASKED_VENDOR_WEBGL（根据 seed + 平台自动生成）
--fingerprint-gpu-renderer	WebGL UNMASKED_RENDERER_WEBGL（根据 seed + 平台自动生成）
--fingerprint-hardware-concurrency	navigator.hardwareConcurrency（自动生成：8）
--fingerprint-device-memory	navigator.deviceMemory，单位 GB（自动生成：8）
--fingerprint-screen-width	屏幕宽度（自动生成：1920 Win/Linux，1440 macOS）
--fingerprint-screen-height	屏幕高度（自动生成：1080 Win/Linux，900 macOS）
--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 字体配置）
--fingerprint-windows-font-metrics	仅限 Chromium 148+ 二进制版本（更早版本无效）。在 Linux 上伪装为 Windows 时，使字体度量与 Windows 平台对齐 — 用于 FingerprintJS 配置。需要安装 Windows 字体（参见 Linux 字体配置）；未安装则无效果
--fingerprint-webrtc-ip	WebRTC ICE 候选 IP 替换。使用 auto 从代理出口 IP 解析（通过代理发起 HTTP 请求），或传入显式 IP。设置 geoip=True 时自动注入
--fingerprint-noise=false	禁用噪声注入（canvas、WebGL、audio、client rects），同时保持确定性指纹 seed 处于活动状态
--fingerprint=off	仅限 Chromium 148+ 二进制版本。 透传调试模式 — 关闭伪装并呈现机器的真实原生指纹（仅保留任何 Chrome 所需的基础配置）。二进制会剥离注入的 seed 以及 --fingerprint-platform，因此不会出现混合 OS 配置。在真正的 Windows 机器上最有用，可用于判断问题是出在伪装还是环境。接受 off/false/0/disable/disabled。若要实现纯透传，请勿与 geoip=True / 显式时区 / 区域设置组合使用 — 这些设置仍会生效。
--fingerprint-allow-3p-cookies	仅限 Chromium 148+ 二进制版本。 为需要第三方 Cookie 的嵌入式流程重新启用（reCAPTCHA v3、SSO、部分支付验证）。默认关闭；仅在登录/支付/嵌入式验证能加载但始终无法完成时开启。
--license-through-proxy	仅限 Chromium 148+ 二进制版本，目前仅支持 Linux。 将 Pro 许可证/会话调用经由你的 --proxy-server 路由，而非直连 cloakbrowser.dev。默认关闭（这些调用直连，因此不会占用代理带宽或影响你的爬取会话）。
--enable-blink-features=FakeShadowRoot	访问封闭的 shadow DOM 元素

注意： 所有隐身测试均使用上述默认指纹配置验证。修改这些标志可能影响检测结果 — 投入生产前请先测试你的配置。

Linux 字体配置

对抗强反爬站点（Kasada、Akamai）所必需。 这些系统会在隐藏 canvas 上渲染 emoji 并对像素输出进行哈希。精简的 Linux 环境（Docker、云虚拟机）通常缺少 emoji 和扩展字体，生成的哈希与任何真实浏览器都不匹配。安装标准字体包即可修复：

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"],
)

示例

# Pin a seed for a persistent identity
browser = launch(args=["--fingerprint=42069"])

# Full control — disable defaults, set everything yourself
browser = launch(stealth_args=False, args=[
    "--fingerprint=42069",
    "--fingerprint-platform=windows",
])

# Override GPU to look like a specific machine
browser = launch(args=[
    "--fingerprint-gpu-vendor=Intel Inc.",
    "--fingerprint-gpu-renderer=Intel Iris OpenGL Engine",
])

示例

Python — 参见 examples/：

• basic.py — 启动并加载页面
• persistent_context.py — 持久化配置，支持 cookie/localStorage 持久化
• recaptcha_score.py — 检查你的 reCAPTCHA v3 得分
• stealth_test.py — 在 6 个检测站点上运行测试
• fingerprint_scan_test.py — 针对 fingerprint-scan.com 和 CreepJS 进行测试

JavaScript — 参见 js/examples/：

• basic-playwright.ts — Playwright 启动并加载
• basic-puppeteer.ts — Puppeteer 启动并加载
• stealth-test.ts — 在 6 个检测站点上运行测试

框架集成

CloakBrowser 可与任何使用 Playwright 或 Chromium 的框架配合使用：

# Option 1: Framework launches our binary directly (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

# Option 2: CloakBrowser launches first, framework connects via CDP (browser-use, Crawl4AI, Scrapling)
from cloakbrowser import launch_async
browser = await launch_async(args=["--remote-debugging-port=9242"])
# Connect your framework to http://127.0.0.1:9242 — all stealth flags are set
# Note: humanize requires the wrapper (see below)

通过 CDP 实现 Humanize：隐身指纹补丁可通过 CDP 自动生效，但 humanize=True 是封装层功能。若从独立脚本通过 CDP 连接 CloakBrowser，需导入补丁函数以添加 humanization：

import { patchBrowser, resolveConfig } from 'cloakbrowser/human';
patchBrowser(browser, resolveConfig('default'));

框架	Stars	语言	示例
browser-use	70K	Python	browser_use_example.py
Crawl4AI	58K	Python	crawl4ai_example.py
Crawlee	8.6K	Python	crawlee_example.py
Scrapling	21K	Python	scrapling_example.py
Stagehand	21K	TypeScript	stagehand.ts
LangChain	100K+	Python	langchain_loader.py
Selenium	—	Python	selenium_example.py
undetected-chromedriver	12K	Python	undetected_chromedriver.py
agent-browser	—	Shell	agent_browser.sh

部署集成

平台	示例
AWS Lambda	aws_lambda/ — Lambda 中的单次抓取（容器镜像）

平台

平台	免费版	Pro 版	状态
Linux x86_64	Chromium 146 (58 patches)	Chromium 148 (66 patches)	✅
Linux arm64 (RPi, Graviton)	Chromium 146 (58 patches)	Chromium 148 (66 patches)	✅
macOS arm64 (Apple Silicon)	Chromium 145 (26 patches)	Chromium 148 (66 patches)	✅
macOS x86_64 (Intel)	Chromium 145 (26 patches)	Chromium 148 (66 patches)	✅
Windows x86_64	Chromium 146 (58 patches)	Chromium 148 (66 patches)	✅

封装器会根据你的平台自动下载对应的二进制文件。

macOS 首次启动： 二进制文件为 ad-hoc 签名。首次运行时，macOS Gatekeeper 会阻止其运行。右键点击应用 → 打开（Open） → 在对话框中点击 打开（Open）。此操作仅需执行一次。

Docker

Docker Hub 上的预构建镜像 —— 无需安装、无需配置。

Pro 版： 镜像内置免费版二进制。设置 CLOAKBROWSER_LICENSE_KEY（例如 -e CLOAKBROWSER_LICENSE_KEY=cb_xxx，或在 Compose 中设置），运行时即可下载最新二进制。

快速测试

docker run --rm cloakhq/cloakbrowser cloaktest

运行脚本

# Inline script
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()
"

# Mount your own script
docker run --rm -v ./my_script.py:/app/my_script.py cloakhq/cloakbrowser python my_script.py

# With a proxy
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（CDP）远程连接：

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()

若你的框架需要直接的 WebSocket 端点，请获取 Chrome 的发现文档并使用重写后的 webSocketDebuggerUrl。该 URL 通过 cloakserve 回连，以便 CDP 代理保持按 seed 的路由不变：

curl http://localhost:9222/json/version | jq -r .webSocketDebuggerUrl
# ws://localhost:9222/devtools/browser/<browser-id>

curl 'http://localhost:9222/json/version?fingerprint=11111' | jq -r .webSocketDebuggerUrl
# ws://localhost:9222/fingerprint/11111/devtools/browser/<browser-id>

当 cloakserve 运行在反向代理或 TLS 终结器之后时，请转发公共主机/协议头，使生成的 WebSocket URL 使用客户端实际可访问的地址：

proxy_set_header Host $host;
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Proto $scheme;

设置这些头后，/json/version 将返回诸如 wss://cdp.example.com/fingerprint/11111/devtools/browser/<browser-id> 的公共端点，而非内部容器主机。

向浏览器传递额外参数：

# With proxy
docker run -d --name cloak -p 127.0.0.1:9222:9222 cloakhq/cloakbrowser \
  cloakserve --proxy-server=http://proxy:8080

# Headed mode (renders to Xvfb inside container)
docker run -d --name cloak -p 127.0.0.1:9222:9222 cloakhq/cloakbrowser \
  cloakserve --headless=false

# Reap disconnected per-seed browser processes after 5 minutes
docker run -d --name cloak -p 127.0.0.1:9222:9222 cloakhq/cloakbrowser \
  cloakserve --idle-timeout=300

停止服务器：

docker stop cloak && docker rm cloak

安全： CDP 可完全控制浏览器（执行 JS、读取页面、访问文件）。 示例绑定到 127.0.0.1，因此仅你的机器可连接。切勿在未增加额外认证的情况下将 9222 端口 暴露到公网。

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

按连接划分的指纹 seed —— 从单个容器运行多个浏览器身份。每个不同的 seed 会启动独立的 Chrome 进程，并拥有各自的指纹：

# Each seed gets unique canvas noise, client rects, and other browser signals
b1 = pw.chromium.connect_over_cdp("http://localhost:9222?fingerprint=11111")
b2 = pw.chromium.connect_over_cdp("http://localhost:9222?fingerprint=22222")

# Full identity control via 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"
)

# Auto-detect timezone/locale from proxy exit 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。相同 seed 复用同一进程（以首次连接的参数为准）。无 seed = 共享默认进程（向后兼容）。

默认情况下，按 seed 的进程会一直保持运行，直到 cloakserve 退出。若客户端创建了许多不同的 seed，可设置 --idle-timeout=SECONDS 或 CLOAKSERVE_IDLE_TIMEOUT=SECONDS，在其最后一次 CDP WebSocket 断开后自动终止该 seed 的 Chrome 进程。0、off、false、none 或 disabled 可禁用空闲清理。执行清理时，--data-dir 下该 seed 的临时 profile 目录也会被删除。可在 GET / 查看活跃进程（返回包含 PID、端口、连接数、空闲超时和待清理状态的 JSON）。

持久化 profile —— 挂载卷以在容器重启后保留 cookie 和会话：

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()
"

使用同一卷再次运行 —— cookie、localStorage 和 cache 会自动恢复。

要在持久化 profile 中启用 Widevine DRM（Netflix、Spotify Web 等），请添加 -e CLOAKBROWSER_FETCH_WIDEVINE=1 以在首次启动时自动获取 CDM（参见 Widevine / DRM）；它会缓存在挂载的卷中。

资源占用： 空闲时约 190MB RAM，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：

docker build -t cloakbrowser .

CloakBrowser 在本地、Docker 和 VPS 上行为一致。无需针对特定环境进行配置。

注意： 若在带 uvloop 的 Web 服务器中运行 CloakBrowser（例如 uvicorn[standard]），请使用 --loop asyncio 以避免子进程管道挂起。

故障排除

---

在强对抗站点（DataDome、Turnstile）上仍被封禁？

有些网站即使使用了我们的 C++ 补丁，仍会检测到无头（headless）模式。请在虚拟显示器上以 headed mode（有界面模式）运行：

# Install Xvfb (virtual framebuffer)
sudo apt install xvfb

# Start virtual display
Xvfb :99 -screen 0 1920x1080x24 &
export DISPLAY=:99

from cloakbrowser import launch

# Headed mode + residential proxy for maximum stealth
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()

这会在虚拟显示器上运行真实的 headed 浏览器，无需物理显示器。结合下方推荐配置，可获得最佳隐匿效果。

---

反机器人站点的推荐配置

大多数封禁源于以下三项配置中缺失其一，而非浏览器指纹检测：

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)

若仍被封禁，请检查下方字体配置。

---

被 FingerprintJS 检测到？

FingerprintJS（demo.fingerprint.com/playground）会检查多种信号。每项检测结果都有具体原因：

检测项	原因	修复
nodriver / bad bot	二进制/wrapper 过期、缺少当前 FPJS 补丁，或代理 IP 信誉不佳	升级至最新 Pro 二进制（148.0.7778.215.5+），搭配 geoip=True 使用住宅代理，并采用下方配置。
Browser tampering	ML 检测到噪声注入	--fingerprint-noise=false
Browser tampering（fonts）	字体度量与伪装的 Windows 平台不匹配	--fingerprint-windows-font-metrics（Chromium 148+ 二进制；需要安装 Windows 字体）
Virtual machine	屏幕尺寸与 viewport 不匹配	--fingerprint-screen-width/height 与 viewport 匹配

在最新二进制上可通过 FPJS 的配置（Linux，住宅代理）：

browser = launch(
    headless=False,
    proxy="http://user:pass@residential-proxy:port",
    geoip=True,
    args=[
        "--fingerprint-noise=false",          # prevents tampering detection
        "--fingerprint-windows-font-metrics", # align font metrics — 148+ binary, needs Windows fonts
    ],
)

const browser = await launch({
    headless: false,
    proxy: 'http://user:pass@residential-proxy:port',
    geoip: true,
    args: [
        '--fingerprint-noise=false',
        '--fingerprint-windows-font-metrics',  // align font metrics — 148+ binary, needs Windows fonts
    ],
});

需要 Chromium 148+ 二进制 和已安装的 Windows 字体（见 Font Setup on Linux）；配合 住宅代理 和 geoip=True 运行。

Persistent contexts（launch_persistent_context / launchPersistentContext）在最新 Pro 二进制上使用相同的 FPJS 配置。请使用真实的 userDataDir。此处存储配额（storage quota）调优与 FingerprintJS 无关；它仅影响从配额推断无痕模式的检测器，例如 BrowserScan（见 storage quota）。DRM/媒体播放见 Widevine / DRM。

---

配置正确仍被 Kasada / Akamai 站点封禁？

在精简 Linux 环境中，缺少字体包会导致 canvas emoji 渲染产生的哈希值无法被反机器人系统识别。在代理、geoip 和有界面模式均已正确配置后，这是防护严格站点上最常见的封禁原因。

安装上文 Linux 字体配置 中列出的字体包。

---

部分网站会挑战新会话，首次访问后则可正常工作

一些网站会通过 HTTP/2 对没有 cookie 的首次访客进行挑战（challenge）。这会影响所有 Chromium 浏览器，而不仅是 CloakBrowser。使用持久化配置文件（persistent profile）预先预热 cookie，然后在各次会话中复用：

from cloakbrowser import launch_persistent_context

# First run: warm up with --disable-http2
ctx = launch_persistent_context("./profile", args=["--disable-http2"])
page = ctx.new_page()
page.goto("https://example.com")  # warms up cookies
ctx.close()

# Future runs — no --disable-http2 needed
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。

---

遇到问题？请确保已升级到最新版本

旧版本可能使用过时的隐身参数（stealth args），或下载较旧的二进制文件：

pip install -U cloakbrowser    # Python
npm install cloakbrowser@latest # JavaScript
docker pull cloakhq/cloakbrowser:latest  # Docker

新更新导致问题？回滚版本

有两种方式可回到可用的版本：

固定二进制版本（保留当前 wrapper，仅使用较旧的 Chromium）—— 适用于 Free 和 Pro：

# Free — pin a public release
browser = launch(browser_version="146.0.7680.177.5")

# Pro — pin a previous Pro version
browser = launch(license_key="cb_xxxxxxxx", browser_version="148.0.7778.215.2")

export CLOAKBROWSER_VERSION=146.0.7680.177.5   # env var for all launches

// Free — pin a public release
const browser = await launch({ browserVersion: '146.0.7680.177.5' });

固定操作不会持久保留——未固定时启动始终使用最新可用版本。

或降级 wrapper（每个 wrapper 版本会硬编码其下载的二进制版本）：

pip install cloakbrowser==0.3.21              # Python
npm install cloakbrowser@0.3.21               # JavaScript
docker pull cloakhq/cloakbrowser:0.3.21       # Docker

---

设置自定义下载 URL 或使用本地二进制文件：

export CLOAKBROWSER_BINARY_PATH=/path/to/your/chrome

macOS：“App 已损坏”或 Gatekeeper 阻止启动

该二进制文件为 ad-hoc 签名。macOS 会对下载的文件进行隔离（quarantine）。运行以下命令一次即可清除：

xattr -cr ~/.cloakbrowser/chromium-*/Chromium.app

---

“playwright install”与 CloakBrowser 二进制文件

你不需要 playwright install chromium。CloakBrowser 会自行下载其二进制文件。你只需安装 Playwright 的系统依赖：

playwright install-deps chromium

---

网站检测到无痕/隐私浏览模式

默认情况下，launch() 会打开无痕上下文（incognito context）。部分网站会因此进行限制。使用 launch_persistent_context() 可获得带 cookie 持久化的真实配置文件：

from cloakbrowser import launch_persistent_context

ctx = launch_persistent_context("./my-profile", headless=False)

若网站仍将你标记为无痕模式，可提高存储配额（storage quota）以呈现为常规浏览会话。详见 存储配额权衡，了解其对不同检测服务的影响。

---

reCAPTCHA v3 分数偏低（0.1–0.3）

避免使用 page.wait_for_timeout() —— 它会发送 reCAPTCHA 可检测到的 CDP 协议命令。请改用原生 sleep：

# Bad — sends CDP commands, reCAPTCHA detects this
page.wait_for_timeout(3000)

# Good — invisible to the browser
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 分数的其他建议：

• 使用 Playwright，而非 Puppeteer —— Puppeteer 会发送更多 reCAPTCHA 可检测到的 CDP 协议流量（详情）

• 使用住宅代理（residential proxies） —— 被标记的是数据中心 IP 的 IP 信誉，而非浏览器指纹

• 在触发 reCAPTCHA 前在页面上停留 15 秒以上 —— 访问时间过短会导致分数偏低

• 错开请求 —— 同一会话中连续调用 grecaptcha.execute() 会被惩罚。在含有 reCAPTCHA 的页面之间等待 30 秒以上

• 使用固定的 fingerprint seed，以便在多个会话间保持一致的设备身份（参见 指纹管理）

• 填表时使用 page.type()，而非 page.fill() —— fill() 会直接设置值而不产生键盘事件，reCAPTCHA 的行为分析会将其标记为可疑。带 delay 的 type() 可模拟真实按键：

  page.type("#email", "user@example.com", delay=50)
  

• 在 reCAPTCHA 检查触发前尽量减少 page.evaluate() 调用 —— 每次调用都会产生 CDP 流量

常见问题

问：这合法吗？ 答：CloakBrowser 是基于开源 Chromium 构建的浏览器。我们不纵容非法用途。未经授权自动化系统、撞库（credential stuffing）以及滥用账号创建均被明确禁止。完整条款见 BINARY-LICENSE.md。

问：CloakBrowser 免费吗？ 答：封装层（Python + JS）采用 MIT 许可，永久免费。二进制采用延迟免费开放模式：上一版 Chromium 主版本（当前为 v146）可在 GitHub Releases 免费下载，会话数不限；最新主版本面向 Pro 订阅用户.。每次新的主版本发布后，上一主版本会降为免费版。

问：免费版需要许可证密钥吗？ 答：不需要。免费版二进制会自动下载，无需密钥。许可证密钥仅用于解锁最新（Pro）二进制。

问：取消 Pro 订阅会怎样？ 答：订阅会保持有效直至当前计费周期结束——取消不会立刻中断服务。周期结束后，封装层会停止拉取新的 Pro 版本，并在下一次许可证检查（缓存约 24 小时）时回退到免费二进制。你只是不再获得新版本。

问：这与 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 代理。

链接

• 📋 更新日志 — CHANGELOG.md
• 🌐 官网 — cloakbrowser.dev
• 🐛 缺陷报告与功能请求 — GitHub Issues
• 📦 PyPI — pypi.org/project/cloakbrowser
• 📦 npm — npmjs.com/package/cloakbrowser
• ☕ 支持 — ko-fi.com/cloakhq
• 📧 联系 — cloakhq@pm.me

安全

封装层在解压前会自动根据已发布校验和上的固定 Ed25519 签名验证每一次二进制下载——被攻陷的镜像无法提供被篡改或降级的二进制。发行版还会额外签名，以便手动进行供应链验证：

# Verify GPG signature (binary release tag)
gpg --keyserver keyserver.ubuntu.com --recv-keys C60C0DDC9D0DE2DD
git verify-tag chromium-v146.0.7680.177.5

# Verify GitHub binary attestation (Sigstore)
gh attestation verify cloakbrowser-linux-x64.tar.gz --repo CloakHQ/cloakbrowser

# Verify Docker image signature (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.
• CloakBrowser 二进制（编译版 Chromium）：
  • v146 及更早版本 —— 个人与商业使用免费，不可再分发（向第三方提供服务需 OEM/SaaS 许可）。
  • v148+（最新版） —— 下载需有效的 CloakBrowser Pro 订阅。
  • 完整条款见 BINARY-LICENSE.md。

贡献

欢迎提交 Issue 与 PR。如有问题，请 提交 issue —— 我们会尽快回复。

贡献者

• @evelaa123 —— 人性化行为、持久化上下文、Windows 修复、.NET 客户端
• @yahooguntu —— 持久化上下文
• @kitiho —— null viewport 修复
• @eofreternal —— humanConfig 类型修复、humanized 方法选项类型、iframe pointer-events 修复
• @manaskarra —— humanized frame 操作的 iframe 作用域修复、GeoIP 超时保护
• @Youhai020616 —— SOCKS5 凭据编码日志
• @AlexTech314 —— AWS Lambda 集成、冷启动加固
• @dgtlmoon —— 优雅的 pw.stop() 清理
• @zackycodes —— Chrome 扩展加载
• @aaronjmars —— 安全修复（shell 注入、依赖升级）
• @Seryiza —— Nix/NixOS flake
• @245678000000 —— package-lock 同步
• @honor2030 —— cloakserve WebSocket origin 防护、CDP WebSocket URL 重写、可组合的 JS 启动辅助函数
• @sparanoid —— Docker Xvfb 锁清理
• @Kumario1 —— 带 seed 配置的 cloakserve 空闲清理
• @0xlally —— 安全报告（cloakserve 路径遍历、WebSocket origin 绕过）

Star 历史