跳到正文

让 Clearcote 保持最新

没有许可证密钥时，每个 SDK 版本都固定对应一个经过 SHA-256 校验的开源版构建，更新它就是一次普通的依赖包升级。有密钥时，SDK 每次启动都会获取当前的授权版构建——无需升级。

目前提供哪些构建

我们当前发布或正在开发的 Chromium 大版本，以及各个方案何时能用上它们：

Chromium 构建开源版免费密钥与 Pro
当前授权版156r57 · 25 Oct 2026约 2 个月后现已可用
早期授权版155·154·153·152尚未提供仅限 Pro——version="155"
当前开源版151v0.1.0-pre.25 · 28 Oct 2026现已可用现已可用
早期开源版150·149现已可用现已可用

所有构建均提供 Windows + Linux x64 版本。 新的 Chromium 主版本在构建完成当天进入授权版构建（可免费使用一个浏览器，或使用 Pro）；开源版构建大约 2 个月后获得同一个完全开放、可复现的主版本。

像更新其他依赖一样升级这个包：

bash
npm i clearcote@latest          # Node
pip install -U clearcote        # Python
dotnet add package Clearcote    # .NET (adds or updates to the newest version)

下次调用 launch() 时，SDK 会发现所需的构建尚未缓存，于是下载它——开源版构建从 GitHub Releases 下载，授权版构建从 clearcotelabs.com 下载——并在使用前校验 SHA-256。任何未经校验的内容都不会运行。构建按版本分别缓存在你的用户缓存目录中——Windows 上是 %LOCALAPPDATA%\clearcote\Cache，Linux 上是 ~/.cache/clearcote（设置 CLEARCOTE_CACHE 可更改位置）——因此每个构建只需下载一次。旧构建会一直保留，直到你运行 clearcote clear-cache。

多个程序共用一个缓存

共用缓存的多个程序会轮流安装构建（SDK 0.41.0+，Python、Node 和 .NET 均如此）：第一个程序负责下载，其他程序等待，然后直接使用它；另一个程序正在运行的构建也不会在其运行时被替换。等待的程序会在 30 分钟后放弃，并给出一条消息，指出持有该安装的进程（锁就是该构建缓存文件夹中的 .install-lock 文件；消息会说明何时可以安全删除它）。崩溃的程序遗留下来的锁会被自动接管。

如果某个已缓存构建的文件损坏或被删除（例如被杀毒软件隔离、文件夹被删除），下次启动时会通过一次下载修复它。如果它的文件仍在使用中，启动会立即停止，并提示你关闭所有使用该浏览器的程序后重试。这个锁要求共用缓存的每个进程都运行 SDK 0.41.0 或更高版本；较旧的版本不会等待它。

Windows：某些环境无法在下载位置直接启动构建，例如运行在打包（MSIX）应用中的程序——Windows 会重定向它对 %LOCALAPPDATA% 的写入（启动会失败，报错 spawn UNKNOWN 或 "the side-by-side configuration is incorrect"）。这种情况下，SDK 会在 ~/.clearcote/recovered 中为该构建复制一份，之后 Python、Node 或 .NET 的每次启动都会使用这份副本，因此临时文件夹中不会留下任何东西，重复启动只需几秒（Python 和 Node 从 0.40.1 起，.NET 从 0.41.0 起）。clearcote clear-cache 也会删除这些副本；.NET SDK 没有命令行工具，因此请在其中调用 WinLaunch.ClearRecovered()。

不升级 SDK，只更新开源版构建

没有密钥时，可以开启自动更新，改用 GitHub 上最新的开源版构建，而不是 SDK 固定的版本。它会根据该版本的 SHA256SUMS.txt 进行校验（如果安装了 gpg，还会用签名密钥校验）；如果无法访问 GitHub，则回退到固定的构建。在命令行中运行 clearcote update 效果相同。有密钥时，这个选项不会带来任何变化——你拿到的本来就是当前的授权版构建。

javascript
import { launch } from "clearcote";
await launch({ autoUpdate: true });   // or set env CLEARCOTE_AUTO_UPDATE=1
浏览器本身从不联网回传数据，也不会自行更新。没有密钥时，只有在你升级 SDK 或开启 autoUpdate 时，浏览器才会变化。有密钥时，SDK 会在下次启动时获取每个新的授权版构建；Pro 可以用 version 固定某个构建。

选择构建

传入 version（或设置 CLEARCOTE_BROWSER_VERSION）：可以是 "latest"、大版本号（如 "156"）、精确版本 "156.0.8078.47"，或者授权版修订号 "r57" / "156.0.8078.47-r57"。在下载任何内容之前，版本号或大版本号会先与公开的版本目录核对，修订号则与许可证服务器核对。releaseChannel: "preview"（Python 中为 release_channel，或设置 CLEARCOTE_RELEASE_CHANNEL=preview）会在有预览构建时使用预览构建。在授权版构建上，旧构建、版本固定和预览通道随 Personal 和 Pro 提供——免费密钥始终获取最新版本。

bash
clearcote install --version 156        # fetch + verify a build ahead of time
clearcote install --channel preview     # the newest preview build (Pro)
clearcote info                          # what's installed and cached, and your key
clearcote clear-cache                   # delete cached builds

直接使用 / Docker 用户

  • 直接使用二进制文件（仅限开源版构建——授权版构建需要通过 SDK、clearcote serve 或 Docker 镜像运行）：从 Releases 页面下载新的压缩包，核对校验和与签名（参见验证），然后把 executable_path / executablePath（或 CLEARCOTE_BINARY）指向新的 chrome。
  • Docker：运行 docker pull teamflatearth/clearcote 获取最新镜像，然后重新创建容器。免费密钥需要基于 SDK 0.30.0 或更高版本构建的镜像。有密钥时，请挂载 -v clearcote-cache:/opt/xdg-cache，这样授权版构建只需下载一次，而不必在每个新容器里重新下载。参见部署。

授权版构建——始终最新，而且最先更新

授权版构建紧跟最新的 Chromium 和最新的补丁，你无需手动重新构建就能获得更新。设置 CLEARCOTE_LICENSE_KEY、传入 licenseKey，或运行 clearcote login（Python/Node；本地 npm 安装请用 npx clearcote login）——它会检查密钥并保存到 ~/.clearcote/license.key，所有 SDK（包括 .NET）都会读取这个文件。获取密钥有三种方式：

  • GitHub 免费版——同一时间运行一个浏览器，不收取任何费用。在控制台中打开“Licenses”，通过以下三种方式之一领取：连接注册至少 30 天的 GitHub 账号（“Connect GitHub and get it free”）、通过银行卡验证（绝不会从卡上扣款；预付卡会被拒绝），或使用公司 Google Workspace 账号登录（每个公司域名每 30 天最多领取 3 次）。每个 GitHub 账号、银行卡或 Google 账号限领一个密钥。密钥有效期 30 天；到期前可在同一页面免费续期。
  • Personal——同一构建，最多可同时运行 15 个浏览器，提供旧版构建、版本固定和预览通道；不含邮件支持。
  • Pro——同样的构建，最多可同时运行 250 个浏览器，另外提供旧版构建、版本固定和预览通道，以及由项目所有者提供的邮件支持。
新的大版本会先进入授权版构建。新的 Chromium 大版本构建完成后，会立即在 GitHub 免费版和 Pro 上提供；开源版构建要晚些才会获得这个大版本——目标是在其发布后约 2 个月（开源版构建目前基于 Chromium 151）。开源版构建始终完全开放、可复现；授权版构建则能更早用上最新版本。

授权浏览器如何计数

每个使用密钥启动的浏览器都会从许可证服务器占用一个名额，并在关闭时归还。控制台会显示当前占用的数量，clearcote info 也会输出同样的计数。

  • GitHub 免费版对每个浏览器都计数。只有一个名额，因此第二个浏览器——无论是在同一个程序、另一个程序还是另一台机器上——都会被拒绝，并提示 The free tier runs one browser at a time, and one is already running，直到第一个浏览器关闭。未正常关闭就崩溃的浏览器会在 6 分钟内释放它的名额。
  • Personal 按每个浏览器计数，最多同时 15 个。每个浏览器各占一个名额，无论在一台还是多台机器上；第 16 个会被拒绝，直到有一个关闭。Personal 需要 SDK 0.55.0 或更高版本（Profile Manager 0.19.0）。
  • Pro 最多可同时运行 250 个浏览器。使用 SDK 0.55.0 或更高版本时，每个浏览器各占一个名额，因此控制台按浏览器而不是按机器计数；较旧的 SDK 仍是每台机器共用一个名额。2026 年 9 月 26 日之前开始的订阅保留原先不设上限的条款；如果你需要超过 250 个，可以按 100 个一块增加，或联系我们。
  • 免费密钥需要 SDK 0.30.0 或更高版本（Python、Node 和 .NET），因为要统计每个浏览器，SDK 必须上报每次启动，并在浏览器运行期间持续刷新许可证状态。旧版 SDK 会收到 SDK_UPGRADE_REQUIRED 以及升级命令；即使旧版 SDK 仍然启动到了引擎这一步，也会在引擎处被拒绝。Pro 密钥和以前一样可以配合旧版 SDK 使用。
  • 名额失效时，免费浏览器会停止运行。检查是持续进行的，而不只在启动时：如果密钥被吊销、名额在别处被签入，或者许可证超出上限，已经打开的免费浏览器会在大约 2 到 3 分钟内关闭。短暂的网络中断（错过一两次心跳）不受影响；超过大约 2 到 3 分钟的中断同样会让免费浏览器停止运行。
  • 免费版始终运行最新构建。请求较旧的授权版构建或预览通道会返回 FREE_LATEST_ONLY；固定构建需要 Personal 或 Pro。
  • 免费密钥的下载限制：每 24 小时最多 10 个不同的构建。同一个构建无论启动多少次，都只计一次。
bash
pip install -U clearcote          # Python 0.30.0+
npm i clearcote@latest            # Node 0.30.0+
dotnet add package Clearcote      # .NET 0.30.0+

升级后会有哪些变化

大多数 SDK 版本都不需要你采取任何行动。下面这些版本会改变现有配置的行为；所有版本都列在控制台的“Releases”页面中。

  • 授权版 156 r53，浏览器默认设置：与 Chrome 一样，密码保存功能处于开启状态：登录后浏览器会提议保存密码（密码管理器中的“提议保存密码和通行密钥”设置可将其关闭）。Google 重新成为默认搜索引擎，新旧配置文件均是如此，因此在地址栏中输入的搜索会发往 Google；可在“设置 > 搜索引擎”中选择其他引擎。使用 Playwright 时，请搭配 SDK 0.63.3 或更新版本。身份不受影响。
  • 0.64.1：所有 SDK 中的 personaSchema / persona_schema / PersonaSchema 都接受 5 和 7。
  • 0.64.0，无许可证密钥：SDK 下载的开源版构建是 Chromium 151，版本 v0.1.0-pre.25，而不再是 150。version="150" 仍会获取 150 构建。
  • 自 2026-10-26 起提供的身份（r52，r51 也一样），现有种子：默认身份画像 schema 现在是 7，这是一种机器模型，由显卡决定机器的类型及其处理器、线程数、内存和屏幕，因此一个种子抽到的机器与之前不同。要保留种子在 r45 到 r51 上的身份，请设置 persona_schema=5 / personaSchema: 5。参见 不同机器上的同一个种子。
  • 授权版构建 156 r51：每次启动时身份都来自 Clearcote 身份画像服务，因此机器需要能通过出站 HTTPS 访问 persona.clearcotelabs.com（以及作为备用的 persona-us），浏览器需要 SDK 0.63.0 或更高版本（免费密钥需 0.63.2）、Profile Manager 0.27.0 或更高版本。r51 没有改变身份。参见 架构。
  • 授权版构建 155 r45，现有 Windows 种子：每个 Windows 配置文件会抽取各自的 Office 字体集，因此它的字体列表会变化一次。persona_schema=4 / personaSchema: 4 可完全保留 r44 的身份。
较早的说明（154 构建，SDK 0.40 到 0.42）
  • 授权版构建 154 r37，现有种子：种子现在会从机器自身显卡厂商更广泛的一系列真实型号中选取显卡，每个型号出现的概率与真实浏览器流量中的相同，因此大多数种子报告的显卡会与 r36 上不同；没有显卡的机器现在会声称 Intel 或 AMD 的集成显卡，而不再只是 Intel 的。种子的其余硬件没有任何变化。要保留种子在 r36 上的显卡，请设置 persona_schema=3 / personaSchema: 3；r36 之前的身份则照旧用 2 保留。参见不同机器上的同一个种子。
  • 授权版构建 154 r37，无头模式下的文件选择与打印：页面打开、而你的脚本没有处理的文件选择框，现在会保持打开 4 到 9 秒，然后被取消，就像不需要它的用户会做的那样；在它打开期间，该标签页无法打开弹出窗口或画中画窗口，与有头浏览器相同。window.print() 现在会让页面停留约 1.2 秒，然后触发 afterprint，就像用户关闭的打印预览。此前两者都在几毫秒内返回。通过 setInputFiles，或通过你的脚本处理的 filechooser 事件进行上传，与以前一样正常工作。
  • 授权版构建 154 r36，现有种子：种子现在会从机器自身显卡厂商的一系列真实型号中选取显卡，而不再是每个厂商只对应一个型号，因此大多数种子报告的显卡会与 r35 上不同。在配有 NVIDIA 显卡的机器上，原先声称入门级硬件（4 到 6 个处理器线程、4 到 8 GB 内存、小尺寸屏幕）的种子，现在会声称中端或更高的配置，而且在这类机器上没有任何种子会声称触摸屏。要保留种子在 r36 之前的身份，请设置 persona_schema=2 / personaSchema: 2。参见不同机器上的同一个种子。
  • 授权版构建 154 r36，第三方 Cookie：浏览器现在默认允许第三方 Cookie，与 Chrome 相同；即使较旧的 SDK 或你自己的启动器没有传入任何 Cookie 选项，也是如此。--block-third-party-cookies 会阻止它们。
  • 授权版构建 154 r36，无头模式下的权限请求：无头浏览器不再在网站请求权限（通知、摄像头、麦克风、位置等）的那一刻就立即拒绝。请求会保持未答复状态，就像有头浏览器中一个未处理的权限提示，因此等待 Notification.requestPermission() 或 getUserMedia() 的脚本现在会一直等待。请先授予权限（Playwright 的 context.grant_permissions() / context.grantPermissions()），或传入 --deny-permission-prompts 以恢复以前的拒绝行为。
  • 0.42.0，Linux 主机：Linux 身份画像的 WebGL 现在无论有头还是无头，都通过基于 EGL 的 Mesa 渲染（主机需要安装 libegl1），因此有头 Linux 身份画像的 WebGL 渲染器字符串、扩展列表和限制值会一次性改变，变为无头模式启动早已呈现、也是大多数真实 Linux 机器报告的形式。在没有窗口管理器的 Xvfb 下，有头模式启动时窗口会适配到屏幕。即使身份画像没有生效，无头模式启动也会保留逼真的显示器；只传入 --window-position 时，serve() 同样会保留它。参见Playwright & Puppeteer。
  • 154 r34 及更新的授权版构建，disableGpuFingerprint：它现在只改变 GPU 上报的内容。WebGL 像素回读会保留种子按站点生成的噪声，因此 readPixels 与 WebGL canvas 的导出结果保持一致。此前，它只会单独停止 readPixels 的噪声。参见指纹参数。
  • 0.41.1，拟人化输入：启用 humanize 后，滚动会像真实滚轮一样以完整的鼠标滚轮刻度为单位移动：Windows 身份上每格 100 px，Linux 上 120，macOS 上 40。请求的距离会四舍五入到最接近的刻度（至少一格），因此 mouse.wheel(0, 800) 在 Windows 上滚动 800 px，在 Linux 上滚动 840。打字时，在快速连按的键对上，现在有时会在松开前一个键之前就按下下一个键。在 .NET 中，用数字作为种子的 humanizer 现在与 Python 和 Node 中的运动身份相同；此前，所有非零数字种子共用同一个运动身份。参见拟人化输入。
  • 0.41.0，r32 起的授权版构建：身份画像通过环境变量而不是命令行传给浏览器，因此从进程列表中读取种子的工具将再也找不到它（persona_env=False 保留旧方式）。本地启动创建的上下文不再模拟浅色配色方案，因此深色身份画像在各处都报告深色（传入 color_scheme 可固定一种）。带身份画像的无头 Linux 启动会获得与身份画像所声称尺寸相同的屏幕。参见启动选项。
  • 0.41.0，Linux 上的 .NET：启动现在使用浏览器自带的字体，而不是主机的字体，与 Python 和 Node 一贯的做法相同。那里的 Windows 身份画像测量结果会因此不同，现在与另外两个 SDK 一致。参见在 Linux 上使用你自己的字体。
  • 0.41.0，Windows 电脑上的 Linux 身份画像：SDK 会在每个进程中警告一次。Windows 通过 Direct3D 驱动 GPU，这会压低 WebGL 和 WebGPU 的限制值；身份画像可以调低某个限制值，但无法把它调到超过驱动的值，因此在那里，Linux 身份画像报告的限制值是任何 Linux 机器都不会有的。请在 Windows 上声明 Windows，或者在 Linux 上或 Docker 中运行 Linux 身份画像。quiet 或 CLEARCOTE_NO_WARN 可以关闭该警告。
  • Docker 镜像 sdk-0.41.0：如果使用镜像的 seccomp 配置文件启动容器，Chrome 可以带着沙箱运行；不使用该配置文件时，容器的运行方式与之前相同。内置了各书写系统字体。参见部署。
  • 0.40.0：在 macOS 上，launch() 会运行 Clearcote Docker 镜像（需要 Docker Desktop；docker=False 可将其关闭）。参见 macOS。

升级之后，重新验证

新构建可能会改变某个信号。请重新运行你的指纹检测（例如 CreepJS），如果使用了导入的配置文件，请确认它仍能一致地加载——参见验证。当前的开源版构建是 v0.1.0-pre.25（Chromium 151.0.7922.108）；当前的授权版构建是 156.0.8078.47-r57。接下来的计划见路线图。