让 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，只更新开源版构建

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

clearcote install --version 153        # 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——同样的构建，Beta 期间不限制同时运行的浏览器数量，另外提供旧版构建、版本固定和预览通道，以及由项目所有者提供的邮件支持。

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

授权浏览器如何计数

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

• GitHub 免费版对每个浏览器都计数。只有一个名额，因此第二个浏览器——无论是在同一个程序、另一个程序还是另一台机器上——都会被拒绝，并提示 The free tier runs one browser at a time, and one is already running，直到第一个浏览器关闭。未正常关闭就崩溃的浏览器会在 6 分钟内释放它的名额。
• Pro 按机器计数，Beta 期间不设上限。同一台机器上的所有浏览器共用这台机器的名额。
• 免费密钥需要 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+

升级之后，重新验证

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