启动选项
其他页面没有涉及的启动选项:扩展、Privacy Sandbox,以及列表中的其余选项。
更多启动选项
extensions——未打包扩展的目录路径列表(会生成--load-extension+--disable-extensions-except)。disablePrivacySandbox/disable_privacy_sandbox——设为true可关闭 Privacy Sandbox API(Topics、FLEDGE / Protected Audience、Shared Storage、Private Aggregation、Fenced Frames)。自 0.23 起此选项默认关闭:默认身份画像呈现为 Google Chrome,而 Google Chrome 提供了上述所有 API。只有当身份画像是去 Google 化的 Chromium 时才开启它。WebUSB 不受影响。agentTyping/agent_typing——智能体的击键节奏(默认human/fast/instant)。参见智能体。tlsProfile——让 TLS ClientHello 与身份画像声称的 Chrome 版本保持一致,使网络层跟随 UA(而不是构建自身原生的 TLS)。默认值"match-persona"跟随brandVersion;"native"保持原样不做改动;"chrome-<major>"固定为某个主版本。参见指纹参数。platform: "android"——尽力而为的移动端身份画像(触控、粗略指针、移动端屏幕/DPR、Mali/Adreno WebGL、手机视口)。在桌面引擎上,GPU 渲染仍然是桌面端的——请搭配 canvas bridge 实现渲染一致性。storageQuota、fingerprintProfile、canvasBridge、webrtcIp、acceptLanguage、disableGpuFingerprint、fingerprintNoise——参见指纹参数。
较新的选项(授权版构建)
以下选项需要授权版构建(GitHub 免费版或 Pro)。方括号中是各选项所需的引擎修订版本;在较旧的引擎上,SDK 会跳过标注 152 r22 的选项并给出警告;对每个标注 154 r32 的选项,SDK 会先检查引擎,构建不支持时就不启用它;其余选项则会被引擎忽略。
stockRuntime/stock_runtime/StockRuntime(或CLEARCOTE_STOCK_RUNTIME=1)——在调试运行中让 Playwright 恢复原版的 DevTools 行为:控制台和页面错误事件、page.setContent(),以及导航之后的exposeFunction()。默认关闭,因为页面能察觉到它;没有该开关的引擎会在不启用它的情况下启动,SDK 会警告一次。仅适用于本地和 Docker 启动。参见事件与调试。[154 r32;SDK 0.41.0]personaEnv/persona_env/PersonaEnv——从 SDK 0.41.0 起默认开启。身份画像相关的开关(种子、每一项身份画像覆盖、代理凭据以及 canvas bridge 令牌)通过浏览器的环境变量传入,而不是通过命令行——任何本地用户都能在进程列表中读到命令行(Linux 上的/proc/<pid>/cmdline,Windows 上的进程详细信息)。引擎也不会让它们出现在其辅助进程的命令行中。false或CLEARCOTE_PERSONA_ENV=0会把它们保留在命令行上,例如当你自己的某个工具需要从命令行读取它们时。Docker 镜像对容器内的浏览器也是同样处理。[154 r32]- Persona 令牌 — 在授权版 Chromium 156 构建(r51 及更新)上,SDK 每次启动都会从 Clearcote 的 persona 服务为你的 seed 或配置获取一个已签名的 persona,并与上述开关一起传给浏览器。没有关闭它的选项;没有它浏览器不会启动。需要 SDK 0.63.0、Profile Manager 0.27.0 或对应的 Docker 镜像。[156 r51; SDK 0.63.0]
- 浅色或深色——从 154 r32 起,由身份画像决定配色方案(大约每三个身份画像中有一个偏好深色),CSS、
matchMedia、Sec-CH-Prefers-Color-Scheme请求头以及系统颜色都会跟随它。Playwright 会在它创建的每个上下文中模拟浅色,这与深色身份画像相矛盾,因此从 SDK 0.41.0 起,在这类构建上,本地启动所创建的上下文不再改动配色方案。如果仍想模拟某种配色方案,请传入colorScheme/color_scheme/ColorScheme;或者在args中传入--fingerprint-color-scheme=light|dark,让身份画像本身成为浅色或深色。较旧的构建保留 Playwright 的默认行为。[154 r32] allowThirdPartyCookies/allow_third_party_cookies——第三方 Cookie,默认允许,与原版 Chrome 一致(SDK 0.45.0+);设为false则阻止。嵌入式登录、支付和验证框架依赖它们。152 r22 之前的构建始终阻止第三方 Cookie。[152 r22]transparentProxy/transparent_proxy——在请求头和连接时序中隐藏代理(纯 HTTP 请求不携带代理请求头;经代理的连接上报的时序与复用连接相同)。需要配合代理使用。[152 r22]fingerprintVoices: false/fingerprint_voices=False——保留本机自己的语音,而不使用身份画像的语音列表。[152 r22]fingerprint: "off"——完全不使用身份画像启动,用于排查问题。[152 r22]socks5Udp/socks5_udp——让 WebRTC 的 UDP 流量经由socks5://代理传输,这样语音、视频和点对点连接都能正常工作,而且仍然从代理的地址发出。代理必须允许这样做;很多住宅代理池并不允许。[151 r17]portableProfile/encryptionKey——可在机器之间复制的 profile(见上文)。[151 r14;Python、Node & .NET(0.58.0+)]personaSchema/persona_schema——种子派生所用的身份模型。不设置即使用当前模型7(自 2026-10-26 起提供,r52):由显卡决定机器的类型(笔记本或台式机)及其处理器、线程数、内存和屏幕,每一项出现的概率都与真实浏览器流量中的相同。5派生的结果与 r45 到 r51 完全相同,4与 154 r37 到 155 r44 相同,3与 154 r36 相同,2与 153 r29 到 154 r35 相同;要保留在这些构建上创建的身份,请设置其中之一。1是 r29 之前的原始模型。不存在6。从 0.64.1 起,所有 SDK 都接受 5 和 7。参见不同机器上的同一个种子。只在配有真实显卡的机器上添加realGpuHost/real_gpu_host。[151 r19;Python, Node & .NET]shaderDialect: "hlsl"——从 SDK 0.39.0 起,Linux 或 macOS 主机上的 Windows 身份画像默认开启;false可将其关闭。参见着色器方言。[151 r15]profile: "auto"——启动一个为本机挑选的真实采集指纹,而不是使用种子;可以用profileSelect/profile_select调整。支持 Python、Node & .NET(LocalProfile = "auto",0.58.0+)。在 Node 中,从 SDK 0.31.1 起它可用于默认的launch()、launchPersistentContext()和serve();0.31.0 及更早版本需要ephemeralProfile: false,且配合serve()使用时会失败。
与引擎构建无关的选项:
version/releaseChannel——选择构建;参见选择构建。licenseKey/license_key/LicenseKey——许可证密钥(如果它不在CLEARCOTE_LICENSE_KEY或~/.clearcote/license.key中)。licenseThroughProxy/license_through_proxy(或CLEARCOTE_LICENSE_THROUGH_PROXY=1)——通过本次启动所用的代理发送许可证请求,而不是从本机直接发出。launch()上的ephemeralProfile/userDataDir——参见上文使用 SDK 一节中的说明。widevine: true——DRM 播放(两种构建均支持);参见 Widevine & DRM。quiet——关闭 SDK 的启动警告和进度输出。fontDirs/font_dirs/FontDirs——在 Linux 上使用你自己的字体;见下文。
在 Linux 上使用你自己的字体(fontDirs)
在 Linux 上,浏览器只能看到 SDK 指给它的字体:该版本自带的一组与 Windows 字体度量兼容的替代字体(Arial→Arimo、Segoe UI→Selawik、Times New Roman→Tinos……)。主机上安装的任何字体都不会到达浏览器,因此这台机器上的任何东西都无法改变页面测量到的结果。从 SDK 0.41.0 起(Python、Node 和 .NET;launch()、持久化上下文和 serve()),可以用两个设置添加字体目录:
fontDirs/font_dirs/FontDirs,或CLEARCOTE_FONT_DIRS——你自己的字体,通常是一台 Windows 机器上C:\Windows\Fonts的副本,排在自带字体之前。在 154 r32 起的授权版构建上,这些目录提供的每个字体族都会以它本身、以它自己的名称渲染,而不再使用替代字体;在 Windows 上代表这些字体族的名称也随之生效:Helvetica、Times 和 Courier,以及 CSS 通用字体族(sans-serif→ Arial,serif→ Times New Roman,monospace→ Consolas,system-ui→ Segoe UI)。较旧的引擎对身份画像列出的字体族仍使用替代字体绘制,只把这些目录用于其他字体都不覆盖的字符。如果某个路径不是目录,启动会立即失败,此时尚未占用许可证名额。CLEARCOTE_FALLBACK_FONT_DIRS——只用于其他字体都不覆盖的字符(CJK、印度系文字、emoji……)的字体,排在自带字体之后。它们不会接管任何字体族。Docker 镜像会把它设置为镜像自带的各书写系统字体。
from clearcote import launch
# a copy of a Windows machine's C:\Windows\Fonts, on the Linux host
browser = launch(fingerprint="acct-1", platform="windows", font_dirs=["/srv/windows-fonts"])
# or: CLEARCOTE_FONT_DIRS=/srv/windows-fonts (several directories: separate them with ":")- 两个变量都是以
:分隔的列表。字体族名称直接从字体文件中读取,因此不需要 fontconfig 工具。切勿把任何一个变量指向整个/usr/share/fonts:那样主机的拉丁字体族会与自带字体竞争,改变 Windows 身份画像报告的字宽。 - 在 Linux 上,
clearcote info(Python 和 Node)会报告:一次启动所能看到的字体可以绘制 29 种书写系统中的哪些、你的字体目录,以及这些目录真正提供了哪些关键的 Windows 字体族。 - 如果列出了你自己的字体但仍想保留替代字体,请在
args中传入--disable-genuine-font-faces(154 r32+)。SDK 会识别它并保持自己的字体规则不变,这样引擎和 fontconfig 对每个字体族的认定都一致。 - 在 Windows 和 macOS 上会被忽略(它们使用自己的字体);云端启动和 macOS Docker 启动会拒绝这些设置:在你自己的容器中,请挂载字体并在容器里设置
CLEARCOTE_FONT_DIRS(参见部署)。只使用你已获得授权的字体。 - 在 0.41.0 之前,.NET SDK 根本没有把浏览器指向自带字体,因此 Linux 上的 .NET 启动使用的是主机字体,没有用到任何替代字体。现在它与 Python 和 Node 保持一致,这会改变 Windows 身份画像在那里的测量结果。