Lighthouse
執行 Google Lighthouse 來測量網頁品質，並驗證修復確實讓數據有所改善。Lighthouse 會稽核指定 URL 的效能、無障礙性、SEO 和最佳實踐，為每個類別回傳 0–100 的評分，以及一份包含具體指導說明的失敗稽核清單。
何時使用此技能
此技能負責測量。同系列的其他技能負責修復。工作流程是一個循環：
測量（此技能） → 修復（效能/無障礙性/SEO/最佳實踐） → 重新測量
當你需要：取得基準分數、找出具體的失敗稽核、設定效能預算、在 CI 中閘控建置、或證明某項改進（或回歸）時，請使用此技能。不要憑空猜測改進 — 測量、改變一件事、再次測量。
運作方式
- 選擇目標 URL — 一個已部署的 URL，或一個本機開發/預覽伺服器（
http://localhost:3000）。 - 執行 Lighthouse — 建議使用
scripts/run-lighthouse.sh <url>；它會多次執行，選取中位數，並輸出精簡的 JSON（完整的報告檔案很大，會浪費上下文）。 - 讀取類別評分和失敗稽核 從 JSON 中。
- 將每個失敗稽核對應到修復 使用相關的品質技能。
- 重新執行 並回報前後的差異。
安裝與執行 (CLI)
Lighthouse 的說明文件建議全域安裝（需要 Node 22 LTS+），並且需要你系統上已安裝一個Chrome/Chromium：
npm install -g lighthouse
# 或：yarn global add lighthouse
lighthouse https://example.com --view # 基本執行；--view 會開啟 HTML 報告
Lighthouse 會自動偵測已安裝的 Chrome；你也可以使用 CHROME_PATH 環境變數指定特定的二進位檔。
如果你只是想快速執行一次而不想全域安裝，也可以使用 npx lighthouse <url> — 發佈的 CLI 二進位檔支援此用法，雖然官方文件只涵蓋全域安裝。
適合代理程式的機器可讀執行（輸出 JSON 到檔案，安靜模式，無頭模式）：
npx lighthouse https://example.com \
--quiet \
--chrome-flags="--headless=new" \
--only-categories=performance,accessibility,seo,best-practices \
--output=json --output-path=./lh.json
包裝腳本（建議使用）
scripts/run-lighthouse.sh 包裝了 CLI，執行 N 次，選取中位數（Lighthouse 官方建議的減少變異方法），並將精簡的 JSON 輸出到 stdout — 只包含類別評分和失敗稽核。人類可讀的日誌則輸出到 stderr。
# 用法：run-lighthouse.sh <url> [執行次數] [類別]
skills/lighthouse/scripts/run-lighthouse.sh https://example.com 3
skills/lighthouse/scripts/run-lighthouse.sh http://localhost:3000 5 performance,accessibility
輸出範例：
{
"success": true,
"url": "https://example.com",
"runs": 3,
"lighthouseVersion": "13.x",
"scores": { "performance": 78, "accessibility": 95, "seo": 92, "best-practices": 96 },
"failingAudits": [
{ "id": "largest-contentful-paint", "score": 0.4, "displayValue": "4.2 s" },
{ "id": "unused-javascript", "score": 0.3, "displayValue": "Potential savings of 180 KiB" }
]
}
主要標誌
| 標誌 | 用途 |
|---|---|
--output=json|html|csv | 報告格式（可重複多次以輸出多種格式） |
--output-path=<path> | 報告寫入位置 |
--only-categories=… | 限制稽核範圍為 performance,accessibility,seo,best-practices |
--preset=desktop | 桌面版設定（預設為行動版：模擬中階手機 + 慢速 4G 網路） |
--chrome-flags="--headless=new" | 無頭模式執行（適用於 CI/伺服器） |
--budget-path=budget.json | 強制執行效能預算（LightWallet） |
--throttling-method=simulate|devtools|provided | 節流方式（simulate 為預設的實驗室節流） |
--quiet | 抑制進度日誌 |
--view | 執行完成後開啟 HTML 報告 |
讀取 JSON
評分是 categories 下的 0–1 浮點數；稽核細節在 audits 下。
# 類別評分 (0–1) → 乘以 100 得到常見的百分制評分
jq '.categories | to_entries | map({(.key): (.value.score)}) | add' lh.json
# 核心網頁指標的實驗室數值
jq '.audits | {
LCP: .["largest-contentful-paint"].displayValue,
CLS: .["cumulative-layout-shift"].displayValue,
TBT: .["total-blocking-time"].displayValue
}' lh.json
# 值得處理的失敗/機會稽核
jq '[.audits[] | select(.score != null and .score < 0.9)
| {id, score, displayValue}]' lh.json
效能預算 (LightWallet)
當資源或時間超過門檻值時，讓稽核失敗。此技能附帶一個可直接編輯的 examples/budget.json；其格式如下：
[
{
"path": "/*",
"timings": [
{ "metric": "largest-contentful-paint", "budget": 2500 },
{ "metric": "interactive", "budget": 3800 }
],
"resourceSizes": [
{ "resourceType": "script", "budget": 300 },
{ "resourceType": "stylesheet", "budget": 100 },
{ "resourceType": "image", "budget": 500 },
{ "resourceType": "total", "budget": 1500 }
],
"resourceCounts": [
{ "resourceType": "third-party", "budget": 10 }
]
}
]
lighthouse https://example.com --budget-path=budget.json --output=json --output-path=./lh.json
大小單位為 KB，時間單位為 ms。預算結果會放在 JSON 中的 performance-budget 和 timing-budget 稽核底下。
實驗室數據 vs. 實測數據 — 在信任數字前請先閱讀
Lighthouse 是一個實驗室工具：一次合成載入，在模擬硬體上，使用模擬節流。它可重現，非常適合捕捉回歸問題，但不是真實使用者的體驗。
- 變異是真實存在的。 單次執行可能會有 ±5–10 分的波動。至少執行 3 次並取中位數（包裝腳本已處理此問題）。
- 如需真實使用者資料，請改用實測來源：CrUX、PageSpeed Insights（會同時顯示實驗室 + 實測數據）、Search Console 的 Core Web Vitals 報告，或將
web-vitals函式庫回報至你的分析系統。 - INP 無法透過單次 Lighthouse 載入測量 — 它需要真實的互動。Lighthouse 報告 Total Blocking Time (TBT) 作為其實驗室代理指標；請以實測的 INP 為準。
Lighthouse v13 說明（Insight Audits）
自 v13（2025 年 10 月+）起，Lighthouse 將效能稽核遷移至 Insight Audits。數個舊有的機會稽核 ID 被合併或移除（例如 CLS 相關稽核 → cls-culprits-insight，圖片稽核 → image-delivery-insight）。建議本身不變；只有稽核 ID 和報告分組方式改變。當解析舊版報告時，請將其視為超集，而非矛盾。在 CI 中鎖定一個 Lighthouse 版本，以確保你斷言所依賴的稽核 ID 保持穩定。
效能評分的構成方式
效能評分是實驗室指標的加權混合（權重在不同版本間會變動）。在最近的版本中，主要權重大致如下：
| 指標 | 約略權重 |
|---|---|
| Total Blocking Time (TBT) | ~30% |
| Largest Contentful Paint (LCP) | ~25% |
| Cumulative Layout Shift (CLS) | ~25% |
| First Contentful Paint (FCP) | ~10% |
| Speed Index | ~10% |
由於 TBT/LCP/CLS 佔主導地位，修復這些指標最能提升評分。使用 Lighthouse Scoring Calculator 來查看指標變化如何確切影響分數。
CI 與程式化 API
保留在參考文件中以保持專注：
- 持續整合 —
@lhci/cli、lighthouserc.js斷言、以及一個 GitHub Actions 工作流程：references/CI.md - 程式化 (Node) API — 使用
chrome-launcher驅動 Lighthouse 以實現自訂流程、使用者流程和批次執行：references/PROGRAMMATIC-API.md
將稽核對應到修復
| Lighthouse 類別 | 使用哪個技能修復 |
|---|---|
| 效能 / Core Web Vitals | 一個效能或 Core Web Vitals 技能 |
| 無障礙性 | 一個無障礙性 / WCAG 技能 |
| SEO | 一個 SEO 技能 |
| 最佳實踐 | 一個安全 / 最佳實踐技能 |
將此技能與 addyosmani/web-quality-skills 配對，以實現循環中的修復環節。