perf-audit

性能审计

工作流

1. 从 package.json 检测构建工具（vite、webpack、next、rollup）

2. 通过项目的任务运行器执行生产构建（从 package.json 自动检测）。

3. 分析构建输出——仅限非交互式操作。审计期间绝不启动浏览器或长时间运行的服务；它们会导致自动化运行挂起。按以下优先顺序选择：

   • 直接测量生成的文件：对于输出目录中的每个文件（例如 dist/assets/*.js），报告原始大小和 gzip 压缩后的大小——gzip -c <file> | wc -c。这种方法始终有效，无需额外工具。
   • 按模块细分，作为静态产物（不是服务），写入 $TMPDIR（否则写入 /tmp），绝不写入工作树，以免被下次 commit 一并提交。打印文件路径：
     • Vite/Rollup：npx source-map-explorer 'dist/assets/*.js'，或添加 rollup-plugin-visualizer 并配置为将 JSON/HTML 输出到文件
     • webpack/Next.js：npx webpack-bundle-analyzer -m static -r "${TMPDIR:-/tmp}/report.html" <stats-file>（写入文件；不要使用默认的服务模式）
   • npx vite-bundle-visualizer 会打开浏览器并阻塞——只能建议用户手动探索；不要在这里运行。

4. 检查 package.json 中是否包含已知的大型软件包

5. 检查源代码中是否存在以下 Core Web Vitals 风险。先检测框架；只推荐该框架惯用的做法。

6. 报告发现：说明包体积的影响，以及源代码风险的潜在影响

对照行业标准阈值；报告 gzip 压缩后的大小。

Core Web Vitals 风险

检查源代码中的以下风险；在经过测量前，每项都属于 潜在影响。

• LCP：主视觉图片或标题未延迟加载；初始 HTML 中的 LCP 图片带有 fetchpriority="high"；<head> 中没有未设置 defer/async 的脚本；已预加载关键字体
• CLS：图片、iframe 和嵌入内容预留了空间（width/height 或 aspect-ratio）；不会在现有内容上方注入内容；字体使用 font-display 并匹配备用字体
• INP：事件处理程序中没有长时间的同步操作；长循环会让出执行权（scheduler.yield()，或使用 setTimeout 作为回退）；繁重的工作在 worker 中执行
• 渲染：长列表使用虚拟化；动画仅作用于 transform/opacity；不存在先读取再写入的布局循环；仅在确有收益时使用记忆化
• 网络：彼此独立的请求并行发起，而不是按顺序 await；没有过度获取；列表采用分页；长时间缓存带哈希的静态资源；繁重的第三方组件通过外观模式延迟加载

输出格式

• 包体积摘要：总大小 / gzip 压缩后的大小，与预算对比
• 大型代码块：名称 + 大小 + 占总量的百分比
• 大型依赖：软件包 + 大小 + 更轻量的替代方案
• 快速优化：按估算节省量排序
• Core Web Vitals：LCP、INP、CLS——数值 + 来源，或 not measured
• 源代码风险：file:line、受影响的指标、修复方法

规则

• 报告 gzip 压缩后的大小（即浏览器下载的大小）
• 绝不自动更改依赖项——只报告并提出建议
• 用户未提供测量数据（Lighthouse 或 PageSpeed JSON、CrUX 数据、DevTools 跟踪）时，绝不声称 LCP、INP 或 CLS 的具体数值；标明数据属于实验室测量还是现场测量
• 跳过对 Core Web Vital 或包体积没有合理影响的微优化

错误处理

• 构建失败——报告错误，跳过包体积分析步骤，仍然执行源代码检查
• 未找到构建输出——先执行生产构建
• 无法识别构建工具——扫描 package.json 中的大型软件包，然后执行源代码检查