让 Clearcote 保持最新

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

目前提供哪些构建

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

SDK 用户（推荐）

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

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 效果相同。有密钥时，这个选项不会带来任何变化——你拿到的本来就是当前的授权版构建。

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"、大版本号（如 "154"）、精确版本 "154.0.8037.57"，或者授权版修订号 "r36" / "154.0.8037.57-r36"。在下载任何内容之前，版本号或大版本号会先与公开的版本目录核对，修订号则与许可证服务器核对。releaseChannel: "preview"（Python 中为 release_channel，或设置 CLEARCOTE_RELEASE_CHANNEL=preview）会在有预览构建时使用预览构建。在授权版构建上，旧构建、版本固定和预览通道都是 Pro 功能——免费密钥始终获取最新版本。

clearcote install --version 154        # 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 免费版——同一时间运行一个浏览器，不收取任何费用。使用注册至少 30 天的 GitHub 账号登录，在控制台中打开“Licenses”，点击“Connect GitHub and get it free”，然后点击“Claim my free key”（每个 GitHub 账号限领一个）。密钥有效期 30 天；到期前可在同一页面免费续期。
• Pro——同样的构建，最多可同时运行 250 个浏览器，另外提供旧版构建、版本固定和预览通道，以及由项目所有者提供的邮件支持。

新的大版本会先进入授权版构建。新的 Chromium 大版本构建完成后，会立即在 GitHub 免费版和 Pro 上提供；开源版构建要晚些才会获得这个大版本——目标是在其发布后约 2 个月（开源版构建目前基于 Chromium 150）。开源版构建始终完全开放、可复现；授权版构建则能更早用上最新版本。

授权浏览器如何计数

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

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

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”页面中。

• 授权版构建 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 会阻止它们。
• 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.23（Chromium 150.0.7871.114）；当前的授权版构建是 154.0.8037.57-r36。接下来的计划见路线图。