如何將 Lighthouse 新增至持續整合系統，例如 GitHub Actions。
Lighthouse CI 是一套工具，可在持續整合期間使用 Lighthouse。Lighthouse CI 可透過多種方式整合至開發人員工作流程。本指南涵蓋下列主題：
- 使用 Lighthouse CI CLI。
- 設定 CI 供應商，執行 Lighthouse CI。
- 為 Lighthouse CI 設定 GitHub Action 和狀態檢查。這會自動在 GitHub 提取要求上顯示 Lighthouse 結果。
- 為 Lighthouse 報表建立效能資訊主頁和資料儲存庫。
總覽
Lighthouse CI 是一套免費工具，可協助使用 Lighthouse 監控效能。單一 Lighthouse 報表會提供網頁執行時的成效匯報；Lighthouse CI 則會顯示這些發現結果隨時間變化的情況。這可用於找出特定程式碼變更的影響，或確保在持續整合程序中達到效能門檻。雖然效能監控是 Lighthouse CI 最常見的用途，但也可以用於監控 Lighthouse 報表的其他方面，例如 SEO 或無障礙功能。
Lighthouse CI 的核心功能由 Lighthouse CI 指令列介面提供。(注意：這與 Lighthouse CLI 是不同的工具)。Lighthouse CI CLI 提供一組指令，用於使用 Lighthouse CI。舉例來說，autorun 指令會執行多個 Lighthouse 執行作業、找出中位數 Lighthouse 報表，並上傳報表進行儲存。您可以傳遞額外旗標，或自訂 Lighthouse CI 的設定檔 lighthouserc.js，大幅自訂這項行為。
雖然 Lighthouse CI 的核心功能主要封裝在 Lighthouse CI CLI 中，但 Lighthouse CI 通常會透過下列其中一種方式使用：
- 在持續整合過程中執行 Lighthouse CI
- 使用 Lighthouse CI GitHub Action，在每個提取要求上執行並加上註解
- 透過 Lighthouse Server 提供的資訊主頁，追蹤一段時間內的成效。
這些方法都是以 Lighthouse CI CLI 為基礎。
Lighthouse CI 的替代方案包括第三方效能監控服務，或自行編寫指令碼，在 CI 程序中收集成效資料。如果您希望由他人管理效能監控伺服器和測試裝置，或希望擁有通知功能 (例如電子郵件或 Slack 整合)，而不必自行建構這些功能，則應考慮使用第三方服務。
在本機使用 Lighthouse CI
本節說明如何在本機執行及安裝 Lighthouse CI CLI，以及如何設定 lighthouserc.js。在本機執行 Lighthouse CI CLI，是確保 lighthouserc.js 設定正確的最簡單方法。
安裝 Lighthouse CI CLI。
npm install -g @lhci/cli如要設定 Lighthouse CI，請在專案存放區的根目錄中放置
lighthouserc.js檔案。這個檔案為必要檔案，包含 Lighthouse CI 相關設定資訊。雖然 Lighthouse CI 可以設定為不使用 Git 存放區，但本文中的操作說明假設您的專案存放區已設定為使用 Git。在存放區的根目錄中，建立
lighthouserc.js設定檔。touch lighthouserc.js在
lighthouserc.js加入以下程式碼。這段程式碼是空白的 Lighthouse CI 設定。您會在後續步驟中新增這項設定。module.exports = { ci: { collect: { /* Add configuration here */ }, upload: { /* Add configuration here */ }, }, };每次 Lighthouse CI 執行時，都會啟動伺服器來提供網站。即使沒有其他伺服器在執行，Lighthouse 也能透過這個伺服器載入網站。Lighthouse CI 執行完畢後，會自動關閉伺服器。為確保放送功能正常運作，請務必設定
staticDistDir或startServerCommand屬性。如果網站是靜態網站，請將
staticDistDir屬性新增至ci.collect物件，指出靜態檔案的位置。Lighthouse CI 會在測試網站時，使用自己的伺服器提供這些檔案。如果網站不是靜態，請在ci.collect物件中加入startServerCommand屬性，指出啟動伺服器的指令。Lighthouse CI 會在測試期間啟動新的伺服器程序，並在測試結束後關閉。// Static site example collect: { staticDistDir: './public', }// Dynamic site example collect: { startServerCommand: 'npm run start', }將
url屬性新增至ci.collect物件，指出 Lighthouse CI 應對哪些網址執行 Lighthouse。url屬性的值應以網址陣列的形式提供；這個陣列可以包含一或多個網址。根據預設，Lighthouse CI 會針對每個網址執行 Lighthouse 三次。collect: { // ... url: ['http://localhost:8080'] }將
target屬性新增至ci.upload物件，並將值設為'temporary-public-storage'。Lighthouse CI 收集的 Lighthouse 報表會上傳至暫時公開儲存空間。報告會保留七天，之後就會自動刪除。本設定指南使用「暫時公開儲存空間」上傳選項，因為設定速度很快。如要瞭解其他儲存 Lighthouse 報表的方式，請參閱說明文件。upload: { target: 'temporary-public-storage', }報表的儲存位置大致如下：
https://storage.googleapis.com/lighthouse-infrastructure.appspot.com/reports/1580152437799-46441.report.html(報表已刪除，因此這個網址無法運作)。
使用
autorun指令，從終端機執行 Lighthouse CI CLI。這會執行 Lighthouse 三次，並上傳中位數 Lighthouse 報表。lhci autorun如果 Lighthouse CI 設定正確，執行這個指令後，應該會產生類似以下的輸出內容：
✅ .lighthouseci/ directory writable ✅ Configuration file found ✅ Chrome installation found ⚠️ GitHub token not set Healthcheck passed! Started a web server on port 65324... Running Lighthouse 3 time(s) on http://localhost:65324/index.html Run #1...done. Run #2...done. Run #3...done. Done running Lighthouse! Uploading median LHR of http://localhost:65324/index.html...success! Open the report at https://storage.googleapis.com/lighthouse-infrastructure.appspot.com/reports/1591720514021-82403.report.html No GitHub token set, skipping GitHub status check. Done running autorun.您可以忽略控制台輸出內容中的
GitHub token not set訊息。只有在您想搭配 GitHub Action 使用 Lighthouse CI 時，才需要 GitHub 權杖。本文稍後會說明如何設定 GitHub 動作。點選輸出內容中開頭為
https://storage.googleapis.com...的連結，即可前往對應中位數 Lighthouse 執行的 Lighthouse 報表。您可以透過指令列或
lighthouserc.js覆寫autorun使用的預設值。舉例來說，下方的lighthouserc.js設定表示每次執行autorun時，都應收集五次 Lighthouse 執行作業。更新
lighthouserc.js以使用numberOfRuns屬性：module.exports = { // ... collect: { numberOfRuns: 5 }, // ... }, };重新執行
autorun指令：lhci autorun終端機輸出內容應顯示 Lighthouse 已執行五次，而非預設的三次：
✅ .lighthouseci/ directory writable ✅ Configuration file found ✅ Chrome installation found ⚠️ GitHub token not set Healthcheck passed! Automatically determined ./dist as `staticDistDir`. Set it explicitly in lighthouserc.json if incorrect. Started a web server on port 64444... Running Lighthouse 5 time(s) on http://localhost:64444/index.html Run #1...done. Run #2...done. Run #3...done. Run #4...done. Run #5...done. Done running Lighthouse! Uploading median LHR of http://localhost:64444/index.html...success! Open the report at https://storage.googleapis.com/lighthouse-infrastructure.appspot.com/reports/1591716944028-6048.report.html No GitHub token set, skipping GitHub status check. Done running autorun.如要瞭解其他設定選項，請參閱 Lighthouse CI 設定說明文件。
設定 CI 程序，以便執行 Lighthouse CI
Lighthouse CI 可與您偏好的 CI 工具搭配使用。Lighthouse CI 說明文件的「設定 CI 供應商」一節提供程式碼範例，說明如何將 Lighthouse CI 納入常見 CI 工具的設定檔。具體來說，這些程式碼範例說明如何執行 Lighthouse CI，在 CI 程序中收集效能評估資料。
使用 Lighthouse CI 收集效能評估資料，是開始監控效能的好方法。不過，進階使用者可能想更進一步，使用 Lighthouse CI，在建構作業不符合預先定義的條件 (例如通過特定 Lighthouse 稽核或符合所有效能預算) 時，將建構作業標示為失敗。這項行為是透過 lighthouserc.js 檔案的 assert 屬性設定。
Lighthouse CI 支援三個層級的斷言：
off：忽略斷言warn：將失敗訊息輸出至 stderrerror：將失敗記錄輸出至 stderr，並以非零的結束代碼結束 Lighthouse CI
以下是包含斷言的 lighthouserc.js 設定範例。它會為 Lighthouse 的效能和無障礙功能類別分數設定斷言。如要試用這項功能，請將下方所示的斷言新增至 lighthouserc.js 檔案，然後重新執行 Lighthouse CI。
module.exports = {
ci: {
collect: {
// ...
},
assert: {
assertions: {
'categories:performance': ['warn', {minScore: 1}],
'categories:accessibility': ['error', {minScore: 1}]
}
},
upload: {
// ...
},
},
};
產生的控制台輸出內容如下所示：
如要進一步瞭解 Lighthouse CI 斷言，請參閱說明文件。
設定 GitHub Action 來執行 Lighthouse CI
您可以使用 GitHub Action 執行 Lighthouse CI。每當程式碼變更推送至 GitHub 存放區的任何分支版本時，系統就會產生新的 Lighthouse 報表。請搭配狀態檢查使用，在每個提取要求中顯示這些結果。
在存放區的根目錄中，建立名為
.github/workflows的目錄。專案的工作流程會進入這個目錄。工作流程是在預定時間 (例如推送程式碼時) 執行的程序，由一或多個動作組成。mkdir .github mkdir .github/workflows在
.github/workflows中建立名為lighthouse-ci.yaml的檔案。這個檔案會保留新工作流程的設定。touch lighthouse-ci.yaml在
lighthouse-ci.yaml中新增下列文字。name: Build project and run Lighthouse CI on: [push] jobs: lhci: name: Lighthouse CI runs-on: ubuntu-latest steps: - uses: actions/checkout@v1 - name: Use Node.js 10.x uses: actions/setup-node@v1 with: node-version: 10.x - name: npm install run: | npm install - name: run Lighthouse CI run: | npm install -g @lhci/cli@0.3.x lhci autorun --upload.target=temporary-public-storage || echo "LHCI failed!"這項設定會建立由單一工作組成的工作流程，每當有新程式碼推送至存放區時，該工作就會執行。這項工作有四個步驟：
- 查看要執行 Lighthouse CI 的存放區
- 安裝及設定 Node
- 安裝必要的 npm 套件
- 執行 Lighthouse CI，並將結果上傳至暫時公開儲存空間。
修訂這些變更並推送至 GitHub。如果您已正確執行上述步驟，將程式碼推送至 GitHub 時，就會觸發您剛才新增的工作流程。
如要確認 Lighthouse CI 已觸發，並查看產生的報表，請前往專案的「Actions」(動作) 分頁。您應該會在最近的修訂版本下方，看到「Build project and Run Lighthouse CI」工作流程。
您可以從「Actions」分頁前往特定修訂版本對應的 Lighthouse 報表。按一下修訂版本，然後按一下「Lighthouse CI」工作流程步驟，接著展開「執行 Lighthouse CI」步驟的結果。
您已設定 GitHub Action 來執行 Lighthouse CI。與 GitHub 狀態檢查搭配使用時，這項功能最實用。
設定 GitHub 狀態檢查
如果設定了狀態檢查，每項 PR 都會顯示一則訊息，通常包含測試結果或建構成功等資訊。
下列步驟說明如何設定 Lighthouse CI 的狀態檢查。
前往 Lighthouse CI GitHub 應用程式頁面，然後按一下「Configure」(設定)。
(選用) 如果您在 GitHub 上隸屬於多個組織，請選擇要使用 Lighthouse CI 的存放區所屬組織。
如要在所有存放區中啟用 Lighthouse CI，請選取「All repositories」；如果只想在特定存放區中使用，請選取「Only select repositories」，然後選取存放區。然後點按「Install & Authorize」。
複製顯示的權杖。您會在下一個步驟中使用。
如要新增權杖，請前往 GitHub 存放區的「Settings」(設定) 頁面，依序點選「Secrets」(密鑰) 和「Add a new secret」(新增密鑰)。
將「Name」(名稱) 欄位設為
LHCI_GITHUB_APP_TOKEN，並將「Value」(值) 欄位設為您在上一個步驟中複製的權杖，然後按一下「Add secret」(新增密鑰) 按鈕。前往
lighthouse-ci.yaml檔案，並將新的環境密鑰新增至「run Lighthouse CI」指令。
- name: run Lighthouse CI
run: |
npm install -g @lhci/cli@0.3.x
lhci autorun --upload.target=temporary-public-storage || echo "LHCI failed!"
+ env:
+ LHCI_GITHUB_APP_TOKEN: $
- 狀態檢查已可使用。如要測試，請建立新的提取要求，或將修訂版本推送至現有的提取要求。
設定 Lighthouse CI 伺服器
Lighthouse CI 伺服器提供資訊主頁，可用於探索歷來 Lighthouse 報表。也可以做為 Lighthouse 報表的私人長期資料儲存庫。
- 選擇要比較的修訂版本。
- 兩次修訂版本之間的 Lighthouse 分數變化量。
- 這個部分只會顯示兩次修訂版本之間有變化的指標。
- 迴歸則會以粉紅色醒目顯示。
- 改善項目會以藍色醒目顯示。
Lighthouse CI 伺服器最適合能自行部署及管理基礎架構的使用者。
如要瞭解如何設定 Lighthouse CI 伺服器，包括使用 Heroku 和 Docker 部署的方案，請參閱這些操作說明。