cloakbrowser

用途

CloakBrowser 用于驱动隐身浏览器自动化。根据本资料，它的默认 JavaScript 入口与 Playwright 兼容；在通过 CDP 附加 playwright-cli 之后，自动化层面与 Playwright 几乎 1:1。该技能主要面向 CLI 驱动的浏览器自动化，也支持直接使用 Node 代码。

主要能力

管理模式 CLI：提供 cloakbrowser install|info|update|clear-cache 命令，用于二进制生命周期管理。
自动化 CLI 路径：先用 CDP 端口启动 CloakBrowser，再用 playwright-cli attach --cdp=... 附加驱动。资料明确指出，CloakBrowser 本身并不附带完整的页面驱动 CLI。
自动化 API：提供 launch()、launchContext()、launchPersistentContext() 等入口。
默认 JS 入口与 Playwright 兼容。
Puppeteer 为独立导入路径：import { launch } from 'cloakbrowser/puppeteer'。
隐身相关设置：代理、geoip、时区、语言、humanize、持久化配置等（资料中作为可调项列出，具体参数以官方文档为准）。
迁移支持：将现有 Playwright 代码以最小改动迁移到 CloakBrowser。

使用方式

环境要求：Node.js 20+。资料建议使用 pnpm 安装。首次启动会自动下载约 200MB 的 Chromium 二进制，默认缓存目录为 ~/.cloakbrowser。

安装命令：

CLI 自动化栈：pnpm add cloakbrowser playwright-core playwright-cli
Playwright 风格配置：pnpm add cloakbrowser playwright-core
Puppeteer 风格配置：pnpm add cloakbrowser puppeteer-core
可选 GeoIP 支持：pnpm add mmdb-lib

默认 CLI 自动化流程：

pnpm add cloakbrowser playwright-core playwright-cli
node scripts/attach-cloakbrowser.mjs --port 9222 --headed --humanize
playwright-cli attach --cdp=http://127.0.0.1:9222
playwright-cli goto https://example.com
playwright-cli snapshot
playwright-cli click "text=More information"
playwright-cli screenshot
playwright-cli detach
node scripts/stop-cloakbrowser.mjs

随附的辅助脚本：

scripts/attach-cloakbrowser.mjs：以 CDP 端点启动 CloakBrowser
scripts/stop-cloakbrowser.mjs：停止已启动的浏览器进程
scripts/open-url.mjs：一个极简的直接 Node 示例

最小的 Playwright 风格示例：

import { launch } from 'cloakbrowser'

const browser = await launch({ headless: true })
const page = await browser.newPage()
await page.goto('https://example.com')
console.log(await page.title())
browser.close()

Context 优先用法：

import { launchContext } from 'cloakbrowser'

const context = await launchContext({
  locale: 'en-US',
  timezone: 'America/New_York',
})

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

持久化配置用法：

import { launchPersistentContext } from 'cloakbrowser'

const context = await launchPersistentContext({
  userDataDir: './chrome-profile',
  headless: false,
})

const page = context.pages()[0] || await context.newPage()
await page.goto('https://example.com')
await context.close()

从 Playwright 迁移的基本规则：

- import { chromium } from 'playwright-core'
- const browser = await chromium.launch()
+ import { launch } from 'cloakbrowser'
+ const browser = await launch()

迁移后大多数页面代码保持不变，例如 browser.newPage()、page.goto()、page.click()、page.type()、page.screenshot()、browser.close()。

适用场景

终端驱动的浏览器自动化，命令如 open、goto、click、fill、snapshot、screenshot
需要隐身能力的自动化流程
将已有 Playwright 代码迁移到 CloakBrowser
需要代理、持久化配置或降低被检测风险的场景
CLI 二进制管理（安装、更新、查看信息、清理缓存）

限制

资料明确给出的注意事项：

CloakBrowser 没有完整的 Playwright 风格页面驱动 CLI；其内置 CLI 仅用于二进制生命周期管理。
不能说它替代 Playwright Test。
不能说它能直接解决 CAPTCHA。
不能说 Puppeteer 与 Playwright 的隐身效果完全相同。

隐身相关建议（仅在相关时使用）：在较强的反机器人流程中优先使用 Playwright 模式而非 Puppeteer；优先使用顶层 timezone 和 locale，而非 contextOptions.timezoneId 或 contextOptions.locale；当存在无痕模式检测时使用 launchPersistentContext()；当存在行为检测时使用 humanize: true；在敏感流程中避免 page.waitForTimeout()，优先使用原生 sleep；表单填写中 page.type() 通常比 page.fill() 更接近人类操作。

技能介绍

用途

主要能力

使用方式

适用场景

限制