Front-End-Checklist 实战基于真实浏览器执行性能审计Lighthouse / Puppeteer / Playwright【免费下载链接】Front-End-Checklist The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-Checklist本篇技术指南以 Front-End-Checklist 仓库中browser-requiredPerform browser-based performance audits规则为核心讲解为什么性能审计必须发生在真实浏览器环境中以及如何用 Lighthouse、Puppeteer、Playwright 落地 LCP、CLS、INP 等运行时指标的测量。读完你将掌握一套可复制到 CI/CD 流程中的浏览器级性能审计方案并了解本仓库中该规则对应的源码级验证工具链。规则定位这是 performance 类目下的 metrics 子规则在 Front-End-Checklist 的内容体系中browser-required规则位于 packages/content/rules/en/performance/browser-required.mdx归属于performance类目、metrics子类目优先级为 medium、难度为 intermediate、预计耗时 10 分钟。与其配套的 Agent 技能入口是 skills/browser-required/SKILL.md该文件以 frontmatter 形式声明了规则的触发场景Use when auditing slow page loads, heavy assets, or rendering delays related to Perform browser-based performance audits. Verify the actual bottleneck in DevTools, Lighthouse, or field data before recommending changes.换句话说这条规则的职责边界是当你在审计慢页面加载、重资源或渲染延迟时必须先判断瓶颈是否真实存在于浏览器执行阶段再用浏览器级工具去量化它。规则的 check / fix / explain 三个动作分别是确保审计发生在能执行 JavaScript 并渲染页面的环境中如 Lighthouse、Puppeteer把 Lighthouse 或 WebPageTest 这类浏览器测试工具集成进开发流程与 CI/CD 管线向团队解释静态分析对性能的局限以及完整浏览器环境的必要性。为什么静态分析测不出真正的性能问题规则文档开门见山给出结论静态分析能发现一部分性能问题但大量关键指标只有在真实浏览器中执行页面时才能测得。这一判断可以从四个层面展开指标计算依赖渲染引擎Largest Contentful PaintLCP需要真正渲染出页面内容才能确定最大内容绘制的时刻Cumulative Layout ShiftCLS必须在元素移动的真实布局流程中累计位移分数。没有渲染引擎这些值根本不存在。JavaScript 执行影响主线程脚本对主线程的阻塞时长、交互延迟如 INP、TBT只有执行过脚本才能测量静态分析无法模拟 V8 引擎的解析、编译与执行开销。真实世界模拟只有浏览器环境可以同时做 CPU 节流与网络节流还原低端手机 弱网的真实用户体验。可视化反馈浏览器工具能产出加载过程的截图和录屏帮助定位卡顿jank与布局抖动。方案一用 Lighthouse CLI 发起完整浏览器审计Lighthouse 会启动一个完整的 Chrome 实例来审计页面规则文档给出了最小可用的两条命令# 安装 Lighthouse npm install -g lighthouse # 对 URL 发起审计--view 自动打开报告--chrome-flags 传入 Chromium 启动参数 lighthouse https://example.com --view --chrome-flags--headless在此基础上可以按审计需求扩展常用参数# 输出 JSON 报告并指定设备模拟与节流配置 lighthouse https://example.com \ --outputjson --output-path./lighthouse-report.json \ --presetdesktop \ --throttling-methodsimulate \ --chrome-flags--headless --no-sandbox --disable-gpu关键参数说明参数作用--view审计完成后自动打开 HTML 报告--output/--output-path导出 json / html / csv 格式报告到指定文件--presetdesktop以桌面配置运行默认移动端模拟--throttling-methodsimulate用模拟方式施加网络/CPU 节流比真实节流快得多--chrome-flags透传 Chromium 命令行参数CI 中常用--headless --no-sandbox方案二用 Puppeteer 脚本化浏览器审计并施加节流规则文档提供了基于 Puppeteer 的自动化方案通过 CDPChrome DevTools Protocol会话下发Network.emulateNetworkConditions来模拟 Fast 3G 网络然后读取页面运行时指标const puppeteer require(puppeteer); (async () { const browser await puppeteer.launch(); const page await browser.newPage(); // Throttling network and CPU const client await page.target().createCDPSession(); await client.send(Network.emulateNetworkConditions, { offline: false, latency: 100, downloadThroughput: 750 * 1024 / 8, // Fast 3G uploadThroughput: 250 * 1024 / 8, }); await page.goto(https://example.com); const metrics await page.metrics(); console.log(Browser Metrics:, metrics); await browser.close(); })();需要注意Network.emulateNetworkConditions的吞吐量单位是字节/秒所以代码里用750 * 1024 / 8把 750 kbps 的 Fast 3G 带宽换算成字节。同理CPU 节流也可以通过 CDP 会话下发Emulation.setCPUThrottlingRate如rate: 4模拟 4 倍慢的 CPU二者叠加才能同时还原弱网 低端设备的真实场景。除了网络节流脚本里还可以读取 Navigation Timing 与 Performance Resource Timing 数据。这一点在本仓库的 E2E 工具链中有直接对应实现apps/e2e/utils/performance.utils.ts 里的PerformanceUtils类封装了measurePageLoad()通过performance.getEntriesByType(navigation)计算 domContentLoaded、loadComplete、domInteractive 等阶段耗时、getResourceMetrics()遍历PerformanceResourceTiming统计资源数量、传输大小与耗时和measureMemoryUsage()读取 Chrome 的usedJSHeapSize等内存指标——这就是在浏览器执行环境中取运行时数据这一思路在工程代码中的落地形态。方案三用 Playwright 构建多浏览器性能回归防线规则文档在工具清单中列出了 Playwright现代浏览器自动化适合编写自定义性能脚本。本仓库正是用 Playwright 搭建了真实浏览器测试基础apps/web/playwright.config.ts 定义了三个浏览器项目chromium、firefox、webkit对应桌面 Chrome / Firefox / Safari并通过webServer配置在测试前自动启动pnpm exec next start --port 3080用真实运行的 Next.js 服务作为被测对象apps/web/e2e/smoke.spec.ts 提供了冒烟测试范例真实打开首页、断言 H1 标题可见、验证/rules与/mcp路由正常渲染——这类真实浏览器里跑页面的用例正是性能审计的前置条件apps/e2e/playwright.config.ts 为跨应用 E2E 提供配置PerformanceUtils的交互耗时判定measureInteraction与TEST_CONFIG.performance.maxInteractionTime阈值比较展示了把性能预算写进测试断言的模式。把三者串起来就得到一条可落地的流水线Playwright 真实启动浏览器 → 访问页面 → 通过page.evaluate取 Navigation Timing / Resource Timing 指标 → 与性能预算阈值比较 → 超限则 CI 失败。最佳实践清单规则文档给出的最佳实践可以直接作为代码评审和 CI 配置的检查项✅在 CI 中自动化在每次 Pull Request 上运行浏览器审计尽早捕获性能回归。 ✅始终节流网络与 CPU 节流是默认动作不能省略。 ✅多地区测试从不同地理位置发起审计理解延迟带来的影响。 ✅移动优先优先使用移动设备模拟进行审计。❌不要只依赖开发机高端开发笔记本无法代表预算型智能手机用户的体验。 ❌避免无节流测试在千兆网络下测试会掩盖大部分性能瓶颈。与之呼应仓库中同一performance/metrics区域还有一批常与browser-required一同评审的关联规则写在 packages/content/rules/en/performance/browser-required.mdx 的relatedRules中字体加载优化font-loading.mdx、JavaScript 重定向js-redirects、旧版 JavaScriptlegacy-js以及动画 GIF 转视频animated-content.mdx。也就是说浏览器审计发现瓶颈后往往需要配合这些规则去修复根因。工具与验证体系规则文档推荐的工具组合各自覆盖不同环节Lighthouse浏览器审计的事实标准给出各指标得分与优化建议WebPageTest深度瀑布图分析 多地理位置测试仓库中 packages/content/rules/en/html/webpagetest.mdx 完整记录了其 API 集成、性能预算插件、GitHub Actions 接入与性能回归检测的代码示例PageSpeed Insights把 Lighthouse 的实验室数据与真实用户现场数据field data结合Playwright用于编写自定义性能脚本的现代浏览器自动化框架。验证方法自动化检查在 Lighthouse、PageSpeed Insights 或 DevTools 中测量受影响页面/流程确认目标指标确实改善检查网络瀑布图waterfall或性能时间线确认预期的资源/执行变更真实生效。手动检查在节流的移动端配置下验证改动而不是只在本地桌面环境验证如果该规则映射到性能预算或 Web Vital 阈值确认页面保持在阈值范围内。标准依据规则的sources字段见 browser-required.mdx给出了两个权威标准以 web.dev 的 Learn Performance 作为衡量最终生产行为而非仅本地合成输出的标准以 Chrome Developers 的 Lighthouse overview 作为同样的生产行为衡量标准。这提示我们在落地时浏览器审计的结论最终要用真实用户环境的生产行为来校准而不是只看本地跑出的合成分数。结合 skills/browser-required/SKILL.md 的定位这条规则的完整闭环是静态分析发现问题线索 → 浏览器环境量化确认瓶颈 → 用 DevTools / Lighthouse / 现场数据核实 → 修复后回归验证。【免费下载链接】Front-End-Checklist The essential checklist for modern web development, for humans and AI agents项目地址: https://gitcode.com/gh_mirrors/fr/Front-End-Checklist创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考