sitespeed.io Matrix 消息推送实战:配置、预算结果与错误告警的完整指南
sitespeed.io Matrix 消息推送实战:配置、预算结果与错误告警的完整指南
导读:本文围绕 sitespeed.io 内置的 Matrix 插件,讲解如何把性能测试的预算结果(通过/失败/错误)与测试运行错误实时推送到 Matrix(Element)客户端。读完本文,你将掌握 --matrix.host、--matrix.accessToken、--matrix.room 等全部配置参数、按消息类型分房间路由的用法,并结合仓库源码理解消息的构造、发送与重试机制,从而把性能预算监控接入自己的聊天与告警工作流。
Matrix 插件能做什么
Matrix 是一个开源、去中心化的安全通信网络,Element 是其中最常用的客户端之一。sitespeed.io 的 Matrix 插件(源码位于 lib/plugins/matrix/index.js)让你把两类消息直接发到 Matrix 房间:
- 预算消息(budget):页面通过性能预算、页面未通过预算(列出具体超标的指标与数值)、以及预算执行出错(如某 URL 无法测试)时的消息;
- 错误消息(error):测试运行过程中产生的错误(例如浏览器/设备启动失败、脚本执行异常),方便你及时掌握测试本身是否正常工作。
插件的 messageTypes() 方法明确了当前支持的两种消息类型,它同时被 CLI 选项解析所引用:
// lib/plugins/matrix/index.js
export function messageTypes() {
return ['error', 'budget'];
}
配置 Matrix 通知
必需参数
要让 sitespeed.io 把消息发送到 Matrix,至少需要配置以下三个参数:
| 参数 | 说明 |
|---|---|
--matrix.host |
你的 Matrix 服务器主机地址,例如 matrix.example.com |
--matrix.accessToken |
你的用户访问令牌(Access Token),可通过 Matrix 客户端 API 获取 |
--matrix.room |
默认房间 ID,sitespeed.io 会把消息发送到这个房间 |
在插件初始化阶段,源码会用 throwIfMissing 校验这三个参数,缺失任何一个都会直接报错,确保配置在运行时是完整的:
// lib/plugins/matrix/index.js(open 方法)
throwIfMissing(options.matrix, ['accessToken', 'host', 'room'], 'matrix');
这些 CLI 选项定义在 lib/cli/options/matrix.js,运行 sitespeed.io --help 时也会在 Matrix 分组下看到它们。
可选参数
| 参数 | 说明 |
|---|---|
--matrix.messages |
选择要发送的消息类型,可选值为 error、budget;默认两者都发送,即 ["error","budget"] |
--matrix.rooms |
按消息类型把消息路由到不同房间,例如 --matrix.rooms.error 房间A --matrix.rooms.budget 房间B |
推荐使用配置文件
官方文档建议通过配置文件来管理 Matrix 配置。下面是一个完整的示例(matrix-config.json):
{
"matrix": {
"host": "myhost.com",
"room": "THE_DEFAULT_ROOM",
"accessToken": "THEVERYLONGTOKEN",
"rooms": {
"budget": "THE_ROOM_FOR_BUDGET_MESSAGES",
"error": "THE_ROOM_FOR_ERROR_MESSAGES"
}
}
}
- 没有配置
matrix.rooms时,所有消息都发往默认的room; - 配置了
matrix.rooms后,budget 消息发往rooms.budget,error 消息发往rooms.error,实现"告警分流"。
命令行直接运行
不借助配置文件时,也可以把所有参数放到命令行(以 Docker 运行方式为例,参数说明以当前仓库 lib/cli/options/matrix.js 为准):
docker run --rm -v "$(pwd):/sitespeed.io" sitespeedio/sitespeed.io \
https://www.sitespeed.io/ -b chrome -n 3 \
--matrix.host matrix.example.com \
--matrix.accessToken YOUR_TOKEN \
--matrix.room YOUR_DEFAULT_ROOM
如需只发送预算消息、并将错误消息发到单独房间:
--matrix.messages budget \
--matrix.rooms.budget YOUR_BUDGET_ROOM \
--matrix.rooms.error YOUR_ERROR_ROOM
消息如何按类型路由到房间
在插件处理消息时,房间的选择遵循"优先使用类型专属房间,回退到默认房间"的规则。源码中多次出现这一模式:
// lib/plugins/matrix/index.js
// 错误消息在渲染阶段发送
const room = get(options, 'rooms.error', options.room);
// 预算消息在预算结果产生时发送
const room = get(options, 'rooms.budget', options.room);
其中 get 是项目自带的 objectPath 工具(lib/support/objectPath.js#L17),作用是从配置对象中按路径取值并支持默认值。这意味着 rooms.error 和 rooms.budget 是可选的覆盖项,未配置时自动落到 room。
错误消息:掌握测试是否正常工作
Matrix 插件处理 error 类型消息的逻辑位于 lib/plugins/matrix/index.js 的 case 'error' 分支。它有两个值得注意的设计:
1. 批量聚合发送,避免触发限流。 源码注释明确说明:如果逐条发送错误消息,可能瞬间发出太多请求导致 Matrix 返回 429(Too Many Requests)。因此插件先把所有错误文本拼接进 this.errorTexts,等到渲染阶段(sitespeedio.render 消息)才一次性发出:
case 'error': {
// We can send too many messages to Matrix and get 429 so instead
// we bulk send them all one time
if (options.messages.includes('error')) {
this.errorTexts += `⚠️ Error from <b>${
message.source
}</b> testing ${message.url || ''} <pre>${message.data}</pre>`;
}
break;
}
case 'sitespeedio.render': {
if (this.errorTexts !== '') {
const room = get(options, 'rooms.error', options.room);
try {
const answer = await send(options.host, room, options.accessToken, this.errorTexts);
} catch { /* TODO */ }
}
break;
}
错误消息内容包含消息来源(message.source,例如 browsertime)、被测 URL 以及错误详情 message.data。这些 error 消息由测试过程中各插件发出,例如 Browsertime 插件在浏览器/脚本运行失败时通过 super.sendMessage('error', ...) 上报(见 lib/plugins/browsertime/index.js),并会在队列层被统一登记(见 lib/core/queueHandler.js)。
2. 错误示例。 下图是一条典型的错误通知:显示测试文件 tests/ZY2242HJDX-Moto-G4/random.js 运行失败,错误为 FailError: Failure: 'device 'ZY2242HJDX' not found'(未找到测试设备)。
预算消息:通过、失败与错误
预算消息是 Matrix 插件最主要的应用场景。它消费的是 Budget 插件发出的 budget.result 消息(见 lib/plugins/budget/index.js),该消息在 sitespeedio.prepareToRender 阶段由 lib/plugins/budget/verify.js 的验证结果汇总而来,结构上包含三个按 URL 分组的对象:
failing:未通过预算的 URL 及其超标指标;working:通过预算的 URL;error:测试出现错误的 URL。
全部通过
当 failing 与 error 均为空时,Matrix 会收到一条祝贺消息,文案形如:
🎉 All (50) URLs passed the budget.
消息中还会带上测试名称(如果配置了 --name)以及浏览器/设备信息。浏览器信息来自 browsertime.browser 消息,插件通过 getBrowserData() 组装,包含浏览器名称、版本,以及 Android 设备时的型号(model)、系统版本(androidVersion)与设备 ID(id):
// lib/plugins/matrix/index.js
function getBrowserData(data) {
return data && data.browser
? `${data.browser.name} ${data.browser.version} ...android.model... android.androidVersion... android.id...`
: '';
}
上图中可以看到:All (50) URLs passed the budget.,测试对象为随机页面,浏览器为 Chrome 86.0.4240.110。
存在失败
当存在未通过预算的 URL 时,消息会以 <h1> 标题列出失败数量,随后逐条列出失败 URL 及每个超标指标的实际值 vs 限制值,例如:
Total Blocking Time : 2.055s (2.000s)——总阻塞时间超过阈值;Long Task : 16 (15)——长任务数量超过阈值。
上图为真实示例:Budget failing (24 URLs),测试对象为英文维基百科页面,设备为 Moto G Play 7.1.1(设备 ID ZY2242HJDX),并逐条列出了总阻塞时间、长任务数量等超标项。
从源码看,失败消息的构造逻辑会为每个 URL 生成"结果页链接"和"截图链接"(当配置了结果存储基础 URL 时),方便直接跳转到 HTML 报告核查:
text += this.resultUrls.hasBaseUrl()
? ` (<a href="${...}index.html">result</a> - <a href="${...}data/screenshots/1/afterPageCompleteCheck.${this.screenshotType}">screenshot</a>)`
: '</h5>';
预算测试出错
当某些 URL 测试本身出错(如页面无法加载)时,消息会以 Budget errors testing N URLs 标题列出出错的 URL 与错误详情(<pre> 代码块)。
与上传存储联动:等待上传完成再发送
插件还支持与 GCS、S3、FTP、SCP 等存储插件联动:当收到 gcs.setup、ftp.setup、s3.setup 消息时,会设置 this.waitForUpload = true,此时预算消息不会立即发送,而是暂存在 this.budgetText 中,直到收到对应的 *.finished 消息后再发送——这样预算通知里能带上完整的结果链接/截图(截图已上传):
case 'gcs.finished':
case 'scp.finished':
case 'ftp.finished':
case 's3.finished': {
if (this.waitForUpload && options.messages.includes('budget')) {
const room = get(options, 'rooms.budget', options.room);
await send(options.host, room, options.accessToken, this.budgetText);
}
break;
}
预算本身如何判定(背景原理)
budget.result 中的 failing/working 由 lib/plugins/budget/verify.js 逐 URL 校验产生。其判定规则是:对 timings、requests、transferSize、thirdParty、score 等配置项,Coach / Lighthouse / GPSI 的评分类指标采用 min 语义(得分低于预算即失败),其余计时、请求数、体积类指标采用 max 语义(数值高于预算即失败)。这与 Matrix 消息中"指标 : 实际值 (限制值)"的展示一一对应。完整的预算文件写法可参考仓库文档 性能预算配置。
底层发送实现:向 Matrix 客户端 API 发消息
消息的实际投递由 lib/plugins/matrix/send.js 完成,它直接调用 Matrix 客户端-服务器 API,没有依赖额外的 SDK:
- HTTP 端点:
POST https://{host}/_matrix/client/r0/rooms/{room}/send/m.room.message?access_token={accessToken},固定使用 443 端口; - 消息格式:
msgtype: 'm.notice',并声明format: 'org.matrix.custom.html',把插件构造的 HTML 内容放入formatted_body字段,从而在 Element 等客户端中渲染出标题、列表、链接等富文本效果; - 重试与退避:当服务端返回 408、429、500、503 时,最多重试 3 次,每次等待时间从 5 秒起、逐次翻倍(5s → 10s → 20s),其他错误码则直接记录日志并拒绝:
// lib/plugins/matrix/send.js
const retryCodes = new Set([408, 429, 500, 503]);
// 失败后 setTimeout 递归调用 send,retries - 1, backoff * 2
这个设计保证了在 Matrix 服务暂时不可用或限流时,消息仍有较高概率送达。
常见问题与排查建议
- 提示缺少配置:启动时若出现 matrix 相关配置校验错误,请检查
matrix.host、matrix.accessToken、matrix.room三者是否齐全(源码在插件open阶段强制校验)。 - 收不到错误消息:确认没有用
--matrix.messages把error排除掉;错误消息是聚合后在一次渲染结束时发送的,所以是批量到达而非逐条实时到达。 - 收不到预算消息但配置了 S3/GCS:注意
*.finished依赖上传完成事件,请检查上传插件是否正常工作,否则预算消息会被暂存而不发送。 - 消息显示为纯文本而非富文本:消息以
m.notice+org.matrix.custom.html发送,请在支持 HTML 渲染的 Matrix 客户端(如 Element)中查看。 - 发送被限流:
send.js对 429 等状态码内置了指数退避重试,若仍频繁失败,可以检查 Matrix 服务端限流策略或拆分监控频率。
总结
Matrix 插件为 sitespeed.io 的"性能预算 + 持续监控"工作流提供了轻量的消息出口:三类必需参数即可连通 Matrix 房间,matrix.rooms 实现预算/错误消息分流,批量聚合发送避免限流,HTML 富文本让通过/失败/错误三类结果一目了然。结合性能预算与上传存储,你可以把预算告警、错误通知无缝接入团队日常使用的 Matrix 聊天频道,实现性能监控的闭环反馈。


