如何將 Lighthouse 新增至持續整合系統，例如 GitHub Actions。
Lighthouse CI 是一套工具，可在持續整合期間使用。Lighthouse CI 能以各種不同的方式納入開發人員工作流程中。本指南涵蓋下列主題：
- 使用 Lighthouse CI CLI。
- 設定您的持續整合供應商以執行 Lighthouse CI。
- 設定 GitHub 動作並檢查 Lighthouse CI 的狀態檢查。這會在 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 動作，針對每個提取要求執行並加註
- 透過 Lighthouse 伺服器提供的資訊主頁追蹤長期效能。
上述所有方法都是以 Lighthouse CI CLI 為基礎建構而成。
Lighthouse CI 的替代方案包括第三方效能監控服務，或是自行編寫指令碼，以在持續整合程序期間收集效能資料。如果您想讓他人處理效能監控伺服器和測試裝置的管理工作，或者希望在不自行建構這些功能的情況下，使用第三方服務 (例如電子郵件或 Slack 整合)，就應該考慮使用第三方服務。
在本機使用 Lighthouse CI
本節說明如何在本機執行及安裝 Lighthouse CI CLI，以及如何設定 lighthouserc.js。在本機執行 Lighthouse CI CLI，是確保 lighthouserc.js 設定正確最輕鬆的方法。
安裝 Lighthouse CI CLI。
npm install -g @lhci/cliLighthouse 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 會在測試您的網站時，使用自己的伺服器提供這些檔案。如果不是靜態網站，請將startServerCommand屬性新增至ci.collect物件，指出啟動伺服器的指令。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 報表會上傳到臨時公開儲存空間。報表會保留 7 天，之後會自動刪除。本設定指南採用「暫時性公開儲存空間」上傳選項，因為設定方式非常快速。如要進一步瞭解儲存 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訊息。只有在您要將 Lighthouse CI 與 GitHub 動作搭配使用時，才需要使用 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 設定說明文件。
設定持續整合程序以執行 Lighthouse CI
Lighthouse CI 可與你最愛的持續整合工具搭配使用。Lighthouse CI 說明文件的「Configure Your CI Provider」(設定持續整合供應商) 部分，提供了程式碼範例，示範如何將 Lighthouse CI 整合到常用持續整合工具的設定檔中。具體來說，這些程式碼範例說明如何執行 Lighthouse 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 動作以執行 Lighthouse CI
GitHub 動作可用來執行 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 的存放區
- 安裝及設定節點
- 安裝必要的 npm 套件
- 執行 Lighthouse CI，並將結果上傳至臨時公開儲存空間。
修訂這些變更並推送至 GitHub。如果您已正確執行上述步驟，將程式碼推送至 GitHub 會觸發執行您剛新增的工作流程。
如要確認 Lighthouse CI 已觸發，並查看其產生的報表，請前往專案的「Actions」分頁。您應該會在最近的修訂版本下方看到「Build project and Run Lighthouse CI」工作流程。
您可以從「Actions」分頁前往與特定修訂版本相對應的 Lighthouse 報表。按一下修訂版本，然後按一下「Lighthouse CI」工作流程步驟，然後展開 run Lighthouse CI 步驟的結果。
您剛剛設定了用於執行 Lighthouse CI 的 GitHub 動作。這對與 GitHub 狀態檢查搭配使用時最有幫助。
設定 GitHub 狀態檢查
狀態檢查 (如有設定) 是每個 PR 上顯示的訊息，通常包含測試結果或建構成功等資訊。
下列步驟說明如何設定 Lighthouse CI 狀態檢查。
前往 Lighthouse CI GitHub App 頁面，然後按一下「Configure」。
(選用) 如果您隸屬於 GitHub 上的多個機構，請選擇擁有要使用 Lighthouse 持續整合存放區的機構。
如要在所有存放區中啟用 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 Server 最適合能夠妥善部署及管理基礎架構的使用者。
如要瞭解如何設定 Lighthouse CI 伺服器，包括使用 Heroku 和 Docker 部署的食譜，請參閱這些instructions。