🕸️ 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 前端構建節點