提升易用性：Lighthouse CI 讓效能變化一目了然

Lighthouse CI 是由 Google 官方推出的工具，幫助開發者能在 CI/CD 流程中自動化執行 Lighthouse 分析，追蹤網站效能是否因程式碼變更而退化，並及早發現問題。

此工具主要解決了 Lighthouse 手動執行繁瑣且無法追蹤歷史資料變化的問題。

使用範例

以下範例示範如何在 GitLab CI 中設定，於 Merge Request 事件觸發時自動執行 Lighthouse CI 掃描，並將報告上傳至 Google 官方提供的暫存儲存空間。

# .gitlab-ci.yml
image: cypress/browsers:latest

stages:
  - test

lhci:
  stage: test
  script:
    - npm ci
    - npm run build
    - npm install -g @lhci/cli@0.14.x
    - lhci autorun
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"' # Merge Request 事件觸發
      when: always
    - when: never

module.exports = {
  ci: {
    collect: {
      staticDistDir: "<your-dist-folder>",
      settings: { chromeFlags: "--no-sandbox" },
    },
    upload: {
      target: "temporary-public-storage", // 官方暫存報告儲存空間
    },
  },
};

上傳報告的儲存目標設定（upload.target）

upload.target 用於決定 Lighthouse CI 報告的儲存方式，目前支援以下三種模式：

target 值	優勢	限制 / 注意事項
temporary-public-storage	最快速、零成本的設定方式 - 報告會上傳至 GCP，持連結即可查看 - 報告會於數日後自動刪除	- 報告是公開的，任何持有連結皆可存取 - 無法儲存歷史紀錄或進行差異比較 - 不適合有隱私或長期追蹤需求的場景
lhci	- 可永久儲存報告並控管存取權限 - 支援歷史比較、趨勢圖與 PR 狀態檢查等功能	- 需自行部署 Lighthouse CI Server（含資料庫） - 需設定 build token、server URL 等資訊
filesystem	- 報告會以 JSON/HTML 格式儲存在本地或 CI artifact，適合進行離線分析或整合至自定義流程	- 無法線上分享，亦無 Web UI 支援 - 不支援 GitHub 狀態檢查與差異比對功能

設定效能通過門檻（assertions）

預設情況下，Lighthouse CI 不會因分數下降而使 CI 流程失敗。若希望自動檢查分數是否達到標準，則可透過設定 assert 區塊，明確定義通過門檻。

如:

// lighthouserc.js
module.exports = {
  ci: {
    collect: {
      staticDistDir: ".next",
      settings: { chromeFlags: "--no-sandbox" },
    },
    assert: {
      assertions: {
        "categories:performance": ["error", { minScore: 0.8 }],
        "categories:accessibility": ["warn", { minScore: 0.8 }],
        "categories:best-practices": ["warn", { minScore: 0.8 }],
        "categories:seo": ["warn", { minScore: 0.8 }],
      },
    },
    upload: {
      target: "temporary-public-storage",
    },
  },
};

若設定為 warn，當分數未達標時，CI 流程會顯示警告，但不會失敗。
若設定為 error，當分數未達標時，CI 流程將直接失敗，阻擋合併或部署。

Lighthouse CI server

除了自動化執行 Lighthouse 分析外，Lighthouse CI 也提供一個 Lighthouse CI server，用於儲存和管理每次掃描產生的報告，方便追蹤網站效能歷史變化。

這個 Server 是一個開源的 Node.js 服務，需要自行部署在 AWS、GCP、Heroku 或本地機器等環境。部署完成後，團隊就能集中管理報告、追蹤效能趨勢。

部署方式會因環境而異，官方提供詳細的部署指南，建議依照自己的基礎設施選擇合適方案。

為什麼要用 Lighthouse CI server？

集中管理報告：所有 Lighthouse 分析結果會集中存放，方便團隊檢視和回溯。
效能趨勢追蹤：透過歷史報告，比對每次掃描的分數與詳細資料，掌握效能是否退化。
支援多分支：能同時管理多個分支的效能報告，符合團隊需求。
CI 整合：搭配 CI/CD 流程，自動上傳與更新報告。

快速整合 Lighthouse CI server

完成 server 部署後，確保能連線，再執行：

npm install -g @lhci/cli@0.14.x   # 安裝 CLI
lhci wizard   # 執行專案建立嚮導

建立後會取得兩組 Token：

Build Token：用於 CI 上傳報告，可分享給外部協作者，權限較低。

Admin Token：用於專案管理（修改、刪除），請妥善保管，避免外洩。

接著，在 CI 平台設定環境變數（如 LHCI_TOKEN 為 Build Token），並更新 lighthouserc.js：

// lighthouserc.js
module.exports = {
  ci: {
    upload: {
      target: "lhci", // 由先前的 temporary-public-storage 調整成自行建立的 LHCI Server
      serverBaseUrl: process.env.LHCI_SERVER_URL,
      token: process.env.LHCI_TOKEN,
    },
  },
};