前端性能监控实战：白屏与卡顿指标采集全解析

前端性能优化绕不开两个最直观的体验问题：白屏和卡顿。白屏是用户打开页面那一刻盯着空白等待的焦虑，卡顿是用户滚动、点击时页面半天不给反应的烦躁。这两类问题的根因往往藏在浏览器加载链路和主线程执行过程中，而抓根因的第一步就是先得出准确、可量化的采集数据。这篇内容不是泛泛讲性能优化方法论，而是聚焦如何采集白屏、卡顿指标，并把网络环境一并纳入上报体系，让后续的数据分析有图可查、有据可依。适合刚接手性能监控系统、想在自己项目中搭建一套基础采集SDK的前端开发者，也适合正在排查线上“有人反馈白屏、有人反馈卡顿”但拿不到有效数据的情况。

1. 先搞清楚：我们到底在采集什么？

性能采集最忌讳一上来就写代码。如果指标定义不统一，后面分析数据时很容易各说各话。先说清楚白屏和卡顿在技术上的边界，才能确定采样对象。

1.1 白屏时间不是“网速快慢”那么简单

白屏时间在行业内没有绝对统一的定义。我习惯把它拆成两个阶段来看：第一个阶段是网络请求耗时，第二个阶段是浏览器从收到HTML到渲染出可视内容的时间。很多文章把TTFB（首字节时间）直接当成白屏，这是不准确的。TTFB只代表服务器响应到达浏览器的第一个字节，此时用户看到的仍然是一片空白。白屏真正结束的标志，是页面有第一个可视内容被绘制出来，可以是背景色、文字、图片或UI框架的某个节点。

所以采集白屏时间，核心起点是“页面开始加载”那一刻，终点是“首屏出现第一个有效像素”那一刻。这个终点的检测，业内常用两种方式。第一种是PerformancePaintTiming，通过performance.getEntriesByType('paint')拿到first-paint或first-contentful-paint，这个方案的优势是有浏览器底层实现，性能开销极小。第二种是用MutationObserver监听根DOM节点的变化，一旦发现页面容器内渲染出内容，就记录时间差。第二种方案更适合SPA场景，因为SPA路由切换时会重新渲染，但要注意它容易被异步组件、字体加载、骨架屏干扰，需要做容错。

另外要分清白屏和首屏时间。首屏时间通常需要额外监听首屏区域内的图片、关键资源全部完成加载，而白屏只关心第一个可视节点出现。很多监控平台会把FCP（First Contentful Paint）作为白屏的近似指标，但在实际项目中FCP和用户感知的“白屏结束”有时能差几百毫秒。比如一个页面首屏只有一张大图，FCP可能在图片的alt文本或占位背景渲染时就触发了，但真正的视觉白屏还没结束。因此，采集时除了收FCP，还要额外记录LCP（Largest Contentful Paint）和自定义的首屏可见时间，两个数据放一起才能交叉判断。

1.2 卡顿指标：帧率、长任务、主线程忙

卡顿的本质是浏览器主线程被长任务阻塞，导致浏览器无法及时响应输入事件、样式计算、渲染绘制。用户感官上的“卡”，在数据上通常表现为三种形态：单次长任务超过50ms、连续掉帧、主线程长时间占据高利用率。

最早大家喜欢用FPS（每秒帧数）来衡量流畅度，比如60fps为流畅，低于30fps为明显卡顿。但FPS有个天然缺陷：浏览器运行时帧率本就不是固定值，页面静止时可能完全不绘制新帧，此时FPS为0，并不代表页面卡死。所以单纯统计FPS会误判。更可靠的方案是用Long Task API，PerformanceObserver直接监听longtask条目，任何超过50ms的任务都会生成一条上报记录，附带任务开始时间、执行时长，以及是否因为用户交互引起的延迟。50ms这个阈值来自W3C的Long Tasks规范，它对应的是人对“即时响应”的感知极限，低于50ms的操作用户基本无感知，高于50ms就会觉得“卡了一下”。

FPS和长任务不是互斥关系，两者要结合看。我自己的实践是：用FPS统计来定位“掉帧段”，用Long Task来定位造成掉帧的具体任务。比如实时采集每个动画时间段内的最早帧和最新帧，算出一个区间内的FPS分布，再结合长任务的时间轴，就能看到哪段时间主线程被什么任务霸占，从而定位到具体脚本或渲染操作。另一个更宏观的指标是主线程忙碌率，用长任务总耗时除以页面总活跃时间，能反映页面整体的负载水平。这个适合做版本间的横向对比，比如新功能上线后如果忙碌率从15%涨到30%，就要警惕。

2. 指标采集的具体实现

定义清楚了，接下来就是落地的采集代码。这部分我会直接给出可抄的代码示例，并解释每个关键点背后的考虑。

2.1 白屏时间：从PerformancePaint到MutationObserver

采集FCP这类浏览器标准指标，优先用PerformanceObserver，因为它能在性能事件发生时主动回调，无需轮询performance缓冲区。以下是一段直接可用的代码：

function observePaintMetrics() { const entries = {}; if (typeof PerformanceObserver !== 'undefined') { try { const observer = new PerformanceObserver((list) => { list.getEntries().forEach((entry) => { if (entry.entryType === 'paint') { entries[entry.name] = Math.round(entry.startTime); } }); }); observer.observe({ entryTypes: ['paint'] }); } catch (e) { // 某些环境下PerformanceObserver可能受限，降级处理 } } return entries; }

注意这里的startTime是相对于导航开始的时间，所以上报时不需要再额外记录一个“页面开始时间”，直接取这个值即可。需要特别强调的是，如果页面使用了跨域iframe或者部分受限环境，PerformanceObserver可能不会触发，因此要写降级方案。降级方案是主动查询performance.getEntriesByType('paint')，但这个方法只能在页面已经完全加载后才可用，且拿不到实时的回调时机。实际项目里可以两者共用，observer为主，辅助轮询作为兜底。

对于SPA场景，我建议额外写一个MutationObserver监听根节点内容出现，用来辅助确认用户实际看到的首屏节点时间。核心思路是：页面容器默认是空的或有骨架屏，当容器内第一次出现“非骨架屏、非占位符”的真实业务节点时记录时间。但要注意，不要监听整个body，要指定业务容器，否则脚本往body里插个统计脚本标签也会触发误判。实现大致如下：

function observeFirstContent(containerSelector, threshold = 3000) { return new Promise((resolve) => { const container = document.querySelector(containerSelector); if (!container || container.children.length > 0) { resolve(performance.now()); return; } const observedTime = performance.now(); const observer = new MutationObserver((mutations) => { for (const mutation of mutations) { if (mutation.addedNodes && mutation.addedNodes.length > 0) { // 过滤：只当子节点是真实元素且包含有效高度或文本时才算渲染 observer.disconnect(); resolve(performance.now() - observedTime); } } }); observer.observe(container, { childList: true, subtree: true }); setTimeout(() => { observer.disconnect(); resolve(-1); // 超时未渲染，标记为异常 }, threshold); }); }

这个方案如果在线上环境里跑，要把超时时间设得别太短，否则弱网下页面首屏一大块内容加载超过3秒就会误报成白屏失效。我习惯设5秒，超时返回-1并在上报阶段单独归到“超时白屏”分类，和“正常白屏”分开看。

2.2 卡顿采集：LongTask和FPS的配合

Long Task的采集同样基于PerformanceObserver，但和paint不同，性能异常用户在Safari等浏览器上的支持度一般，所以采集代码必须做特性检测，并预留降级方案。

function observeLongTasks() { if (typeof PerformanceObserver === 'undefined') { return null; } try { const observer = new PerformanceObserver((list) => { list.getEntries().forEach((entry) => { const longTask = { start: Math.round(entry.startTime), duration: Math.round(entry.duration), attribution: entry.attribution || [], }; // 统一扔到采集队列里，后续统一上报 pushToQueue('longtask', longTask); }); }); observer.observe({ entryTypes: ['longtask'] }); return observer; } catch (e) { // 不支持或不安全环境下静默失败 return null; } }

这里有个容易被忽视的点：Long Task是阻塞主线程的任务，如果在任务本身执行过程中做“实时上报”，会进一步拖慢主线程。所以采集端只能把数据推入一个内存队列，等浏览器空闲或页面卸载时再发送。千万不要在observer回调里写fetch或执行重数据处理。

FPS的计算用requestAnimationFrame来近似。rAF的执行频率和页面刷新率一致，每次回调之间相隔约16.7ms（60Hz屏幕），如果两次回调间隔超过了某个阈值，就说明中间插入了长任务或者掉帧。具体实现是记录上一次rAF的时间戳，每次新回调算时间差，再根据差值判断掉帧数。

let lastTime = performance.now(); let frameCount = 0; let droppedFrames = 0; function monitorFPS() { function checkFrame(now) { const diff = now - lastTime; lastTime = now; const expectedInterval = 1000 / 60; if (diff > expectedInterval * 1.5) { // 掉帧，大约掉了 Math.round(diff / expectedInterval) - 1 帧 droppedFrames += Math.max(1, Math.round(diff / expectedInterval) - 1); } frameCount++; requestAnimationFrame(checkFrame); } requestAnimationFrame(checkFrame); }

实际项目中不需要一帧不漏地统计，我一般只统计10秒为一个区间，每10秒计算一次区间内的平均FPS、掉帧次数，并推入采集队列。这样既能缩小数据精度聚焦到卡顿区域，又能避免频繁上报消耗流量。这里有个经验：FPS采集在手机浏览器后台运行时会自动暂停rAF，所以不要依赖它做全局统计，把它作为长任务数据的时间定位辅助即可。

2.3 指标上报的时机与采样策略

数据采得再全，如果一股脑全量上报，生产环境的数据量会迅速膨胀，反而影响服务器和网络。必须做采样和上报合并。

采样策略最简单的做法是用户维度采样，用稳定的哈希函数对用户ID取模，落到指定比例内才上报。为什么要做用户维度而不是页面维度？因为页面维度采样会导致同一个用户前后几次访问有的上报、有的不上报，数据碎片化，无法跟踪单个用户连续会话的性能表现。用户维度采样能保证同一个用户的会话记录完整连续。

function shouldSample(userId, rate = 0.1) { // 简单取模，rate是采样率 let hash = 0; for (let i = 0; i < userId.length; i++) { hash = ((hash << 5) - hash) + userId.charCodeAt(i); hash |= 0; } return Math.abs(hash % 100) < rate * 100; }

上报时机分成两类：页面卸载时的关键指标（白屏、首屏、长任务总和）用sendBeacon发送，因为它在页面关闭时仍能尽量保证送达；会话内的持续指标（FPS、新增长任务）则采用定时合并上报，比如每30秒把队列中的多条指标合并成一个包发送，减少请求数。我这里有一个简单的队列合并逻辑，把所有采集指标先推入数组，由flushToServer统一发送：

const metricsQueue = []; function pushToQueue(category, data) { metricsQueue.push({ category, ...data, timestamp: Date.now(), page: location.href.split('?')[0], ua: navigator.userAgent, }); } function flushMetrics() { if (metricsQueue.length === 0) return; const data = metricsQueue.splice(0, metricsQueue.length); if (navigator.sendBeacon) { navigator.sendBeacon('/collect/beacon', new Blob([JSON.stringify(data)], { type: 'application/json' })); } else { const img = new Image(); img.src = `/collect/gif?data=${encodeURIComponent(JSON.stringify(data))}`; } } // 每30秒刷一次 setInterval(flushMetrics, 30000); window.addEventListener('pagehide', flushMetrics);

3. 网络环境采集：看清用户所处的“赛道”

白屏和卡顿的数值，离开了网络环境就是盲人摸象。同样是白屏3秒，在4G网络下可能是页面代码问题，在2G网络下可能就是物理带宽限制。网络环境采集就是要给每个性能指标打上“网络标签”，方便后续按网络维度分层分析。

3.1 Network Information API：拿到连接类型和有效带宽

浏览器提供了navigator.connection接口，能拿连接类型、有效带宽、RTT等关键信息。其中最常用的字段是effectiveType，它直接返回slow-2g、2g、3g、4g这几个档位，用来粗略区分用户网络质量。它不精确，但胜在不需要额外探测，而且各主流浏览器（Safari除外）基本都支持。以下是采集代码：

function getNetworkInfo() { const conn = navigator.connection || navigator.mozConnection || navigator.webkitConnection; if (!conn) { return { supported: false }; } return { supported: true, effectiveType: conn.effectiveType || '', downlink: conn.downlink || 0, // 单位 Mbps rtt: conn.rtt || 0, // 单位 ms saveData: conn.saveData || false, // 是否开启省流量模式 }; }

downlink和rtt是实时估算值，会随时变化。如果只在页面加载时采集一次，网络质量变化后就失真了。所以我的做法是：在每个页面会话内至少采集三次——首屏加载后、页面稳定时、pagehide时，取中位数作为该会话的网络环境值。这样才能反映页面使用期间的真实网络波动，尤其是对视频加载、图片大量加载的页面很有意义。

兼容性上的坑要提前讲清楚。Safari在很长一段时间不支持Network Information API，这时navigator.connection是undefined。降级方案很有限，常规做法是用performance.getEntriesByType('resource')里的资源加载耗时间接估算网络质量，但准确度较低。另一种做法是让后端在页面请求的响应头里附加CDN节点信息和首包时间，用服务端视角补偿浏览器API缺失的情况。

3.2 Navigation Timing：拆解请求全链路耗时

网络环境是单一标签，全链路耗时才能解释为什么慢。Navigation Timing API会记录一次导航从开始到结束的各个关键时间点，通过它可以把加载过程拆成DNS查询、TCP连接、TLS握手、TTFB、HTML解析、资源加载等多个阶段。最关键的几个字段和计算方式如下：

采集Navigation Timing的最佳时机是页面load事件之后，因为需要等loadEventEnd确定。但项目里如果要最晚也能拿到loadEventEnd，可以在pagehide时读取。实测中要注意一点：跨域\资源加载会让navigation timing里的某些字段变为0，通常指domainLookupEnd等DNS字段在HTTP/2、DNS预解析开启时可能直接等于0，因为浏览器复用了连接的缓存解析结果。遇到这种情况不用慌，直接在上报中标记为0并在分析时跳过，不要用0去计算平均值，不然会把数据拉低。

还有一点是SPA场景下的Navigation Timing只能反映首次加载，路由切换后的白屏和卡顿不在它覆盖范围内。因此，网络链路分析主要用于首屏加载类问题，SPA内路由切换的性能要靠Long Task和自定义渲染事件来补全。

3.3 网络环境与指标的关联分析

采集到网络环境和性能指标后，最大的价值是在分析端交叉对比。我实际用过的场景有三个。

第一个场景是区分“真卡顿”和“网络慢导致的伪卡顿”。有些页面在网络环境为4G时也不流畅，但用户反馈都是“卡”，看数据才发现是事件处理函数里跑了复杂同步计算。这时Long Task不多，但FPS掉帧严重，网络环境指标都很好，问题定位到主线程执行。第二个场景是优化降级策略。如果采集结果显示大量effectiveType为2g的用户白屏时间超过6秒，说明首屏资源对弱网用户太重，服务端应针对这些用户下发无图版或简化版页面。这时候网络环境和白屏指标的联合查询就是决策依据。第三个场景是CDN节点和网络时区的标签关系。通过耗时拆解发现某个地理区域的用户TTFB偏高，看网络环境rtt却不高，那问题可能出在服务端处理或CDN缓存命中率上。

为了让联合分析跑得顺，数据上报时务必把网络环境字段和性能指标放在同一个JSON对象里，而不是分开上报后再join。分开上报在网络不好时会出现指标丢了、网络标签没到的情况，导致无法关联。

4. 从采集到落地：一个完整的上报方案

原理和零散采集代码都有了，现在把它们串成一个可以直接放进项目的完整方案。

4.1 上报数据结构与字段设计

上报JSON设计很重要，字段太细会产生大量冗余，字段太少分析时又要翻原始日志。我推荐一份性能数据包的通用结构：

{ "appId": "demo_web", "pageUrl": "https://example.com/list?id=123", "userId": "uid_7890", "ts": 1734567891234, "net": { "effectiveType": "4g", "downlink": 8.2, "rtt": 42, "saveData": false }, "paint": { "fp": 1204, "fcp": 1350, "lcp": 2100, "customFirstContent": 1420 }, "longTasks": [ { "start": 1800, "duration": 260, "attribution": ["script"] } ], "fps": { "avg": 55, "dropped": 3, "interval": 10000 }, "navTiming": { "dns": 12, "tcp": 40, "ttfb": 420, "htmlDownload": 180, "domInteractive": 950 } }

字段命名不用纠结，团队统一就行。真正重要的是以下几点：pageUrl要去掉query里的动态参数，否则像带sort参数的列表页会产生海量冗余页面维度；userId做hash脱敏后上报，不要直接传明文ID，防数据泄露；每个指标都带ts时间戳，方便后按时间切片。还有一个容易漏的clientVersion字段，前端代码版本变了，而性能采集逻辑也可能变化，没有版本字段时新旧上线代码的数据混在一起会把分析搞得一团糟。

4.2 使用sendBeacon和图片请求的取舍

上报通道的选择我上面提到过，这里展开说一下取舍。navigator.sendBeacon适合在页面卸载、跳转、关闭时可靠上报，它的特点是浏览器会确保数据在页面销毁前发出，并且不阻塞页面卸载流程。但sendBeacon有两个限制：数据量一般建议在64KB以内，且部分浏览器不支持自定义请求头，所以服务端可能需要兼容Content-Type为application/json或text/plain的POST。

备用方案是1x1 GIF图片请求，把数据拼在URL query里。它的优点是全兼容、无跨域限制，缺点是数据只能GET传参，有长度限制，且服务端需要额外解析一条图片请求。如果页面有大量数据上报，图片请求在弱网下会阻塞加载，所以我在生产环境是双层策略：小包高频数据用图片GET发送，大包低频数据用sendBeacon发送。还有一个很多团队踩过的坑：用fetch在unload事件里上报几乎百分百丢失，就算加了keepalive也可能因浏览器处理顺序问题失败，不要在这条路上浪费时间。

4.3 抽样率配置和灰度发布

采样率的设置没有标准答案，取决于数据量瓶颈和业务重要性。一般全局业务可以先用5%的采样率跑两周，看单日数据量是否在服务端可承受范围内，再逐步放开。重要功能页可以单独提高到20%或50%，比如支付流程页、核心交易页。实现上建议做一个可远程配置的开关，把采样率放到服务端配置中心或CDN静态JSON里，前端启动时拉取一次。这样想临时调整某条链路的采样比例，不用发版。

灰度发布上还有一个经验：新上的采集SDK先在一个小流量分组上线，对采集自身造成的性能开销进行验证。我之前见过一个团队上了采集SDK后页面多了100ms延迟，原因是SDK里做了很多同步字符串拼接和频繁的DOM查询。要避免这个问题，采集逻辑全部用异步队列处理，不使用同步eval，不主动触碰DOM，至少要保证SDK在页面全流程中不产生长任务。如果加了采集后Long Task数量明显上升，说明采集代码本身就是污染源，必须优化。

4.4 异常兜底与幂等上报

上报链路网络丢包、服务端偶发超时导致的数据丢失是无解的，我们能做的是防重复、防错乱。防重复上，每条上报记录都带一个eventId，由前端生成递增ID，服务端记录最近一批已处理ID，重复的直接忽略。防错乱上，如果一次上报的数据包太大，服务端需要限制单包大小，否则会触发网关限制导致整包丢失，前端也要在拼接队列时控制单批次不超过最大条数，拆包发送。

另外要特别处理异常值。白屏时间可能出现负数或超出预期的大数，比如时间戳计算错误、系统时间被用户调整，这类数据属于坏数据。采集端要做一次基础合法性过滤，比如所有耗时必须在0到10分钟之间，负数直接丢弃，超过10分钟打上异常标签后再上报。过滤逻辑一定放在队列推入前，不然坏数据会污染统计均值和分位数。

5. 实测中踩过的坑与排查表

这部分都是实际项目中踩过的坑，列出来供大家少走弯路。

5.1 三大坑：白屏异步不准确、FCP误判、LongTask兼容性

第一个坑是我前面提到的MutationObserver误判。页面首屏组件是异步加载的，容器里一开始会出现一个占位符或loading图标，如果监控到占位符就上报白屏结束，数据会偏小得离谱。解决方式是白名单过滤，比如选择器匹配、文本内容判断、元素尺寸判断。只有当新增节点的样式高度超过首屏可视区域的一定比例（比如30%）且不是骨架屏时，才认为白屏结束。骨架屏的检测需要结合业务具体的类名，在不侵入业务的前提下用通用规则：骨架屏元素通常没有文本、背景是灰色、宽高百分比固定，但通用规则总会误伤，所以最稳的方案还是前端业务方在关键容器挂一个>