如何将 Lighthouse 添加到持续集成系统(例如 GitHub Actions)。
Lighthouse CI 是一套用于在持续集成期间使用 Lighthouse 的工具。Lighthouse CI 可以通过许多不同的方式合并到开发者工作流中。本指南涵盖以下主题:
- 使用 Lighthouse CI CLI。
- 配置 CI 提供方以运行 Lighthouse CI。
- 为 Lighthouse CI 设置 GitHub 操作和状态检查。这将在 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 的替代方案包括第三方性能监控服务,或编写自己的脚本以在 CI 过程中收集性能数据。如果您希望让他人处理您的性能监控服务器和测试设备的管理,或者您希望使用通知功能(例如电子邮件或 Slack 集成),而不必自行构建这些功能,您应该考虑使用第三方服务。
在本地使用 Lighthouse CI
本部分介绍如何在本地运行和安装 Lighthouse CI CLI,以及如何配置 lighthouserc.js
。在本地运行 Lighthouse CI CLI 是确保正确配置 lighthouserc.js
的最简单方法。
安装 Lighthouse CI CLI。
npm install -g @lhci/cli
通过在项目代码库的根目录中放置
lighthouserc.js
文件来配置 Lighthouse CI。此文件是强制性的,将包含 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 报告。autorun
使用的默认值可通过命令行或lighthouserc.js
替换。例如,下面的lighthouserc.js
配置表示应在每次执行autorun
时收集 5 次 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 审核或满足所有性能预算),他们可能希望更进一步,使用 Lighthouse CI 使构建失败。此行为通过 lighthouserc.js
文件的 assert
属性进行配置。
Lighthouse CI 支持三个级别的断言:
off
:忽略断言warn
:向 stderr 输出失败error
:向 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 的代码库
- 安装和配置 Node
- 安装所需的 npm 软件包
- 运行 Lighthouse CI 并将结果上传到临时公共存储空间。
提交这些更改并将其推送到 GitHub。如果您正确执行了上述步骤,将代码推送到 GitHub 会触发运行您刚刚添加的工作流。
如需确认 Lighthouse CI 是否已触发并查看它生成的报告,请转到项目的操作标签页。您应该会在最近的提交下看到构建项目和运行 Lighthouse CI 工作流。
您可以从操作标签页导航到与特定提交相对应的 Lighthouse 报告。依次点击提交和 Lighthouse CI 工作流步骤,然后展开运行 Lighthouse CI 步骤的结果。
您刚刚设置了一个 GitHub 操作来运行 Lighthouse CI。在与 GitHub 状态检查结合使用时,这种方法最为有用。
设置 GitHub 状态检查
状态检查(如果已配置)是显示在每个 PR 上的消息,通常包含测试结果或构建成功等信息。
以下步骤说明了如何为 Lighthouse CI 设置状态检查。
前往 Lighthouse CI GitHub 应用页面,然后点击配置。
(可选)如果您是 GitHub 上多个组织的成员,请选择想要为其使用 Lighthouse CI 的代码库的组织。
如果要在所有代码库中启用 Lighthouse CI,请选择所有代码库;如果您只想在特定代码库中使用 Lighthouse CI,请选择仅选择代码库,然后选择这些代码库。然后点击 Install & Authorize(安装并授权)。
复制显示的令牌。您将在下一步中用到它。
如需添加令牌,请转到 GitHub 代码库的设置页面,点击 Secret,然后点击 Add a new secret。
将 Name 字段设置为
LHCI_GITHUB_APP_TOKEN
,并将 Value 字段设置为您在上一步中复制的令牌,然后点击添加密钥按钮。转到
lighthouse-ci.yaml
文件,然后将新的环境密钥添加到“运行 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。