🕸️ Unlighthouse · 死链门禁 · Lighthouse 回归 · 远程 Mac · 二零二六

2026 OpenClaw 前端实战:
远程 Mac 解析 Unlighthouse JSON、死链阈值判定与 Lighthouse 回归摘要回传 PR

2026.05.20 前端 CI · 发布门禁 约 10 分钟阅读

面向前端平台与发布负责人:预览合并前既要抓全站死链与 4xx,又要对关键路由做Lighthouse 性能回归,但 Linux CI 离预览 CDN 远、笔记本合盖会掐断长扫。本文在长期在线的远程 Mac上给出可复现流水线:Unlighthouse 产出 JSON、死链/ LCP·CLS 阈值表、OpenClaw 聚合 Markdown 回传 PR 或 Webhook。含选型对照、字段说明、七步落地与 FAQ。延伸阅读 预览 Lighthouse Webhook、Bugsnag Build × Lighthouse。

阈值对照表 · HowTo 七步 · JSON 字段 · FAQ

痛点拆解(编号)🚀

一只对首页跑单次 lighthouse URL,合并后内页404 与错误重定向仍上线,评审在真机 Safari 才暴雷。

二全站爬虫在 GitHub Actions 上常超时或被限流,报告散在工件里,PR 只有一行绿/red 无法定位路由。

三性能分在 Chromium 过关,WebKit LCP 因字体与合成层仍退化;需与 Safari Playwright 矩阵 分工,不能混为一谈。

① Unlighthouse vs 单次 Lighthouse CLI 选型

决策原则:发现面用 Unlighthouse,签字包络对 3–5 条黄金路由保留 Lighthouse CLI 或 LHCI;二者 JSON 可并进同次 OPENCLAW_RUN_ID。

维度 Unlighthouse(全站 CI) 单次 Lighthouse CLI
覆盖范围 爬取 sitemap/站内链,批量 routes 单 URL 或 lighthouserc 声明的少数 URL
死链 / 4xx 原生统计 HTTP status,适合门禁 不爬站内链,需另配 link checker
耗时与稳定性 分钟级,宜放远程 Mac 长任务队列 数十秒,适合 PR 热路径
输出形态 report.json + 可选 HTML 仪表盘 lhr.json / LHCI manifest
推荐组合 Unlighthouse 阻断死链 → 对 Top 路由跑 Lighthouse → OpenClaw 合并摘要(见 Deployments 联动)

② 远程 Mac 上安装 Node 24+ 与 OpenClaw 网关

与 Playwright HTML 报告聚合 同构:网关只验签入队,重活在 Runner。

  1. Node 24+:fnm install 24 && fnm use 24;全局或项目内 corepack enable。
  2. 依赖:pnpm add -D @unlighthouse/cli lighthouse @lhci/cli(版本锁在 lockfile)。
  3. 网关:登记 /hooks/unlighthouse-preview、HMAC 密钥、Idempotency-Key: ${git_sha}:unlighthouse(对齐 Webhook 专文)。
  4. 环境变量:PREVIEW_URL、OPENCLAW_RUN_ID、GITHUB_TOKEN(只读 PR 评论)、勿把令牌写进 JSON 工件。
  5. 目录约定:.openclaw/reports/${OPENCLAW_RUN_ID}/ 下放 unlighthouse.json 与 *.lhr.json。
  6. 预热:对 PREVIEW_URL 与 /sitemap.xml 幂等 GET 至 200,降低冷启动假 4xx。
  7. 执行扫描:npx unlighthouse-ci --site "$PREVIEW_URL" --build-static --output-path "./.openclaw/reports/${OPENCLAW_RUN_ID}"(参数以项目 unlighthouse 配置为准)。

③ Unlighthouse CI 输出 JSON 字段说明

门禁脚本只读下列键;完整 schema 以当次 CLI 版本为准,建议在仓库固定 reportSchemaVersion 做快照测试。

JSON 路径 含义 门禁用途
site 扫描根 URL、完成时间 与 PREVIEW_URL 对齐,防扫错环境
routes[] 每路由 path、status、redirectChain 筛 status >= 400 与循环重定向
routes[].lighthouse 嵌套 LHR 或分数摘要 与独立 lhr.json 交叉校验
summary.errorRoutes 聚合错误路由数 快速与阈值 maxErrorRoutes 比较
reports.dashboardPath 本地 HTML 报告相对路径 上传工件后写入 PR 链接(脱敏)
// 死链计数骨架(Node 24)
import { readFileSync } from "node:fs";
const r = JSON.parse(readFileSync(process.env.UNLH_JSON, "utf8"));
const dead = (r.routes ?? []).filter((x) => x.status >= 400);
if (dead.length > Number(process.env.MAX_DEAD_LINKS ?? 0)) process.exit(1);

⑤ 性能回归(LCP / CLS)阈值表

自 Unlighthouse 嵌套 LHR 或并行 CLI 读取 mobile 审计;数值宜对齐近五次绿构建中位数 + 余量,与 budgets.json 一致。

指标 字段(LHR audits) 预览起点 回归判定
Performance 分 categories.performance.score ≥ 0.85 较 base 分支 Δ < −0.05 阻断
LCP largest-contentful-paint ≤ 2500 ms 较 base +400 ms 阻断
CLS cumulative-layout-shift ≤ 0.1 较 base +0.05 阻断
TBT(辅助) total-blocking-time ≤ 300 ms 仅警告(与 Bugsnag 文一致)

⑥ OpenClaw 聚合报告并回传 PR 评论 / Webhook

聚合器读取 .openclaw/reports/${OPENCLAW_RUN_ID}/,输出单行或短表格 Markdown,并用隐藏 HTML 锚点做幂等 PR 评论键。

  1. 合并 死链表(path、status、来源链接)与 性能差分(Δ LCP/CLS)。
  2. 附上工件 URL(仪表盘 HTML、unlighthouse.json),正文不含 Cookie。
  3. 若接 GitHub Deployments,写入 target_url 指向报告(见 Deployments 专文)。
  4. Webhook 模式:网关返回 202,Runner 完成后 PATCH 检查运行状态。
  5. 失败时 exit 1,摘要首行写 ❌ Unlighthouse gate 与规则 ID。
<!-- OPENCLAW_PR_ANCHOR:unlighthouse:${OPENCLAW_RUN_ID} -->
**Unlighthouse** · run `${OPENCLAW_RUN_ID}` · dead **0** · perf **0.87** · LCP **2.1s** · [dashboard](artifact-url)

⑦ Safari / WebKit 联调注意

Unlighthouse 默认走 Chromium,不能替代苹果侧签字。建议对首页与结账流在远程 Mac 硬件 Safari 或 Playwright webkit 抽检 LCP;字体子集与 content-visibility 差异会导致 Unlighthouse 绿而 Safari 红。将 WebKit 结论以第二段贴在同一 PR 锚点下,避免与 Chromium 分数混排误导评审。

⑧ 常见报错 FAQ

问:扫描超时 / ENOTFOUND?
答:缩小 maxRoutes、检查预览 DNS 与 VPN;先预热再扫。

问:routes 为空?
答:根 URL 非 200、robots.txt 封禁或 Basic Auth 未注入 PREVIEW_AUTH。

问:死链 0 仍 exit 1?
答:查 LCP/CLS 回归或 summary.errorRoutes 与未完成路由占比 DL-05。

问:与 Playwright 报告重复?
答:E2E 管交互,Unlighthouse 管链接图;OpenClaw 分节合并即可。

据 可引用信息(至少三条)

口径一 · 扫描预算

M 系远程 Mac 全站 Unlighthouse(≤500 routes)建议 wall time 8–12 分钟,worker 间隔 ≥ 200 ms 防预览限流。

口径二 · 死链

生产预览门禁 DL-01:status≥400 路由数必须为 0。

口径三 · 性能

黄金路由 LCP 较 base 分支恶化超过 400 ms 即阻断合并(与仓库 budgets 对齐)。

远程 Mac · 前端 CI · 免登录选型

选择你的 Mac 节点:Unlighthouse 全站扫 + Lighthouse 签字同机跑通

继续阅读 预览 Lighthouse Webhook、Playwright HTML 报告 PR 摘要;首页、购买页、SSH/VNC 指南 均免登录。博客列表 含更多 OpenClaw 与 Lighthouse 专题。

博客列表 · 首页 · 购买页

租远程 Mac 跑 Unlighthouse