Lighthouse 规模化运行指南：PSI API、云端 CLI 与自建采集的三种实战路径-平芜编程栈

Lighthouse 规模化运行指南：PSI API、云端 CLI 与自建采集的三种实战路径

【免费下载链接】lighthouseAutomated auditing, performance metrics, and best practices for the web.项目地址: https://gitcode.com/GitHub_Trending/lig/lighthouse

Lighthouse 的很多用户希望每天为成百上千个 URL 采集性能数据。本文基于 Lighthouse 官方文档 docs/running-at-scale.md，系统梳理规模化采集的三种主流方案（PageSpeed Insights API、云端硬件上的 Lighthouse CLI、集成 Lighthouse 的第三方服务），并深入源码印证 CLI 的端口复用、Chrome 实例管理等底层机制，同时给出可落地的中位数（median）汇总方法与硬件选型建议，帮助你构建一套结果可复现、数据可信赖的批量采集体系。

在动手规模化采集之前，请务必先理解一个前提：性能测量天然存在波动。即使代码没有任何变更，Lighthouse 的性能得分也会因为网络、硬件、浏览器执行的不确定性而发生变化。官方文档 docs/variability.md 详细分析了这一现象，并建议在得出结论前多次运行 Lighthouse。规模化采集意味着你会在同一条流水线上运行大量测试，如果忽略波动性，很容易把噪声当成真实回归。

规模化采集的三种方案概览

围绕"如何为大量 URL 持续获取 Lighthouse 结果"，官方文档给出了三条路径，它们在对环境维护、可配置性和开发成本上的取舍截然不同：

方案	是否自建环境	配置灵活度	首个结果的工程量	完整落地的工程量
Option 1：PageSpeed Insights（PSI）API	不需要	低	约 5 分钟	约 30 分钟（编写批量评估脚本）
Option 2：云端硬件上的 Lighthouse CLI	需要	极高	约 1 天（含环境准备）	额外 2～5 天（校准、排障、处理云主机交互）
Option 3：集成 Lighthouse 的服务	不需要	由服务商决定	取决于服务本身	取决于服务本身

以下逐条展开。

Option 1：使用 PageSpeed Insights API —— 零运维的快速接入

PSI API 的默认配额是每天 25,000 次请求。对于绝大多数团队的量级，这个配额相当充裕。其核心价值在于：你完全不需要创建和维护一套稳定的测试环境——Lighthouse 运行在 Google 的基础设施上，环境一致性较好，可复现性高。

优缺点与适用边界

优点（PRO）：无需维护测试硬件。
优点（PRO）：一次简单的网络请求即可返回完整的 Lighthouse 结果。
缺点（CON）：URL 必须是公网可访问的，无法测试 localhost 或被防火墙隔离的 URL。文档明确提到，除非使用像 ngrok 这类（存在安全隐患的）方案把内网地址暴露到公网，否则无法通过 PSI API 测试内网页面。

工程量评估

首个结果：约 5 分钟。
写一个批量脚本评估并保存数百个 URL 的结果：约 30 分钟。

关键限制：内网与鉴权页面

如果你的被测站点需要登录、位于内网或需要携带自定义请求头，PSI API 就无法覆盖这些场景。这类需求应当转向 Option 2 的自建 CLI 方案，或参考仓库中的 docs/authenticated-pages.md 了解如何在自建环境中处理鉴权页面。

Option 2：在云端硬件上使用 Lighthouse CLI —— 完全可配置的自建方案

Lighthouse CLI 是绝大多数高级用法的基石，提供了非常丰富的配置能力。仓库根目录的 readme.md 给出了安装与基本用法：

npm install -g lighthouse # 或 # yarn global add lighthouse # 基本运行 lighthouse https://example.com/

注意：当前仓库要求 Node 22（LTS）或更高版本（见 readme.md）。

复用同一 Chrome 实例：`--port`的妙用

CLI 最常用的进阶技巧之一是启动一个处于可调试状态的全新 Chrome，然后让 Lighthouse 反复复用同一个 Chrome：

# 1. 先以远程调试端口 9222 启动一个 Chrome 实例 chrome-debug --port=9222 # 2. 让 Lighthouse 连接到这个已有的 Chrome 上运行，而不是每次自启一个新实例 lighthouse <url> --port=9222

从源码看，这一行为的实现位于 cli/run.js 的getDebuggableChrome函数：它首先尝试连接一个已打开远程调试端口的 Chrome（端口由--port指定），如果连接不到，才会通过chrome-launcher启动一个新的可调试实例，并把实际使用的端口回写进 flags：

// cli/run.js（节选） return ChromeLauncher.launch({ port: flags.port, ignoreDefaultFlags: flags.chromeIgnoreDefaultFlags, chromeFlags: parseChromeFlags(flags.chromeFlags), logLevel: flags.logLevel, });

--port选项在 cli/cli-flags.js 中的定义为："The port to use for the debugging protocol. Use 0 for a random port"（默认值为 0，即随机端口）。

官方对复用 Chrome 的明确告诫

文档强调：不推荐用同一个 Chrome 实例跑超过一百次加载，因为 Chrome profile 中会逐渐累积状态（缓存、Service Worker、LocalStorage 等），导致结果漂移。每次 Lighthouse 运行都使用全新 profile 是获得可复现结果的最佳做法。

这一告诫在源码层面同样有印证：cli/run.js 在单次运行结束后会调用launchedChrome?.kill()关闭由它启动的 Chrome，避免跨运行的状态残留；而--disable-storage-reset这个 CLI flag（见 cli/cli-flags.js）默认会清除浏览器缓存与存储 API，也正是为了控制状态对结果的影响。

使用配置文件固化规模化参数

规模化的关键是参数可重复。CLI 提供了--cli-flags-path，可以把一组 CLI 参数写入 JSON 文件统一管理（命令行中显式指定的参数会覆盖文件中的值），非常适合在 CI 或批量脚本中复用同一套采集配置。完整的参数清单见 readme.md 的lighthouse --help输出，规模化场景下常用的有：

--output=json：输出 JSON 结果（默认输出 HTML 报告）。
--output-path：指定输出路径，多个输出格式时会自动追加扩展名（如my-run.report.json）。
--chrome-flags="--headless"：使用无头 Chrome 运行，适合服务器环境。
--throttling.cpuSlowdownMultiplier/--throttling.rttMs等：控制节流参数（详见 docs/throttling.md）。
--only-categories=performance：只运行指定类别，缩短单次运行时间。

社区封装的批量模式

许多团队已经围绕 CLI 用 bash、Python 或 Node 脚本做了封装。文档特别提到了两个 npm 模块：

multihouse：基于 CLI 的批量封装模式。
lighthouse-batch：对一组站点批量运行 Lighthouse 并汇总分数与指标。

这类工具的核心思路与仓库中-G/-A生命周期拆分是一致的：--gather-mode（-G）只采集 artifacts 并落盘，--audit-mode（-A）只基于磁盘上的 artifacts 运行审计（见 readme.md 的 Lifecycle Examples）。在批量场景下，可以先在分布式机器上并行采集 artifacts，再集中进行审计计算，降低资源争用。

运行环境的要求

由于是在你自己的机器上运行 CLI，必须关注机器规格。文档明确要求（详见 docs/variability.md 的 "Run on Adequate Hardware"）：

至少 2 个专用核心（推荐 4 核）。
至少 2GB 内存（推荐 4～8GB）。
避免非标准 Chromium flag（--single-process不受支持；--no-sandbox和--headless一般可用，但需了解 sandbox 的取舍）。
避免使用函数即服务（FaaS）基础设施（如 AWS Lambda、GCF 等）。
避免"可突发"（burstable）或"共享核心"实例类型（如 AWSt系列、GCP 共享核心的 N1/E2 系列）。

环境还必须能够运行 headful Chrome 或 headless Chrome。

文档给出了一个具体的参照系：AWSm5.large、GCPn2-standard-2、AzureD2足以在单个实例上运行单次 Lighthouse（这些实例类型大约 0.10 美元/小时，约 30 秒/次测试，约 0.0008 美元/份 Lighthouse 报告）。值得注意的是：不满足上述要求的环境虽然也能跑出非性能类结果，但官方不建议也不支持在问题出现时对这类环境提供支持——"在不稳定的硬件上运行，得到的就是不稳定的结果"。

严禁同机并发：横向扩展优于纵向扩展

文档给出了一个强约束：绝对不要在同一台机器上同时收集多份 Lighthouse 报告。并发运行会因资源争用而扭曲性能结果（这一点在 docs/variability.md 的 "Client Resource Contention" 一节也有分析）。因此规模化时应横向扩展而非纵向扩展：用 4 台n2-standard-2并行，而不是 1 台n2-standard-8。

优缺点与工程量评估

优点（PRO）：终极的可配置性（Ultimate configurability）。
缺点（CON）：必须自建并维护测试环境。
首个结果工程量：约 1 天（含环境开通与准备）。
完整落地工程量：额外 2～5 天（校准、排障、处理与云主机的交互）。

Option 3：通过集成 Lighthouse 的服务采集数据

第三条路径最省心：直接使用已经集成 Lighthouse 的第三方 Web 性能服务。仓库根目录 readme.md 的 "Lighthouse Integrations in Web Perf services" 一节维护了一份长期更新的集成清单，涵盖 WebPageTest、HTTPArchive、Calibre、DebugBear、SpeedCurve 等众多服务，它们大多以"Lighthouse as a Service"的形式提供批量测试、历史监控、回归告警与 PR 评论等能力，适合不希望自建任何环境的团队。

选择此方案时，建议关注服务是否满足你的核心诉求：是否需要测试内网/鉴权页面、是否需要自定义网络与设备模拟、数据是否可导出并与你的监控体系打通。

必修课：正确处理结果的波动性 —— 多次运行与中位数汇总

无论选择哪条路径，都不要基于单次运行的结果做判断。官方在 docs/variability.md 中给出的核心建议是：

在制定阈值（无论是人为的还是程序化的）时，使用中位数、90 分位、甚至 min/max 等聚合值，而不是单次测试结果。

文档还给出了一个经验数据：5 次运行的中位数 Lighthouse 得分，稳定性是单次运行的 2 倍。

方法一：使用 Lighthouse CI（lhci）批量采集并落盘

最简单的多次运行 + 中位数方案是使用 lighthouse-ci：

# 对同一 URL 连续运行 5 次 npx -p @lhci/cli lhci collect --url https://example.com -n 5 # 把结果写入文件系统 npx -p @lhci/cli lhci upload --target filesystem --outputDir ./path/to/dump/reports

注意：使用npx需要先安装 Node。

之后可以读取落盘结果并从中位数报告中提取性能得分：

const fs = require('fs'); const lhciManifest = require('./path/to/dump/reports/manifest.json'); const medianEntry = lhciManifest.find(entry => entry.isRepresentativeRun) const medianResult = JSON.parse(fs.readFileSync(medianEntry.jsonPath, 'utf-8')); console.log('Median performance score was', medianResult.categories.performance.score * 100);

lhci 也支持通过 PSI 模式采集：

npx -p @lhci/cli lhci collect --url https://example.com -n 5 --mode psi --psiApiKey xXxXxXx npx -p @lhci/cli lhci upload --target filesystem --outputDir ./path/to/dump/reports

方法二：通过 Node 直连 CLI 并使用`computeMedianRun`

如果你直接通过 Node 运行 Lighthouse，官方文档推荐使用computeMedianRun函数——它并非简单地取性能得分的中位数，而是基于多个性能指标做"混合中位数"计算。

const spawnSync = require('child_process').spawnSync; const lighthouseCli = require.resolve('lighthouse/cli'); const {computeMedianRun} = require('lighthouse/core/lib/median-run.js'); const results = []; for (let i = 0; i < 5; i++) { console.log(`Running Lighthouse attempt #${i + 1}...`); const {status = -1, stdout} = spawnSync('node', [ lighthouseCli, 'https://example.com', '--output=json' ]); if (status !== 0) { console.log('Lighthouse failed, skipping run...'); continue; } results.push(JSON.parse(stdout)); } const median = computeMedianRun(results); console.log('Median performance score was', median.categories.performance.score * 100);

上述脚本中的spawnSync每次启动一个全新的 Node 进程调用 CLI 并指定--output=json（结合 cli/bin.js 的逻辑可知，单 JSON 输出且未指定--output-path时会默认写往 stdout），失败时跳过该次运行，最后用computeMedianRun计算中位数——这正是规模化流水线里"采集多份 → 聚合出一份代表性结果"的典型范式。

`computeMedianRun`的底层原理

该函数的实现在 core/lib/median-run.js。它的做法与直觉相反：不直接取性能得分的中位数，而是：

先计算所有运行中FCP（first-contentful-paint）的中位数与TTI（interactive）的中位数；
再对每次运行计算其 FCP、TTI 与对应中位数的欧几里得距离（distanceFcp² + distanceInteractive²）；
选取距离最近的那次运行作为"中位数代表运行"（距离相同时以更小的 TTI 打破平局）。

源码注释说明了这样设计的理由："我们避免使用性能得分等单一指标的中位数，因为它们在加载的早期或晚期仍可能出现离群行为；而 FCP 与 TTI 分别代表页面生命周期中最早和最晚的时刻。"同时，computeMedianRun会在缺少 FCP 或 TTI 值、或传入空数组时直接抛错（Some runs were missing an FCP value等），同文件导出的filterToValidRuns可以先行过滤掉 FCP/TTI 非有限的无效运行——在批量流水线中建议先用它做数据清洗。

控制可变性源：测试环境的四大隔离原则

结合 docs/variability.md，规模化采集还应尽可能隔离外部因素：

隔离页面的第三方影响：尽可能让被测页面不受第三方脚本/广告干扰，避免为别人的波动背锅。
隔离自身代码的非确定性：如果页面有随机出现的动画或 A/B 实验，性能数字也会"随机"。
隔离测试服务器的网络波动：稳定性优先时，用 localhost 或与测试机同一网络的机器。
隔离客户端环境：远离杀毒软件、浏览器扩展等外部影响，条件允许时使用专用测试设备。

如果机器资源实在有限、难以创建干净环境，文档建议改用托管实验室环境（如 PageSpeed Insights、WebPageTest）代为运行；在持续集成场景中尽量使用专用服务器——免费的 CI 环境和"可突发"实例通常波动很大。

三种方案的选型建议

你的诉求	推荐方案
快速验证公网页面的批量性能，不想维护任何环境	Option 1：PSI API（注意 25,000 次/天配额与公网可访问限制）
需要测试内网/鉴权页面，或需要深度定制运行参数与节流	Option 2：云端硬件 + Lighthouse CLI（注意硬件规格与"禁止同机并发"约束）
需要开箱即用的监控、告警、历史回溯与团队协作	Option 3：集成 Lighthouse 的第三方服务（清单见 readme.md）

无论选择哪条路径，请牢记两条贯穿始终的原则：结果必须来自多次运行的中位数等聚合值（用 core/lib/median-run.js 的computeMedianRun或 lhci 的isRepresentativeRun实现），环境必须稳定且可复现（参照 docs/variability.md 的硬件与隔离建议）。只有这样，每天数百上千个 URL 的采集数据才有对比与回归判断的价值。

Lighthouse 规模化运行指南：PSI API、云端 CLI 与自建采集的三种实战路径