Lighthouse Viewer 深度指南本地构建、发布部署与查询参数驱动的报告加载机制【免费下载链接】lighthouseAutomated auditing, performance metrics, and best practices for the web.项目地址: https://gitcode.com/GitHub_Trending/lig/lighthouse本篇技术指南以 viewer/README.md 为骨架系统讲解 Lighthouse 生态中的Lighthouse Report ViewerLighthouse 报告在线查看器如何在本地 checkout 中完成构建与调试如何通过gist、jsonurl、psiurl三类深链参数一键加载报告以及category、strategy、locale、utm_source等可选参数的作用。同时结合viewer/app/src/下的源码实现与 viewer/test/viewer-test-pptr.js 测试用例剖析报告加载、GitHub Gist 读写、PSI 数据拉取与本地化切换的底层调用链帮助开发者完成从会用到能改、能测、能发布的进阶。项目定位一份 LHR JSON 的通用查看终端Lighthouse 在每次运行后产出一份 JSON 格式的 Lighthouse ReportLHR即LH.Result而Lighthouse Viewer是一个纯前端的报告查看器把 LHR JSON或 Flow 用户流报告LH.FlowResult渲染成带评分、图表、审计明细的交互式 HTML 报告页面。Viewer 的典型应用场景包括把lighthouse --outputjson生成的报告文件拖入页面直接可视化将报告上传为 GitHub Gist 后通过?gist分享给他人通过?psiurl直接对线上 URL 实时跑一次 PageSpeed Insights 审计并渲染结果作为其他工具扩展、CI 产物、报告 Diff 工具的打开报告落地页。在仓库中Viewer 位于 viewer/ 目录其核心渲染能力复用自 report/renderer/report-renderer.js单次报告与 flow-report/api.ts用户流报告自身只负责把 JSON 弄进来以及把渲染结果接出去。本地开发与构建按 viewer/README.md 的 Development 章节在 Lighthouse checkout 的根目录依次执行yarn yarn build-viewer yarn serve-gh-pages open http://localhost:7333/viewer/说明yarn安装仓库全部依赖Viewer 使用 ES Module 与 esbuild 打包依赖在根目录package.json中统一管理。yarn build-viewer编译并压缩入口 viewer/app/src/main.js产物写入dist/gh-pages/viewer/。构建脚本定义于根目录 package.jsonbuild-viewer: node ./build/build-viewer.js。yarn serve-gh-pages启动静态服务器serve-gh-pages: cd dist/gh-pages python3 -m http.server 7333即用 Python 内置 HTTP 服务在7333端口托管构建产物模拟 GitHub Pages 的目录结构。打开http://localhost:7333/viewer/即为本地 Viewer 页面。构建产物目录刻意命名为dist/gh-pages/viewer/与线上gh-pages分支下viewer/目录一一对应——这样本地预览路径与最终部署路径完全一致避免深链参数、静态资源相对路径在部署后失效。部署到 gh-pages 分支按 README 的 Deploy 章节Viewer 的部署作为Lighthouse 发版流程的一部分完成在 checkout 根目录执行yarn deploy-viewer该命令deploy-viewer: yarn build-viewer --deploy会在构建后把产物推送到gh-pages分支的viewer/目录下。完整的发版流程细节参见仓库根目录的发布指南 docs/releasing.mdREADME 中引用的releasing.md即此文件其中说明了发版节奏、版本号语义与发布步骤。三种深链参数gist / jsonurl / psiurlViewer 支持通过 URL 查询参数直接加载报告入口逻辑在 viewer/app/src/lighthouse-report-viewer.js 的_loadFromDeepLink()方法中页面初始化时解析location.search按优先级依次处理gist、psiurl、jsonurl。从 Gist 加载把 GitHub Gist 的 ID 作为gist查询参数传入http://localhost:7333/viewer/?gistbd1779783a5bbcb348564a58f80f7099底层由 viewer/app/src/github-api.js 的getGistFileContentAsJson(id)完成调用https://api.github.com/gists/{id}优先选取文件名以.lighthouse.report.json结尾的文件否则回退到任意.json文件解析后交给渲染层。该实现还内置了两层优化ETag 缓存每次请求把上次响应头中的ETag通过If-None-Match带回命中304时直接使用 IndexedDBidb-keyval中的缓存副本速率限制告警当X-RateLimit-Remaining低于 10 时向用户提示接近 GitHub API 速率上限并建议登录以提升限额。加载成功后 URL 会通过history.pushState改写为?gistid方便直接复制分享。从任意 URL 加载 JSON把 LHR JSON 文件的绝对地址作为jsonurl传入http://localhost:7333/viewer/?jsonurlhttps://gist.githubusercontent.com/Kikobeats/d570a1aa285c5d1d97bbda10b92fb97f/raw/4b0f14a5914edd25c95b4bd9d09728ab42181c3e/lighthouse.json实现上jsonurl分支会先通过 Firebase Auth 检查当前是否已登录 GitHub已登录时拒绝加载避免带鉴权头跨域请求引发问题未登录则直接fetch(jsonurl)并解析 JSON。从源码看这是一个安全约束未登录状态下没有 GitHub token 会被附加到请求上。运行并加载 PageSpeed Insights 结果传入目标 URL 作为psiurlViewer 会实时调用 PSI API 生成报告再渲染http://localhost:7333/viewer/?psiurlhttps://www.example.comcategoryseo请求由 viewer/app/src/psi-api.js 的fetchPSI()构造指向https://www.googleapis.com/pagespeedonline/v5/runPagespeed。其默认行为有源码与测试双重印证默认类别未显式传category时请求performance、accessibility、seo、best-practices、agentic-browsing五个类别PSI_DEFAULT_CATEGORIES见 viewer/app/src/psi-api.js 第 11–17 行默认策略strategy为空时兜底为mobile每个类别以独立的category参数重复追加测试注释特别强调传给 PSI 的参数顺序很重要请求附带referer: googlechrome.github.io头。附加查询参数详解README 列出的四个可选参数在_loadFromDeepLink()中透传给 PSI 请求viewer/app/src/lighthouse-report-viewer.js 第 121–128 行参数含义取值/默认category启用哪个类别每次只能传一个类别performance、accessibility、seo、best-practices、agentic-browsing可重复出现多次以请求多个类别缺省时使用上述五个默认类别strategy运行策略mobile默认、desktoplocale渲染报告使用的语言区域任意受支持 locale如es、zh缺省为报告原始 locale通常en-USutm_source标识哪个工具在使用 Viewer的 ID自定义字符串仅用于流量归因统计其中locale的处理并不只作用于 PSI 请求参数报告渲染完成后viewer/app/src/viewer-ui-features.js 会通过懒加载shared/localization/i18n-module.js约 30KB仅在需要时拉取在页面右上角提供语言选择器可对已渲染的报告进行运行时本地化切换swapLocale切换后整体重新渲染。除深链外的四种交互式加载方式即便不依赖任何查询参数打开 Viewer 页面也有多种加载途径交互入口定义在 viewer/app/index.html 的占位区.viewer-placeholder拖拽文件把.json报告拖入页面由 viewer/app/src/drag-and-drop.js 监听dragenter/dragover/drop事件用FileReader.readAsText读取第一个文件点击选择文件点击select a file按钮触发隐藏的input idhidden-file-input typefile acceptapplication/json粘贴在页面任意位置粘贴 Gist 链接https://gist.github.com/...通过正则/[a-f0-9]{5,}/提取 ID或直接粘贴 JSON 文本见 viewer/app/src/lighthouse-report-viewer.js 的_onPaste()输入 Gist URL在.js-gist-url输入框中填写 Gist 地址。报告渲染的底层流程与兼容性处理无论是深链加载还是文件上传最终都汇聚到 viewer/app/src/lighthouse-report-viewer.js 的_replaceReportHtml(json)其处理链条如下格式归一化兼容三类输入——{lhr: ...}runner 结果、{lighthouseResult: ...}PSI 响应、原生 LHR通过steps in json判断是否为 Flow 报告并分流到renderFlowReport来自 flow-report/api.ts或ReportRenderer.renderReport来自 report/renderer/report-renderer.js版本校验_validateReportJson()要求 JSON 必须含lighthouseVersion字段否则报不是 Lighthouse 生成的 JSON当报告主/次版本低于当前 Viewer 版本时给出警告Results may not display properlyv2 旧报告重定向lighthouseVersion以2开头时把报告写入 IndexedDB 后跳转到旧版 Viewer../viewer2x/渲染调试便利渲染后把 LHR 挂到window.__LIGHTHOUSE_JSON__Flow 报告挂window.__LIGHTHOUSE_FLOW_JSON__便于控制台调试深链清理非 Gist/PSI/URL 来源加载时通过history.pushState清空查询串避免误刷新重新加载。入口 viewer/app/src/main.js 还负责日志系统div#lh-log与Logger实现见 report/renderer/logger.js以及lh-log、lh-analytics两个自定义事件的转发后者在存在gtag时上报统计。Gist 保存与 GitHub 登录Viewer 支持把当前报告一键保存为 Gist 以便分享。保存逻辑在 viewer/app/src/github-api.js 的createGist()文件名由 report/generator/file-namer.js 生成基于finalDisplayedUrl与fetchTime追加.lighthouse.report.json后缀以POST https://api.github.com/gists创建私有 Gist需要 GitHub OAuth token认证由 viewer/app/src/firebase-auth.js 完成通过 FirebasesignInWithPopupGithubAuthProviderscope 为gist弹出 GitHub 授权并把 token 存入 IndexedDBGitHub token 永不过期刷新页面后仍可复用保存成功后页面 URL 被改写为?gistid可复制分享。在 viewer/app/src/viewer-ui-features.js 中Save as Gist菜单项在保存成功后才被禁用且当报告本身来自 Gist 时不会提供重复保存入口。测试验证Viewer 的关键行为都有 Puppeteer 覆盖viewer/test/viewer-test-pptr.js 启动本地静态服务器端口 10200与 Puppeteer对 Viewer 做了端到端验证覆盖以下能力可作为理解与二次开发的参考Flow 报告渲染上传sample-flow-result.json后应出现.App容器与包含 14 个评分的 Summary 页单次报告渲染上传 core/test/results/sample_v2.json 后断言所有类别、全部审计项、胶片帧.lh-filmstrip均正确渲染且无 Audit error旧版本报告兼容逐一加载report/test-assets/下从lhr-3.0.0.json到lhr-11.7.0.json的历史报告验证零报错渲染本地化切换默认en-US切换到es后界面文案变为 Copiar JSON保存 HTML通过 CDP 监听下载事件验证 Save as HTML 可生成独立报告页PSI 集成拦截请求验证默认类别顺序、strategymobile兜底、自定义category/locale/utm_source透传以及 API 报错时的日志提示如badPsiResponse error。快速自查清单本地调试yarn→yarn build-viewer→yarn serve-gh-pages→http://localhost:7333/viewer/分享报告Viewer 内保存为 Gist 后用?gistid深链分发实时审计?psiurl目标URLcategoryperformancestrategydesktoplocalezh部署上线随 Lighthouse 发版执行yarn deploy-viewer产物推至gh-pages分支viewer/目录完整流程参见 docs/releasing.md。至此从本地构建、参数化加载到源码原理与测试验证Lighthouse Viewer 的完整工作链路已全部打通。【免费下载链接】lighthouseAutomated auditing, performance metrics, and best practices for the web.项目地址: https://gitcode.com/GitHub_Trending/lig/lighthouse创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考