2026 OpenClaw 前端实战:
远程 Mac 解析 Unlighthouse JSON、死链阈值判定与 Lighthouse 回归摘要回传 PR
面向前端平台与发布负责人:预览合并前既要抓全站死链与 4xx,又要对关键路由做Lighthouse 性能回归,但 Linux CI 离预览 CDN 远、笔记本合盖会掐断长扫。本文在长期在线的远程 Mac上给出可复现流水线:Unlighthouse 产出 JSON、死链/ LCP·CLS 阈值表、OpenClaw 聚合 Markdown 回传 PR 或 Webhook。含选型对照、字段说明、七步落地与 FAQ。延伸阅读 预览 Lighthouse Webhook、Bugsnag Build × Lighthouse。
痛点拆解(编号)🚀
一只对首页跑单次 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。
- Node 24+:
fnm install 24 && fnm use 24;全局或项目内corepack enable。 - 依赖:
pnpm add -D @unlighthouse/cli lighthouse @lhci/cli(版本锁在 lockfile)。 - 网关:登记
/hooks/unlighthouse-preview、HMAC 密钥、Idempotency-Key: ${git_sha}:unlighthouse(对齐 Webhook 专文)。 - 环境变量:
PREVIEW_URL、OPENCLAW_RUN_ID、GITHUB_TOKEN(只读 PR 评论)、勿把令牌写进 JSON 工件。 - 目录约定:
.openclaw/reports/${OPENCLAW_RUN_ID}/下放unlighthouse.json与*.lhr.json。 - 预热:对
PREVIEW_URL与/sitemap.xml幂等 GET 至 200,降低冷启动假 4xx。 - 执行扫描:
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);
④ 死链 / 4xx 阈值与阻断规则
建议把阈值写入仓库 .openclaw/thresholds.json,由 OpenClaw 与 JUnit 门禁 同一退出码语义(失败 exit 1 阻断合并)。
| 规则 ID | 条件 | 建议阈值(预览) | 动作 |
|---|---|---|---|
| DL-01 | status >= 400 的路由数 |
0(生产预览零容忍) | 阻断 + PR 列出 path |
| DL-02 | status >= 500 |
0 | 立即阻断,标 P0 |
| DL-03 | 重定向链长度 | ≤ 3 | 警告或阻断(按团队) |
| DL-04 | 站外链接 4xx(若爬取) | ≤ 5 条 | 警告,不阻断合并(可选) |
| DL-05 | 扫描未完成 routes 占比 | < 2% | 阻断(防止半成品报告签字) |
⑤ 性能回归(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 评论键。
- 合并 死链表(path、status、来源链接)与 性能差分(Δ LCP/CLS)。
- 附上工件 URL(仪表盘 HTML、
unlighthouse.json),正文不含 Cookie。 - 若接 GitHub Deployments,写入
target_url指向报告(见 Deployments 专文)。 - Webhook 模式:网关返回 202,Runner 完成后 PATCH 检查运行状态。
- 失败时
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 节点:Unlighthouse 全站扫 + Lighthouse 签字同机跑通
继续阅读 预览 Lighthouse Webhook、Playwright HTML 报告 PR 摘要;首页、购买页、SSH/VNC 指南 均免登录。博客列表 含更多 OpenClaw 与 Lighthouse 专题。