webperf-media

WebPerf：媒体性能

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

运行脚本

1. 使用 mcp__chrome-devtools__evaluate_script 运行脚本，并读取其返回的对象。脚本不会输出到控制台，因此返回的对象就是结果：script、status 和指标数据（value、rating、details、items、issues），具体说明见 references/schema.md。
2. 当 status 为 "tracking" 时，脚本会持续观察页面。完成交互后，再调用 getDataFn 中命名的函数，并再次使用 mcp__chrome-devtools__evaluate_script 调用，例如 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/Image-Element-Audit.js — 图像元素审计
• scripts/Oversized-Images.js — 过大图像
• scripts/SVG-Embedded-Bitmap-Analysis.js — SVG 嵌入位图分析
• scripts/Video-Element-Audit.js — 视频元素审计

常见工作流

完整媒体审计

当用户要求优化媒体或“审计图像和视频”时：

1. Image-Element-Audit.js — 分析所有图像（格式、延迟加载、尺寸、fetchpriority）
2. Video-Element-Audit.js — 分析所有视频（poster、preload、格式、自动播放）
3. SVG-Embedded-Bitmap-Analysis.js — 检测嵌入 SVG 的低效位图

图像优化工作流

当用户要求“优化图像”或“检查图像性能”时：

1. Image-Element-Audit.js — 全面审计图像
2. 与 webperf-loading 技能交叉参考：
   • Find-Above-The-Fold-Lazy-Loaded-Images.js（错误地延迟加载的图像）
   • Find-non-Lazy-Loaded-Images-outside-of-the-viewport.js（缺少延迟加载的图像）
   • Find-Images-With-Lazy-and-Fetchpriority.js（属性之间存在冲突）
   • Priority-Hints-Audit.js（LCP 图像应设置 fetchpriority="high"）

过大图像审计

当用户询问尺寸超出需要的图像、浪费的字节、模糊的图像或 srcset/sizes 问题时：

1. Oversized-Images.js — 比较每个图像文件与实际绘制的像素（检查尺寸过大和过小的图像）
2. Image-Element-Audit.js — 检查被标记图像的格式、延迟加载和 srcset 用法
3. 与 webperf-core-web-vitals 技能交叉参考：
   • LCP.js（检查过大图像是否为 LCP 元素）

视频性能审计

当用户要求“优化视频”或“检查视频性能”时：

1. Video-Element-Audit.js — 全面审计视频
2. 与 webperf-core-web-vitals 技能交叉参考：
   • LCP-Video-Candidate.js（检查视频或 poster 是否为 LCP）
3. 与 webperf-loading 技能交叉参考：
   • Priority-Hints-Audit.js（视频 poster 优先级）
   • Resource-Hints-Validation.js（视频预加载）

LCP 图像调查

当 LCP 是图像且需要优化时：

1. 与 webperf-core-web-vitals 技能交叉参考：
   • LCP.js（测量 LCP）
   • LCP-Image-Entropy.js（分析图像复杂度）
2. Image-Element-Audit.js — 检查格式、尺寸和延迟加载
3. 与 webperf-loading 技能交叉参考：
   • Find-Above-The-Fold-Lazy-Loaded-Images.js（不应延迟加载）
   • Priority-Hints-Audit.js（应设置 fetchpriority="high"）
   • Resource-Hints-Validation.js（考虑预加载）

图片导致的布局偏移

当 CLS 是由缺少尺寸信息的图片引起时：

1. Image-Element-Audit.js - 检查是否缺少 width/height 属性
2. 与 webperf-core-web-vitals 技能交叉参照：
   • CLS.js（测量总 CLS）
3. 与 webperf-interaction 技能交叉参照：
   • Layout-Shift-Loading-and-Interaction.js（查看偏移发生的时间）

SVG 优化审计

当用户询问 SVG 性能，或文件较大时：

1. SVG-Embedded-Bitmap-Analysis.js - 检测嵌入在矢量 SVG 中的栅格图像
2. 对未嵌入位图的 SVG，建议使用 SVGO 优化
3. 建议将位图提取为单独的图像文件，并使用合适的格式

决策树

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

在 Image-Element-Audit.js 之后

• 如果图片缺少 width/height 属性 → 存在布局偏移风险，运行：

  1. webperf-core-web-vitals:CLS.js（测量 CLS 影响）
  2. webperf-interaction:Layout-Shift-Loading-and-Interaction.js（查看偏移发生的时间）
  3. 建议为所有图片添加明确的尺寸

• 如果图片使用了错误的格式（图形使用 JPEG、照片使用 PNG） → 建议：

  • 现代格式：WebP、AVIF
  • 根据内容类型选择合适的格式
  • 使用针对特定格式的压缩设置

• 如果图片尺寸远大于显示尺寸 → 建议：

  • 使用带 srcset 的响应式图片
  • 设置合适的图像 CDN 尺寸
  • 使用带有多个尺寸的 srcset，以适配不同视口

• 如果首屏图片采用了延迟加载 → 运行：

  1. webperf-loading:Find-Above-The-Fold-Lazy-Loaded-Images.js（确认）
  2. webperf-core-web-vitals:LCP.js（测量 LCP 影响）
  3. 建议从首屏图片中移除 loading="lazy"

• 如果 LCP 图片缺少 fetchpriority="high" → 运行：

  1. webperf-core-web-vitals:LCP.js（测量当前 LCP）
  2. webperf-loading:Priority-Hints-Audit.js（全面审计优先级）
  3. 建议为 LCP 图片添加 fetchpriority="high"

• 如果首屏以下的图片未采用延迟加载 → 运行：

  1. webperf-loading:Find-non-Lazy-Loaded-Images-outside-of-the-viewport.js（确认）
  2. 建议为屏幕外的图片添加 loading="lazy"

• 如果图片同时设置了 loading="lazy" 和 fetchpriority="high" → 运行：

  1. webperf-loading:Find-Images-With-Lazy-and-Fetchpriority.js（确认存在冲突）
  2. 建议移除其中一个冲突属性

• 如果图片与关键资源竞争 → 运行：

  1. webperf-loading:Find-render-blocking-resources.js（检查资源优先级冲突）
  2. webperf-loading:TTFB-Resources.js（识别速度较慢的图像 CDN）

• 如果图片缺少 alt 文本 → 这是无障碍问题，建议添加描述性 alt 文本

在 Oversized-Images.js 之后

• 如果发现超大图片 → 建议：

  • 使用含多个宽度值的 srcset，并设置准确的 sizes 属性
  • 在构建时调整图片尺寸，或使用图像 CDN
  • 运行 Image-Element-Audit.js，检查同一批图片的格式和延迟加载情况

• 如果超大图片是 LCP 元素 → 运行 webperf-core-web-vitals:LCP.js 和 LCP-Subparts.js（大文件会延长资源加载时长）

• 如果发现尺寸过小（模糊）的图片 → 建议使用像素数至少满足需求的源图，并为高密度屏幕提供 2x 候选图

• 如果被跳过的图片采用了延迟加载 → 滚动到页面底部，然后重新运行代码片段

运行 Video-Element-Audit.js 后

• 如果视频是 LCP 候选元素 → 运行：

  1. webperf-core-web-vitals:LCP-Video-Candidate.js（确认）
  2. webperf-core-web-vitals:LCP.js（测量 LCP）
  3. webperf-core-web-vitals:LCP-Subparts.js（分解时间）
  4. 优化视频封面图，或考虑使用图片替代

• 如果视频缺少封面图 → 建议：

  • 添加封面图，以提升感知性能
  • 使用首帧或自定义缩略图
  • 像优化图片一样优化封面图

• 如果视频使用 preload="auto" → 需关注带宽，评估：

  • 视频是否位于首屏？保留 preload="auto"
  • 视频是否位于首屏下方？改为 preload="metadata" 或 "none"
  • 是否有意设置自动播放？确认 preload 符合预期

• 如果视频自动播放但未静音 → 浏览器会阻止播放，建议：

  • 添加 muted 属性
  • 或移除 autoplay

• 如果视频缺少多种格式 → 建议：

  • 为 Chrome/Firefox 提供 WebM
  • 为 Safari 提供 MP4 作为后备格式
  • 按效率排序资源（WebM 优先）

• 如果视频文件较大（>5MB） → 建议：

  • 压缩/转码
  • 使用自适应比特率流媒体（HLS、DASH）
  • 优化加载策略

运行 SVG-Embedded-Bitmap-Analysis.js 后

• 如果在 SVG 中发现位图 → 建议：

  1. 将位图提取为独立文件
  2. 提取的图片使用 WebP/AVIF 格式
  3. 在 SVG 中使用 元素引用图片
  4. 或尽可能将其转换为纯矢量图

• 如果嵌入的位图较大（>100KB） → 属于严重低效：

  • SVG 解析开销 + 大型位图 = 两种格式的缺点兼而有之
  • 强烈建议提取位图

• 如果 SVG 中有多个小型位图 → 考虑：

  • 为小图标使用 CSS 精灵图
  • 为可复用图形使用 SVG 符号
  • 将位图提取为单独的优化图片

性能预算阈值

使用以下阈值触发建议：

图片文件大小：

• 警告：单张图片 > 500KB → 检查格式和压缩情况
• 严重：单张图片 > 1MB → 需要立即优化
• 图片总大小：初始加载时 > 5MB → 实施延迟加载

图片格式：

• 图形/图标使用 JPEG → 建议改用 PNG 或 SVG
• 照片使用 PNG → 建议改用 JPEG、WebP 或 AVIF
• 动画使用 GIF → 建议改用视频（MP4/WebM）或动画 WebP
• 未使用现代格式（WebP/AVIF） → 建议升级

图片尺寸：

• 固有尺寸 > 显示尺寸的 2 倍 → 建议使用响应式图片
• 固有尺寸 < 显示尺寸 → 放大会导致模糊，应提供更大的源图

视频文件大小：

• 警告：视频 > 10MB → 考虑压缩或流媒体
• 严重：视频 > 50MB → 需要立即优化或使用流媒体

延迟加载：

• 首屏图片采用延迟加载 → 会严重影响 LCP，应立即修复
• 首屏下方图片未采用延迟加载 → 浪费带宽，应实施延迟加载
• 超过 10 张图片采用立即加载 → 数量过多，应实施延迟加载

优先级提示：

• LCP 图片未设置 fetchpriority="high" → 添加该属性，可提升 10-30% 的 LCP
• 非 LCP 图片设置了 fetchpriority="high" → 移除该属性，避免浪费浏览器提示
• 延迟加载与 fetchpriority="high" 冲突 → 修复矛盾配置

参考资料

• references/snippets.md — 各脚本的说明和阈值
• references/schema.md — 用于解读脚本输出的返回值架构