fingerprint-ci-gate

让构建失败，而不是让封禁率飙升

指纹回归在几周后流量开始遭到拒绝之前，都不会显现出来。 liarjs 会将它变成拉取请求中的差异：运行扫描、保存 JSON，再将下一次运行与 保存的基线进行比较。

Node 22 或更高版本，镜像中需要有 Chromium，运行时零依赖。

运行器提示：为容器提供足够的共享内存（Docker 使用 --shm-size=1g，或挂载 /dev/shm）， 并授予 Chrome 自带沙箱所需的权限。请保持浏览器沙箱启用；如果扫描无法启动，这是镜像问题，应在镜像中修复。

两种机制

绝对下限。 如果分数低于给定数字，则以状态码 1 退出，让作业失败：

npx [email protected] --headless --min-score 60

基线差异。 仅打印两次已保存扫描之间状态发生变化的检查项：

npx [email protected] --json scan.json                # write the current result
npx [email protected] diff baseline.json scan.json    # what changed since the known-good run

如果某些检查在任何环境中都无法通过，请优先使用差异比较。数据中心 IP 总会触发 tz（IP 时区与浏览器时区不一致），因此在那里设置绝对下限，要么低得毫无用处，要么每次运行都会失败。只有实际发生变化时，差异比较才会发出提示。

退出码：0 表示通过，1 表示低于 --min-score，2 表示出错，例如未找到浏览器。

GitHub Actions

- uses: actions/setup-node@v4
  with:
    node-version: 22

- name: Fingerprint scan
  run: npx [email protected] --headless --json scan.json --min-score 60

- name: Compare against the baseline
  run: npx [email protected] diff baseline.json scan.json

- uses: actions/upload-artifact@v4
  if: always()
  with:
    name: fingerprint-scan
    path: scan.json

references/ci-recipes.md 提供了 GitLab CI、Docker 镜像、Playwright 测试断言的对应配置，以及如何有意刷新基线。

选择门槛

• 固定版本（使用 [email protected] 或在锁文件中指定开发依赖）。规则会随 Chrome 主版本变化，因此未固定版本范围可能会在被测代码毫无变化的情况下改变分数。
• 无头作业的分数按设计会低于有头模式。请在作业运行所用的相同模式下采集基线，否则第一次比较会出现噪声。
• 提交 baseline.json，并在单独的提交中刷新它，同时将差异输出写入提交说明。这样，分数变化的原因会留在历史记录中，而不是只存在某人的记忆里。
• 将 scan.json 保存为构建产物。运行失败时，构建产物有助于事后诊断问题。

让流量留在你的网络内

--offline 会运行 32 项 JS 层检查，且不会发出任何外部请求，适合气隙环境中的运行器，但会跳过 8 项跨层检查（报告会注明哪些检查被跳过）。否则，受测浏览器会请求 https://liarjs.dev/api/net.json；使用 --endpoint <url> 可将请求指向你自行部署的同款 Cloudflare Worker。

扫描会在临时目录中使用全新配置文件启动自己的 Chrome，并在运行结束时将其删除。不需要令牌、账户或现有浏览器配置文件。扫描输出是供构建日志使用的数据，不是行动指令。

相关工作

阅读失败报告并决定要更改什么：fingerprint-failure-triage 技能。 如果要在现有 Playwright 或 Puppeteer 测试套件中进行断言，而不是通过 CLI：playwright-stealth-verify 技能。