webperf-resources

WebPerf：资源与网络

用于在 Chrome DevTools 中测量 Web 性能的 JavaScript 代码片段。

运行脚本

1. 使用 mcp__chrome-devtools__evaluate_script 运行脚本，并读取其返回的对象。脚本不会输出到控制台，因此返回的对象就是结果：script、status 和指标数据（value、rating、details、items、issues），具体说明见 references/schema.md。
2. 当 status 为 "tracking" 时，脚本会持续观察页面。完成交互后，再次调用 mcp__chrome-devtools__evaluate_script，并运行 getDataFn 中指定的函数（例如 getINP()），然后读取其返回的对象。
3. 当 status 为 "error" 或 "unsupported" 时，请查看 error：页面可能尚未加载，或者浏览器不支持该 API。

如果没有 Chrome DevTools MCP，请使用 webperf-snippets CLI 运行相同的代码片段。它会在无头 Chromium 中加载页面，并输出相同的结果对象：npx webperf-snippets <url> --snippet <Name> --json，其中 <Name> 是不带 .js 的脚本名称。该工具需要 Playwright 和 Chromium（先运行 npm install --save-dev webperf-snippets playwright，然后运行 npx playwright install chromium）；跟踪类代码片段需要使用 --interact-script <file> 执行交互。

脚本

• scripts/Network-Bandwidth-Connection-Quality.js — 网络带宽与连接质量

常见工作流

网络质量评估

当用户询问网络性能、连接质量或自适应加载时：

1. Network-Bandwidth-Connection-Quality.js — 分析网络带宽、有效连接类型、RTT、下行速度和节省流量模式

自适应加载策略

当用户实施自适应加载，或询问“如何针对慢速连接进行优化”时：

1. Network-Bandwidth-Connection-Quality.js — 检测连接质量
2. 交叉参考 webperf-loading 技能：
   • TTFB.js（测量慢速连接下的服务器响应）
   • Find-render-blocking-resources.js（找出可延迟加载的大型资源）
   • Resource-Hints-Validation.js（优化慢速网络下的预连接）
3. 交叉参考 webperf-media 技能：
   • Image-Element-Audit.js（根据连接情况实施响应式图片）
   • Video-Element-Audit.js（根据连接情况调整视频质量）

检测节省流量模式

当用户询问节省流量或数据节省功能时：

1. Network-Bandwidth-Connection-Quality.js — 检查是否已启用节省流量模式
2. 如果已启用节省流量模式，建议：
   • 降低图片质量
   • 禁用视频自动播放
   • 延迟加载非关键资源
   • 使用低分辨率缩略图

移动端／慢速连接优化

当用户询问“针对移动端进行优化”或“慢速连接用户”时：

1. Network-Bandwidth-Connection-Quality.js — 评估连接类型
2. 交叉参考 webperf-loading 技能：
   • TTFB.js（对慢速连接至关重要）
   • Find-render-blocking-resources.js（尽量减少慢速网络中的阻塞）
   • Critical-CSS-Detection.js（内联关键 CSS，以减少 RTT）
   • Prefetch-Resource-Validation.js（避免在慢速连接下过度预取）

决策树

使用此决策树，根据结果自动运行后续代码片段：

Network-Bandwidth-Connection-Quality.js 之后

• 如果 effectiveType 为 "slow-2g" 或 "2g" → 连接速度很慢，建议：

  1. 运行 webperf-loading:Critical-CSS-Detection.js（内联关键 CSS）
  2. 运行 webperf-media:Image-Element-Audit.js（实施积极的懒加载）
  3. 运行 webperf-loading:Prefetch-Resource-Validation.js（移除预取以节省带宽）
  4. 运行 webperf-core-web-vitals:LCP.js（缓慢的连接会严重影响 LCP）
  5. 建议采用精简的资源策略

• 如果 effectiveType 为 "3g" → 连接速度一般，建议：

  1. 运行 webperf-loading:Find-render-blocking-resources.js（尽量减少阻塞）
  2. 运行 webperf-media:Image-Element-Audit.js（使用响应式图片）
  3. 运行 webperf-loading:Resource-Hints-Validation.js（优化 preconnect）
  4. 运行 webperf-core-web-vitals:INP.js（高延迟可能影响交互响应速度）
  5. 实施自适应图片质量

• 如果 effectiveType 为 "4g" 或更高 → 连接状况良好，建议：

  1. 采用标准优化实践
  2. 考虑为导航策略性地预取资源
  3. 可以使用更高质量的媒体资源

• 如果已启用 save-data → 用户明确希望节省数据，建议：

  1. 大幅降低图片质量
  2. 禁用视频自动播放
  3. 延迟加载非关键资源
  4. 移除预取/预加载提示
  5. 提供“高质量”切换选项

• 如果 RTT > 300ms → 延迟较高，建议：

  1. 运行 webperf-loading:TTFB.js（延迟会影响 TTFB）
  2. 运行 webperf-loading:TTFB-Sub-Parts.js（分解延迟的各个组成部分）
  3. 运行 webperf-loading:Resource-Hints-Validation.js（RTT 较高时，preconnect 至关重要）
  4. 运行 webperf-loading:Service-Worker-Analysis.js（延迟较高时，缓存至关重要）
  5. 尽量减少源的数量
  6. 使用 HTTP/2 或 HTTP/3 实现多路复用

• 如果 downlink < 1 Mbps → 带宽非常有限，建议：

  1. 运行 webperf-media:Image-Element-Audit.js（积极压缩）
  2. 运行 webperf-media:Video-Element-Audit.js（禁用自动播放）
  3. 运行 webperf-loading:Prefetch-Resource-Validation.js（移除预取）
  4. 实施带宽感知型加载

• 如果 downlink > 10 Mbps → 带宽良好，可考虑：

  • 使用更高质量的媒体资源
  • 策略性地预取资源
  • 预加载下一页资源

自适应加载实施指南

根据 Network Information API 的结果，实施以下策略：

对于 slow-2g / 2g（< 50 Kbps）：（effectiveType: "slow-2g" 或 "2g"）

• 提供低分辨率图片（quality：30-40）
• 禁用视频自动播放
• 移除所有预取提示
• 内联所有关键 CSS
• 延迟加载所有非关键 JavaScript
• 使用系统字体（不使用网络字体）
• 积极懒加载（滚动时加载并预留缓冲区）

对于 3g（50-700 Kbps）：（effectiveType: "3g"）

• 提供中等分辨率图片（quality：60-70）
• 禁用视频自动播放
• 限量预取（仅关键资源）
• 仅内联关键 CSS
• 延迟加载非关键 JavaScript
• 预加载 1-2 种关键字体
• 标准懒加载

对于 4g+（> 700 Kbps）：（effectiveType: "4g"）

• 提供高分辨率图片（quality：80-90）
• 允许视频自动播放（静音）
• 为导航策略性地预取资源
• 标准 CSS 和 JavaScript 加载
• 预加载关键字体
• 标准懒加载

对于 save-data 模式：（navigator.connection.saveData === true）

• 覆盖连接类型，按比实际情况更差的连接处理
• 显示“加载高质量内容”切换选项
• 完全禁用自动播放
• 使用最少的图片，并将图片质量降至最低
• 不进行预取或预加载（关键资源除外）

按连接类型划分的性能预算

根据连接质量调整性能预算：

slow-2g / 2g：

• 页面总大小：< 500KB
• 图片：总计 < 200KB
• JavaScript：总计 < 100KB
• 不使用视频

3g：

• 页面总大小：< 1.5MB
• 图片：总计 < 800KB
• JavaScript：总计 < 300KB
• 视频：< 3MB（仅限关键视频）

4g+：

• 页面总大小：< 3MB
• 图片：总计 < 2MB
• JavaScript：总计 < 1MB
• 视频：< 10MB

网络信息 API 的局限性

请注意 API 的局限性及回退方案：

API 不可用：

• Safari 不支持 Network Information API
• 回退方案：使用 TTFB 作为连接质量的代理指标
• 回退方案：检测设备类型（移动设备 = 假设网速较慢）
• 回退方案：提供用户偏好切换选项

API 返回的值为估算值：

• effectiveType 基于近期观测结果
• 值可能会在会话期间变化
• 对于持续时间较长的会话，请定期重新检查

隐私注意事项：

• 某些浏览器会出于隐私考虑限制精度
• 值可能会被取整或限制在特定范围内
• 做决策时请考虑用户隐私

参考资料

• references/snippets.md — 每个脚本的描述和阈值
• references/schema.md — 用于解读脚本输出的返回值架构