SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场web-performance-audit

web-performance-audit

测试与质量

查看项目

更新于 10-27 22:58

技能介绍

用途

Web Performance Audit 用于测量并报告一个线上网页的性能。它针对单个 URL 产出两份交付物，始终保存在项目的 docs/ 文件夹中：

docs/<site-slug>-performance/ report.md # 面向编码代理的事实来源：证据、代码、验证 report.html # 由 report-data.json 渲染，面向人工审阅者（标签页、图表、可筛选待办） report-data.json # 两份报告共用的数字与发现 .gitignore # 忽略 raw/ raw/ # Lighthouse JSON/HTML、trace、堆快照、QA 截图（永不提交）

<site-slug> 是裸主机名，例如 example-com-performance。如果项目没有 docs/ 文件夹，则创建它。永不提交 raw/：它有数百 MB，且来自真实浏览器配置的 trace 包含 cookie ID 和像素查询字符串。

前置条件

需要 Node.js 22.19+（当前 Lighthouse 要求；在更旧的 Node 上向运行器传 --lighthouse 12）、Google Chrome 144+、来自 chrome-devtools-mcp 包的 chrome-devtools CLI，最好还有 Chrome DevTools MCP 服务器及其上游技能。用 chrome-devtools --version 检查。如有缺失，先完成一次设置，然后继续。

保持数字可信的规则

  • 现场数据优先，实验室数据用于诊断。CrUX p75（28 天）说明用户是否有问题；trace 和 Lighthouse 说明原因。绝不单凭实验室数据断言用户未通过 Core Web Vitals，也绝不在部署后立即断言现场数据改善。
  • DevTools MCP 的 lighthouse_audit 工具不包含 Performance 类别。Performance 分数和指标取自 Lighthouse CLI（scripts/run-lighthouse.mjs）；lighthouse_audit 仅用于无障碍、SEO 和最佳实践。
  • 每个设备形态至少运行 3 次；报告中位数与范围。顺序运行 Lighthouse，并在其运行时保持用户浏览器空闲。
  • 为每个数字说明条件：浏览器配置、设备与节流、冷或热缓存、同意与登录状态。
  • 浏览器扩展会污染 trace。在用户自己的配置中，trace 会把扩展工作（ThirdParties 中的 chrome-extension://<id>）归因到页面。在隔离上下文中重新测量（new_page --isolatedContext <name>），真实配置运行仅用于对比。
  • 后台标签页会被节流。在追踪前把测量标签页置于前台（select_page <id> --bringToFront true）。
  • 在推荐修复前验证根因。如果某个洞察暗示了原因（例如滑块隐藏了 LCP 图片），先用小实验测试（见方法论中的 LCP 候选记录器）再写下来。一个看似合理但错误的 P0 会浪费团队一个冲刺。
  • 绝不输入凭据。如果审计需要登录状态，用户先在自己的 Chrome 中登录，然后你用 --autoConnect 附加。

工作流

用以下清单跟踪进度：

Audit progress:

  • [ ] 1. Scope: URL, states to compare (anonymous / consented / logged in), output folder
  • [ ] 2. Lab baseline: Lighthouse CLI 3x mobile + 3x desktop, clean headless profile
  • [ ] 3. Field data + traces: cold and warm reload traces, desktop and throttled mobile
  • [ ] 4. Diagnose: insights for failing metrics only; verify the root cause
  • [ ] 5. Interactions (INP) and memory (heap snapshots before/after repeated interactions)
  • [ ] 6. Write report-data.json, then report.md
  • [ ] 7. Render report.html, check it in a browser, publish if asked

1. 范围

仅在不明时询问：哪个 URL、哪些访客状态重要、是否可以使用用户的真实 Chrome 配置。然后把审计文件夹固定为绝对路径并创建其 raw 文件夹，使下面的每个 trace、日志和重定向都落在被忽略的 raw/ 内，无论工作目录是什么：

AUDIT="$PWD/docs/example-com-performance"; mkdir -p "$AUDIT/raw/lighthouse" "$AUDIT/raw/traces" && printf 'raw/\n' > "$AUDIT/.gitignore"

在 Windows PowerShell 上，设置 $AUDIT = "$PWD\docs\example-com-performance" 并用 New-Item -ItemType Directory -Force 创建相同文件夹。

2. 实验室基线（Lighthouse CLI）

node <skill-dir>/scripts/run-lighthouse.mjs --url https://example.com/ --out "$AUDIT/raw/lighthouse" --runs 3 node <skill-dir>/scripts/summarize-lighthouse.mjs "$AUDIT/raw/lighthouse" "$AUDIT/raw/lighthouse-summary.json"

运行器会拒绝已包含运行的 --out 文件夹，因为汇总器会把它们混入中位数；为每个审计状态使用新文件夹，或用 --clean 替换它们。在 WSL 上，运行器自己启动 Linux Chrome，因为 Lighthouse 自带的启动器在那里会失败（设置）；绝不要在 WSL 中直接运行 lighthouse。摘要打印中位数与范围、失败审计及估计节省、主线程分解、每个脚本的启动时间、第三方、按类型和主机的资源总量以及 LCP 子部分。在后台运行它，期间不要做 CPU 密集的事。

3. 现场数据与 trace（DevTools CLI）

脚本化步骤用 CLI，交互式探索用 MCP 工具；它们共享相同的工具名。完整命令模式、模拟预设和同意状态技术在方法论中。

chrome-devtools new_page "https://example.com/" --isolatedContext perf chrome-devtools performance_start_trace <pageId> --reload true --autoStop true --ignoreCache true --filePath "$AUDIT/raw/traces/desktop-cold.json.gz"

trace 摘要包含 CrUX p75 现场数据（URL 或来源范围），当 Google 有数据时。设备形态跟随模拟设备：桌面 trace 返回桌面现场数据，移动模拟 trace 返回手机现场数据。两者都记录。

对于节流的移动 trace，CLI 客户端可能在页面稳定前超时。使用 --autoStop false，等待约 45 秒，然后 performance_stop_trace <pageId> --filePath ...。

4. 诊断

仅对与失败或可疑指标相关的洞察调用 performance_analyze_insight：LCPBreakdown、RenderBlocking、NetworkDependencyTree、ThirdParties、DOMSize、ForcedReflow、Cache、ImageDelivery、INPBreakdown、CLSCulprits。将每个输出保存在 $AUDIT/raw/traces/ 下。使用 trace 打印的洞察集 ID（NAVIGATION_0、NAVIGATION_1 或 NO_NAVIGATION）；不要假设它是 NAVIGATION_0。

先选瓶颈 LCP 子部分（TTFB、加载延迟、加载时长、渲染延迟）。仅针对该子部分推荐修复，并在写下来之前用实验验证原因。

5. 交互与内存

INP：安装 Event Timing 观察器，在 4x CPU 下点击真实 UI 控件（菜单、搜索、滑块、手风琴），并读取每次交互的输入延迟、处理和呈现。同时记录一次交互 trace 用于 INPBreakdown。

内存：加载后取堆快照，重复一组交互 10 次，再取第二个快照。重新加载后元素 UID 会变化，因此在脚本化点击前先取新的 take_snapshot。然后对每个文件使用 compare_heapsnapshots、get_heapsnapshot_details --filterName objectsRetainedByDetachedDomNodes 和 close_heapsnapshot。当增量平稳时报告“无泄漏”；重但稳定的堆是单独的发现。

6. 编写 report-data.json，然后 report.md

在 report-data.json 中一次性收集每个数字（模式和示例见 assets/report-data.example.json）。然后按报告结构编写 report.md：

executive summary

method and conditions

scorecard (field, lab, field vs lab)

LCP deep dive

JS / main thread / third parties

payload vs budget

INP

memory

prioritized to-do (P0-P3: evidence, how with code, verify)

verification plan with budgets

reproduce

将每个未测试的想法标记为假设。

7. 渲染并检查 HTML 报告

node <skill-dir>/scripts/render-html-report.mjs docs/example-com-performance/report-data.json docs/example-com-performance/report.html

输出是一个自包含文件：浅色和深色主题、标签页、带工具提示和表格视图的 SVG 图表、带复制按钮的优先级可筛选待办列表。在浏览器中打开并检查：

  • 无控制台错误
  • 每个标签页都能切换
  • 390 px 宽度下无水平滚动

如果用户想分享且有 artifact 或发布工具可用，发布渲染后的页面并给他们链接。

完成

关闭你打开的每个标签页并运行 chrome-devtools stop。

不要动用户自己的标签页。

告诉用户报告在哪里、测量了什么、哪些状态无法测量以及前三项修复。

仅提交报告文件（绝不提交 raw/），且仅在用户要求时。