sitespeed.io Coach 指南：用真实浏览器规则库诊断页面性能、隐私与最佳实践问题

• 测试
• 性能剖析
• 指标监控

The Coach 是内置在 sitespeed.io 中的一套开源规则引擎：它让真实浏览器在运行测试时检查活页面（DOM），再结合同一次运行的 HAR 网络日志（Har 文件）给出可执行的修复建议，覆盖 Core Web Vitals、现代图片实践、隐私与安全响应头、第三方脚本开销等主题。读完本文，你将掌握 Coach 的检查范围与评分模型、如何通过 sitespeed.io 命令行获得诊断结果、如何把coach-core分析库接入自己的浏览器流水线，以及如何在coach-core仓库中编写或改进一条 Coach 规则。

Coach 是什么：两条数据源合二为一

Coach 是一组针对"真实页面"运行的规则集，其分析逻辑位于开源的coach-core库中（当前仓库package.json中声明的版本为9.2.1）。在 sitespeed.io 中，Coach 默认开启：当你正常运行 sitespeed.io 时，Coach 会随同运行并输出诊断结果。

每条 Coach 规则都合并了两种事实来源：

• DOM advice——以 JavaScript 形式注入浏览器内部执行，检查活页面的实时状态。例如：哪些脚本阻塞了渲染、<img>是否在 HTML 中被缩放、是否设置了decoding="async"、LCP 元素是否带有fetchpriority。
• HAR advice——分析同一次运行生成的 HAR 文件。例如：各内容类型的请求数量、缓存头、重定向、渲染阻塞时序、第三方脚本的使用情况。

两类结果最终被合并为一个输出，因此每条规则都能同时利用来自 DOM 与 HAR 两侧的信息。

Coach 检查什么

Coach 的检查范围在 introduction 文档 中被完整列出：

• Core Web Vitals——LCP、CLS、INP、FCP，每个指标都有对应的规则级建议；
• 现代图片实践——decoding="async"、原生懒加载、AVIF/WebP 使用情况、LCP 图片的fetchpriority；
• 关键渲染路径——阻塞渲染的 JavaScript 与 CSS、内联 CSS、head 内容；
• HTTP 与缓存——缓存头、重定向、压缩、HTTP/2 与 HTTP/3 的使用情况；
• 隐私与安全响应头——CSP、COOP/COEP/CORP、Permissions-Policy、X-Content-Type-Options、NEL、Reporting-Endpoints、Referrer-Policy；
• 第三方脚本——页面引入了哪些第三方脚本，以及它们带来的成本；
• 可访问性与最佳实践——无需额外工具即可执行的基础检查；
• Info——页面事实类信息（DOM 大小、DOM 深度、iframe 数量、localStorage 大小），不含主观判断，供你自行得出结论。

在 Coach 的测试 fixture coach.run-0.json 中可以看到这些类别的真实落地形态：accessibility类别包含altImages（缺失 alt 属性的图片）、headings（标题结构）、labelOnInput（表单标签）、landmarks、neverSuppressZoom（禁止抑制捏合缩放）、sections、table等规则；bestpractice类别包含charset、doctype等规则；每条规则都带有score、weight、offending（违规资源 URL 列表）和tags。

评分模型：score、weight 与 severity

在 introduction 文档 中，每条规则产出一个包含三个数字的结果：

所有分数会被聚合成类别分数（performance、privacy、best practice、accessibility）以及一个总体页面分数，量纲都是 0–100。

聚合逻辑在仓库中的 coach 插件聚合器 有具体实现：addToAggregate把每次运行的总体score以及每个类别、每条规则（adviceList）的score推进分组统计，summarize()再按组生成包含最小值、最大值等统计量的汇总对象。对应的单元测试见 coachTests.js，它读取 fixture 数据后验证"汇总不返回 undefined"。

在 sitespeed.io 中使用 Coach

默认开启，无需额外参数

Coach 在 sitespeed.io 中默认启用。正常启动测试即可，HTML 结果页会展示 Coach 分数与逐规则建议：

sitespeed.io https://www.sitespeed.io/

HTML 报告负责渲染 Coach 输出（相关模板见 index.pug 与 detailed.pug，其中coach以"0–100，越高越好"的分数组形式展示，并带有 good（≥90）/ poor（≤70）的分级阈值）。同一份数据还会以coach.json形式写入结果目录；如果你把指标发送到 InfluxDB、Graphite 或 Prometheus，Coach 分数也会随之一起上报。

Coach 在源码中如何被调用

在 sitespeed.io 内部，Coach 的调用链清晰地贯穿两条路径：

• 注入 DOM 脚本：browsertime 分析器 中的addCoachScripts()调用getDomAdvice()获取 DOM 检查脚本，并挂到scripts.coach.coachAdvice上，随浏览器脚本一起注入页面；
• 合并 HAR 结果：browsertime 插件 在处理每次运行时，若options.coach为真，会读取coachAdvice，用pickAPage(result.har, harIndex)选中 HAR 中对应的一次页面加载，调用analyseHar(myHar, undefined, coachAdvice, options)运行 HAR 规则，再用merge(coachAdvice, harResult)合并两侧结果，最后把 third-party-web、wappalyzer 与 webappanalyzer 的数据版本写入 advice，并通过coach.run消息发回插件系统；
• 汇总与上报：coach 插件 监听coach.run消息，将第一次迭代的结果转成coach.pageSummary，并在sitespeedio.summarize阶段生成coach.summary汇总消息；其默认指标筛选（DEFAULT_METRICS_SUMMARY）覆盖score.*、performance.score.*、privacy.score.*、bestpractice.score.*、accessibility.score.*，DEFAULT_METRICS_PAGESUMMARY则额外包含advice.info.domElements、advice.info.domDepth、advice.info.iframes、advice.info.localStorageSize等页面事实指标。

作为库使用：coach-core

如果你有自己的浏览器流水线（自定义 WebDriver runner、headless 服务、内部工具），可以安装coach-core并直接调用它。coach-core是纯 ESM 包，需要 Node.js 20 或更高版本：

npm install coach-core

库要求你自己准备两个输入：

1. 在浏览器中运行 Coach 的 DOM 脚本后得到的结果；
2. 同一次页面加载产生的 HAR 文件。

完整调用流程如下（摘自 how-to 文档）：

import { getDomAdvice, getHarAdvice, analyseHar, merge, pickAPage } from 'coach-core'; // 1. 获取检查页面的 JavaScript，并在你自己的浏览器中运行它。 const domScript = await getDomAdvice(); const domResult = await yourBrowser.evaluate(domScript); // 2. 取出同一次运行的 HAR。如果 HAR 包含多个页面，选择要分析的那一页。 const har = await yourBrowser.getHar(); const page = pickAPage(har, 0); // 3. 运行 HAR 规则。把 DOM 结果传进去，HAR 规则才能使用它。 const harAdvice = await getHarAdvice(); const harResult = await analyseHar(page, harAdvice, domResult, { // 任何你想转发的选项，例如 { mobile: true, browser: 'chrome' } }); // 4. 合并两侧结果，得到最终的 Coach 结果。 const coachResult = merge(domResult, harResult);

coachResult的结构与 sitespeed.io 写出的coach.json完全一致：按类别划分的分数、逐规则条目（含score、weight、severity、advice文本和offending列表）。这也与上面提到的 fixture coach.run-0.json 的结构相互印证。

库还暴露了若干辅助函数：

• getThirdPartyWeb()与getThirdPartyWebVersion()——Coach 做第三方检测所使用的 third-party-web 数据及其版本；
• getPageXray()——用于把 HAR 转换成页面摘要的 PageXray 实例；
• getTechnologiesVersion()与getWappalyzerCoreVersion()——技术识别数据的版本。

浏览器支持

Coach 针对最新的 Chrome 与 Firefox 进行测试。大多数规则也适用于 Edge 和 Safari，但项目不会对这两种浏览器运行自动化测试——如果规则在其他浏览器中表现异常，可以提交 issue 寻求处理。

面向开发者：编写或改进 Coach 规则

代码位置与开发环境

所有 Coach 规则与分析逻辑都位于coach-core仓库（注意：它独立于当前 sitespeed.io 仓库，sitespeed.io 通过 npm 依赖引入它）。本地开发流程：

git clone git@github.com:<your-fork>/coach-core.git cd coach-core npm install npm test

需要 Node.js 20 或更高版本；运行 DOM 测试还需要本地安装 Chrome 和 Firefox。

advice schema：每条规则的统一结构

无论 DOM 规则还是 HAR 规则，都产出同一形状的对象（摘自 developers 文档）：

{ id: 'uniqueId', // 唯一规则 id title: 'Short summary', description: 'Why the rule exists and what to do about it', advice: 'Specific, page-aware text written by the rule when it runs', score: 100, // 0–100。100 表示没有需要标记的问题。 weight: 5, // 0–10。该规则在所属类别中的重要性。 severity: 'warn', // 'error' | 'warn' | 'info' offending: [], // 造成分数下降的资源 URL（或其他标识符）数组 tags: ['performance', 'css'] }

severity是一目了然的分诊等级；weight决定规则失败时下拉类别分数的程度；score是规则针对被分析页面实际产出的分数。

DOM advice 与 HAR advice 的区别

Coach 分两次分析一个页面，每条规则属于其中一侧：

• DOM advice以 JavaScript 形式在浏览器内部运行，检查活页面。适合只有活 DOM 才能回答的问题：哪些脚本阻塞了解析器、<img>标签是否使用decoding="async"、文档大小、LCP 元素是否带fetchpriority="high"；
• HAR advice在 Node.js 中运行，检查本次运行产生的 HAR 文件。适合网络日志回答最好的问题：缓存头、重定向、渲染阻塞时序、响应数量、第三方使用情况。

HAR 规则还能看到同一页面的 DOM 结果（processPage(page, domAdvice, options)），因此 HAR 规则可以把网络事实与 DOM 规则观察到的事实结合起来。在 DOM 侧与 HAR 侧共享同一id的规则会被合并，且HAR 结果优先。

一个 DOM 规则示例：检查 print stylesheet

DOM 规则被打包成一个注入浏览器的 JavaScript 文件，因此每条规则都是一个返回 advice 对象的 IIFE，辅助函数通过util参数提供：

(function (util) { 'use strict'; const offending = []; const links = document.getElementsByTagName('link'); for (const link of links) { if (link.media === 'print') { offending.push(util.getAbsoluteURL(link.href)); } } const score = Math.max(0, 100 - offending.length * 10); return { id: 'cssPrint', title: 'Do not load specific print stylesheets.', description: 'A separate print stylesheet still costs a request and bytes even though screen readers ignore it. Inline the print rules in your main CSS with @media print instead.', advice: offending.length > 0 ? `The page has ${util.plural(offending.length, 'print stylesheet')}. Move them into your main CSS with @media print.` : '', score, weight: 1, severity: 'info', offending, tags: ['performance', 'css'] }; })(util);

一个 HAR 规则示例：检查页面总大小

HAR 规则是 ESM 模块，包含静态 schema 和一个processPage函数（针对 HAR 中每个页面运行一次），该函数返回结果的动态部分（score、advice、offending）：

import * as util from '../util.js'; export default { id: 'pageSize', title: "Total page size shouldn't be too big", description: 'Large pages are slower on every connection. Keep transfer size under 2 MB on desktop and 1 MB on mobile.', weight: 3, severity: 'warn', tags: ['performance', 'mobile'], processPage(page, domAdvice, options) { const sizeLimit = options.mobile ? 1_000_000 : 2_000_000; if (page.transferSize > sizeLimit) { return { score: 0, offending: [], advice: `The page transfers ${util.formatBytes(page.transferSize)}, more than the ${util.formatBytes(sizeLimit)} limit.` }; } return { score: 100, offending: [], advice: '' }; } };

processPage的第三个参数options就是调用方传给analyseHar的选项——适合根据mobile、browser等运行时特征分支处理。

HTTP/2 与 HTTP/1 的分支

DOM 与 HAR 的辅助工具都提供isHTTP2检查，让同一条规则能按协议给出不同建议：

// DOM if (util.isHTTP2()) { // 不要推荐域名分片（domain sharding）等 } // HAR if (util.isHTTP2(page)) { // ... }

测试规则

每条规则都需要测试，测试代码与规则代码放在一起。一个 DOM 测试会针对test/http-server中的 fixture HTML 页面运行该规则：

it('detects a print stylesheet', () => runner.run('cssPrint.js').then(result => { assert.strictEqual(result.offending.length, 1); }) );

如果你新增一条 DOM 规则，需要在test/http-server下添加（或扩展）一个能触发它的 HTML fixture，然后通过npm test运行测试。这与 sitespeed.io 仓库中 coachTests.js 的做法思路一致：用固定的 fixture 数据验证聚合逻辑。

新增一个类别

Coach 目前拥有 performance、privacy、best practice、accessibility 和 info 五个类别。新增类别的方法是在lib/dom/<name>（和/或lib/har/<name>）下新建文件夹并把规则文件放进去。如果不确定新类别是否合适，建议先开一个 issue 讨论。

针对真实页面验证你的改动

编辑规则后，需要重建被打包的 DOM 脚本：

npm run combine

然后通过npm link把本地 checkout 接到 sitespeed.io 安装上，再对某个 URL 运行 sitespeed.io——Coach 就会使用你修改后的规则：

# 在 coach-core 目录中 npm link # 在 sitespeed.io 的 checkout 目录中 npm link coach-core sitespeed.io https://www.sitespeed.io/

为什么开源

每条规则都是开放的：你可以阅读确切的检查逻辑、修改它，或者新增一条规则。如果某条规则漏掉了某种情况、或者对你的网站判断不合理，可以向coach-core提交 issue 或 PR。每条规则都带有单元测试，因此保持易于修改。在 sitespeed.io 侧，Coach 的汇总、上报与 HTML 渲染同样是开源的，分别对应 coach 插件、聚合器 与 HTML 模板，形成从规则到报告的完整闭环。

• 测试
• 性能剖析
• 指标监控