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 專題。