经常听到前端同学抱怨：
- 面试聊到性能优化，FCP/LCP/CLS 这些名词都能说；但如果让“先不依赖第三方库，设计一个监控 SDK”，一时间真不知如何下手。
- 老板说页面慢，我们把图片压了、代码拆了；他追问“到底快了多少秒？”——手里没一套可对齐的数据。
- 本地跑得飞快，上线后却被用户说卡顿，现场复现不了，这种“抓不住问题”的感觉挺挠头。
不卖关子： Google 官方推出的 web-vitals 库本身很棒，能一键采集 Core Web Vitals（核心 Web 指标）。但本文想带你跳出“调包侠”的舒适区，把控制权拿在自己手里：
-
要归因：指标异常时，不光要分数，还要知道是哪个 DOM 元素慢、哪段脚本卡。
-
要适配：在 SPA（单页应用）路由切换时，能灵活地分段统计与结算。
-
要透明：从零使用
PerformanceObserver，把“黑盒”变成“白盒”。
接下来，我们将手把手打造一个小而透明的性能监控 SDK，一起把“凭感觉优化”升级成“有数据、有依据的优化”。
指标扫盲：别被指标缩写吓跑了
别被那一堆性能指标缩写整蒙了。对于前端来说，核心就关注三件事：快不快（Loading）、卡不卡（Interaction）、稳不稳（Visual Stability）。
1. Loading (加载)：别让我等太久！
用户最怕面对一片白屏。这个阶段我们关注三个瞬间：
| 指标 |
全称 |
人话解释 |
典型场景 |
及格线 |
| FP |
First Paint (首次绘制) |
屏幕亮了 浏览器开始渲染任何东西的时刻（哪怕只是背景色）。 |
屏幕从纯白变成浅灰色，虽然啥内容都没有，但你知道“它活着”。 |
- |
| FCP |
First Contentful Paint (首次内容绘制) |
看到内容了 浏览器渲染出第一个内容（文字、图片、Logo）的时刻 |
页面上终于蹦出了“Loading...”文字或者导航栏 Logo。 |
< 1.8s |
| LCP |
Largest Contentful Paint (最大内容绘制) |
主角登场 视口内可见的最大图片或文本块渲染完成的时刻。这是 Google 最看重的加载指标 |
淘宝详情页的大图终于刷出来了，你终于看清商品长啥样了。 |
< 2.5s |
2. Interaction (交互)：别卡得像 PPT！
东西加载出来了，用户开始点了，这时候最怕卡顿。
| 指标 |
全称 |
人话解释 |
典型场景 |
及格线 |
| FID |
First Input Delay (首次输入延迟) |
第一下没反应？ 用户第一次与页面交互（点击按钮、链接）到浏览器真正开始处理这个事件的时间差 |
兴奋地去点“登录”按钮，结果点了没反应，过了 1 秒钟按钮才变色。 |
< 100ms |
| INP |
Interaction to Next Paint (下次绘制交互) |
越用越卡？ FID 的升级版。它不仅看第一下，还看你浏览全程中所有交互的延迟，取最慢的那几次 |
每输入一个字，输入框都要卡顿一下才能显示出来，有种“粘滞感”。 |
< 200ms |
| Long Task |
Long Task (长任务) |
谁在堵路？ 任何执行时间超过 50ms 的 JavaScript 任务 |
主线程就像单行道，大卡车（复杂计算）一堵，后面的点击事件全得排队。 |
< 50ms |
注：长任务不光交互期会出现，加载时也常见；它会让白屏更久、把 TBT（总阻塞时间）拉高。我们归到“交互”里讲，是因为它最直接拖慢的是点击/输入的响应（FID、INP）。
3. Visual Stability (视觉稳定性)：别乱动！
这可能是最让人抓狂的体验。
| 指标 |
全称 |
人话解释 |
典型场景 |
及格线 |
| CLS |
Cumulative Layout Shift (累积布局偏移) |
页面布局在加载过程中发生意外移动的程度 |
你正准备点“取消订单”，顶部广告突然插队把页面往下挤，害你点成了“支付”。这种布局的意外位移，就叫 CLS。分数越低，页面越稳 |
< 0.1 |
读完这篇，你将收获什么？
手写 SDK 不只是为了“造轮子”，更是为了把黑盒变成白盒。你将深入掌握：
-
底层 API 实战：拒绝盲猜！从零使用
PerformanceObserver、Resource Timing 等原生 API，彻底搞懂数据从哪来。
-
全链路指标体系：覆盖 Loading (FCP/LCP)、Interaction (FID/INP/Long Task)、Visual Stability (CLS) 及网络耗时，给应用做一次全身体检。
-
插件化架构设计：学习如何解耦 采集、处理、上报、配置 四大模块，打造一个高扩展、易维护的工程化 SDK。
-
关键路径归因：不仅要监控“慢”，更要定位“为什么慢”。通过元素选择器与长任务归因，直击性能瓶颈。
系统架构与功能设计
为了保证 SDK 的轻量性与可扩展性，我们采用了分层架构设计。整个系统由 核心采集层、数据处理层、数据上报层 和 配置中心 四大模块组成。
简单说，就是把活儿分得明明白白：采集模块只管抓数据，处理模块只管处理数据，上报只管发送数据到服务端，配置只管配置
架构要点：
-
采集层：Loading / Interaction / VisualStability / Network（各司其职）
-
处理层：数据清洗、格式化、核心指标归因（找到卡顿的 DOM 或脚本）
-
上报层：支持
sendBeacon + fetch keepalive 双保险，确保数据不丢失
-
配置中心：环境区分、采样率控制、日志开关
1. 核心采集层 (Collectors) —— 用户体验四步走
这是 SDK 的心脏。咱们不按技术分类，按用户实际感受来分，对应源码的四个核心目录：
-
Step 1: Loading (看得见吗？) —— src/loading
-
核心目标：紧盯白屏时间与关键内容渲染。
-
实现手段：利用
Paint Timing 与 Largest Contentful Paint API，捕获 FP、FCP、LCP 及页面加载完成时机。
-
Step 2: Interaction (好用吗？) —— src/interaction
-
核心目标：监控用户交互的响应速度与流畅度。
-
实现手段：通过
Event Timing 监听点击延迟（FID/INP），并用 Long Task API 揪出导致主线程阻塞的元凶。
-
Step 3: Visual Stability (稳不稳？) —— src/visualStability
-
核心目标：防止页面布局“乱动”，提升视觉舒适度。
-
实现手段：结合
Layout Shift API 计算布局偏移（CLS），并针对 SPA 应用做特殊的会话窗口计算。
-
Step 4: Network (为啥慢？) —— src/network
-
核心目标：定位资源加载与接口响应的瓶颈。
-
实现手段：复用
Resource Timing 接口，深度解析静态资源与 XHR/Fetch 请求的 DNS、TCP、TTFB 等关键耗时。
2. 数据处理层 (Processor) —— 数据清洗工
-
洗数据：浏览器原生的 API 给的数据太杂太乱，咱们得把它洗成干净统一的 JSON 格式，方便后端存。
-
加料：光知道卡了没用，还得知道哪儿卡了。比如 LCP 慢，我们会自动把那个慢元素的 DOM 选择器加上；长任务卡，我们会尝试解析出是哪个脚本干的。
3. 数据上报层 (Reporter) —— 快递员
-
使命必达：用户都要关页面了，数据还没发出去？首选
Navigator.sendBeacon（兼容性好）；在现代浏览器中也可使用 fetch(..., { keepalive: true }) 以支持自定义 Header
-
省流模式：平时不重要的日志先攒一攒（批量上报），关键的报错立刻发（实时上报），给用户的流量省点钱。
4. 配置中心 (Configurator) —— 遥控器
-
随心所欲：通过
options 参数控制。开发环境想看日志？开！生产环境只报错误？关！采样率设多少？你说了算。
核心代码实现
-
主入口 (index.ts)
入口文件负责对外暴露初始化方法，串联各个模块。
-
职责明确：init() 方法一键启动所有监控，按用户体验生命周期（加载 -> 交互 -> 网络）依次调用。
-
配置中心：构造函数接收 options，实现配置合并（如开发模式开启日志）。
-
模块解耦：不直接写监控逻辑，而是通过 import 引入 loading/interaction/network 三大模块的 startXXX 函数，各司其职。
-
示例代码：
import { startFP, startFCP, startLCP, startLoad } from './loading';
import {
startCLS,
startFID,
startInteraction,
startLongTask,
} from './interaction';
import { startEntries, startRequest } from './network';
export default class PerformanceMonitor {
constructor(options = {}) {
this.options = {
log: true, // 开发模式下开启日志
...options,
};
}
init() {
// 1. 页面加载与渲染 (Loading & Rendering)
startFP();
startFCP();
startLCP();
startLoad();
// 2. 交互响应 (Interaction)
startFID();
startInteraction(); // INP
startLongTask();
// 3. 视觉稳定性 (Visual Stability)
startCLS();
// 4. 资源与网络 (Resource & Network)
startEntries();
startRequest();
console.log('Performance Monitor Initialized');
}
}
2. Loading 监控 (loading/index.js)
这部分主要负责捕捉页面从白屏到内容出现的关键时刻。我们把这个过程拆解为三个关键动作：变色 (FP) -> 有内容 (FCP) -> 主角登场 (LCP)。
-
FP (First Paint)：屏幕变色了（不白屏了）。
-
FCP (First Contentful Paint)：看见字或图了（有内容了）。
-
LCP (Largest Contentful Paint)：主角（大图/正文）出来了。
-
Load：资源全加载完了。
(1) FP & FCP：屏幕终于亮了
先讲道理：
-
为什么要一起抓这两个指标是一起抓的？ 因为它俩在浏览器眼里都属于
paint（绘制）类型，都是“第一眼”的感觉。
-
怎么抓？ 用
PerformanceObserver 蹲守。
-
避坑指南（Buffered 标志）： 这是一个极其容易被忽略的参数！
- SDK 初始化往往比页面渲染晚。
- 如果你不开启
buffered: true，就像你 10 点才去蹲守 9 点的日出，永远蹲不到。
- 开启后，浏览器会把过去发生过的指标打包补发给你。
代码实战：
// src/loading/FP.js (FCP 逻辑完全一致，只需改 entry.name)
export function startFP() {
const entryHandler = (list) => {
for (const entry of list.getEntries()) {
// 筛选 'first-paint'
if (entry.name === 'first-paint') {
observer.disconnect(); // FP 一辈子只发生一次，抓到就撤，省内存
const json = entry.toJSON();
console.log('FP Captured:', json);
// 上报数据结构
const reportData = {
...json,
type: 'performance',
name: entry.name,
pageUrl: window.location.href,
};
}
}
};
// 1. 创建观测者
const observer = new PerformanceObserver(entryHandler);
// 2. 开始蹲守 'paint' 频道
// buffered: true 是关键，确保能拿到 SDK 初始化之前的记录
observer.observe({ type: 'paint', buffered: true });
// 3. 返回清理函数
return () => observer.disconnect();
}
(2) LCP：主角登场
先讲道理：
代码实战：
// src/loading/LCP.js
import { getElementSelector } from '../../util/index';
export function startLCP() {
const entryHandler = (list) => {
for (const entry of list.getEntries()) {
const json = entry.toJSON();
const reportData = {
...json,
lcpTime: entry.startTime, // 记录时间
// 核心：利用 element 属性计算出 CSS 选择器，帮你定位是哪个元素慢
elementSelector: getElementSelector(entry.element),
type: 'performance',
name: entry.name,
pageUrl: window.location.href,
};
console.log('LCP Update:', reportData);
}
};
const observer = new PerformanceObserver(entryHandler);
// 同样开启 buffered，防止漏掉
observer.observe({ type: 'largest-contentful-paint', buffered: true });
return () => observer.disconnect();
}
(3) 加载完成
先讲道理：
-
为什么不用
window.onload？ 现在的 SPA（单页应用）和浏览器的“往返缓存”（BFCache）机制，让 onload 变得不那么靠谱（有时候回退页面不会触发 onload）。
-
为什么用
pageshow？ 它能覆盖更多场景，无论你是新打开的，还是后退回来的，它都会触发。
-
为什么套一层
requestAnimationFrame？ pageshow 触发时，浏览器可能还在忙着处理最后的渲染。我们用 rAF 往后稍一稍，让主线程先喘口气，获取的时间更精准，也不影响页面交互。
代码实战：
// src/loading/load.js
export function startLoad() {
const onPageShow = (event) => {
// 往后推一帧，避免抢占主线程
requestAnimationFrame(() => {
['load'].forEach((type) => {
const reportData = {
type: 'performance',
subType: type,
pageUrl: window.location.href,
// 计算相对时间
startTime: performance.now() - event.timeStamp,
};
console.log('Load Captured:', reportData);
});
});
};
window.addEventListener('pageshow', onPageShow, true);
return () => {
window.removeEventListener('pageshow', onPageShow, true);
};
}
3. Interaction 监控
交互性能直接决定了用户觉得你的页面“顺不顺手”。这里我们重点关注 FID/INP (响应速度) 和 Long Task (主线程阻塞)。
(1) FID & INP：点击要灵敏
先认个脸：
三句话讲明白
-
相亲 vs 过日子：FID 就像相亲，只要第一眼（第一次交互）没问题，后面拉胯它也不管；INP 就像过日子，日久见人心，它会盯着你全程的每一次表现，哪怕你前面表现再好，最后一下卡了，分也高不了。
-
只管排队 vs 全程跟踪：FID 只管“排队时间”（你点下去到浏览器开始处理的时间）；INP 管得更宽，它包括“排队 + 处理 + 渲染”的全过程。所以 INP 更能代表用户的真实感受。
-
谁在堵路：想象你去餐厅吃饭（点击），服务员（主线程）正忙着给隔壁桌上菜（执行 JS），没空理你。你等服务员转过身来理你的这段时间，就是 FID。如果服务员理你了，但做菜慢（处理逻辑复杂），上菜也慢（渲染慢），这整个过程太久，INP 就会炸。
直接上代码：FID
// src/interaction/FID.js
export function startFID() {
const observer = new PerformanceObserver((list) => {
for (const entry of list.getEntries()) {
// 核心公式：处理开始时间 - 点击时间 = 延迟时间
const delay = entry.processingStart - entry.startTime;
console.log('FID:', delay, entry.target);
observer.disconnect(); // FID 只看第一下，拿到就撤
}
});
observer.observe({ type: 'first-input', buffered: true });
}
代码怎么理解？
-
processingStart - startTime：startTime 是你手指按下的瞬间，processingStart 是代码终于开始跑的瞬间。这中间的差值，就是浏览器因为“忙不过来”而让用户等待的时间。
-
disconnect()：FID 全称是 First Input Delay，既然是 First，抓到一次就可以收工了，省点内存。
-
buffered: true：防止 SDK 加载晚了。万一用户手快，脚本还没加载完就点了，这个参数能把那次点击记录补发给你。
直接上代码 INP：
// src/interaction/INP.js
export function startINP() {
const observer = new PerformanceObserver((list) => {
for (const entry of list.getEntries()) {
// 不断收集，因为我们要找最慢的那个
// 这里只是简单的打印，实际开发中需要一个算法来取 top 几位
console.log('Interaction Latency:', entry.duration, entry.target);
}
});
// 注意：INP 监听的是 'event' 类型，不是 'first-input'
observer.observe({ type: 'event', durationThreshold: 16, buffered: true });
}
代码怎么理解？
-
INP 代码：
type: 'event'。这里我们不断监听，不断打 log。实际场景里，你需要维护一个数组，把耗时最长的几次交互存下来，最后上报那个最慢的。
-
durationThreshold: 16：这是个优化参数。意思是“小于 16ms（一帧）的交互我就不看了”，省得数据太多刷屏。
踩坑提醒
(2) Long Task：主线程别堵车
先认个脸：
-
Long Task (长任务)：只要执行时间超过 50 毫秒 的任务，都叫长任务。
-
危害：浏览器的主线程是“单线程”的，一次只能干一件事。如果一个任务霸占了主线程太久，其他的点击、滚动、渲染就都得排队，用户就会觉得“卡死”了。
三句话讲明白
-
独木桥效应：主线程就像一座独木桥。平时过的小车（短任务）很快，大家都有路走。突然来了一辆大卡车（长任务），把桥堵得死死的，后面的车（用户交互）全被堵住了。
-
50ms 分界线：为啥是 50ms？
-
100ms 法则：心理学上，用户点击后 100ms 内有反应就算“即时”。
-
对半分：Google 把这 100ms 切成两半：50ms 给你跑代码，50ms 留给浏览器画画。这样加起来刚好 100ms。
-
高刷屏怎么办：虽然 120Hz 屏幕每帧只有 8ms，但在 Web 标准里，50ms 依然是那个平衡了“体验”和“代码复杂度”的安全及格线。
-
抓元凶：监控 Long Task 不光是为了知道“卡了”，更是为了知道“谁卡了”。API 会告诉你是因为哪个 iframe 或者哪个脚本文件导致的。
直接上代码：
// src/interaction/longTask.js
export function startLongTask() {
const observer = new PerformanceObserver((list) => {
for (const entry of list.getEntries()) {
if (entry.duration > 50) {
// 抓到个慢的！看看是谁
// attribution 里面藏着“罪魁祸首”的名字
console.log('LongTask:', entry.duration, entry.attribution);
}
}
});
// 开启监听，buffered 同样重要
observer.observe({ type: 'longtask', buffered: true });
}
代码怎么理解？
-
entry.duration > 50：虽然 API 只会返回长任务，但为了保险（或者你想设置更严格的 100ms 阈值），可以再判断一下。
-
entry.attribution：这是个数组，里面会告诉你这个任务来自哪个 container（比如是当前窗口，还是广告 iframe），有的浏览器还能精确到 scriptURL（脚本文件路径）。
踩坑提醒
-
拆分任务：遇到 Long Task 咋办？拆！ 把一个大函数拆成几个小函数，用
setTimeout 或者 requestIdleCallback 分批执行，给主线程留出喘息的机会（让“大卡车”变成“小车队”）。
-
广告背锅：很多时候你会发现 Long Task 都是广告脚本（iframe）带来的。这种时候……你可以甩锅给广告商，或者延迟加载广告。
-
兼容性：这个 API 兼容性还不错，但还是老规矩，Safari 可能比较高冷（较新版本才支持）。
4. Visual Stability (视觉稳定性) 监控
这可能是最让人抓狂的体验。
CLS：页面别乱动
-
别冤枉好人：用户点了个按钮展开菜单，布局肯定会变，这叫“符合预期”
-
聚沙成塔：CLS 不是一次性的，它是“积分制”。用户在页面上待多久，这期间所有的小抖动都要加起来，算总账。
-
秋后算账：千万别抖一下报一下！CLS 是“长跑比赛”，不到终点（页面关闭/隐藏）不知道最终成绩。必须等用户关页面或者切后台的时候，把最后的总分一次性报上去。
// src/interaction/CLS.js
export function startCLS() {
let clsValue = 0;
const observer = new PerformanceObserver((list) => {
for (const entry of list.getEntries()) {
// 核心：剔除用户交互（点击/输入）导致的预期偏移
if (!entry.hadRecentInput) {
clsValue += entry.value;
}
}
});
observer.observe({ type: 'layout-shift', buffered: true });
const report = () => console.log('CLS Final:', clsValue);
// 双重保险：兼容各类浏览器的卸载场景
window.addEventListener('pagehide', report, { once: true });
document.addEventListener(
'visibilitychange',
() => {
if (document.visibilityState === 'hidden') report();
},
{ once: true }
);
}
代码怎么理解？
-
怎么区分是“好动”还是“乱动”？
刚刚我们说用户交互（比如点按钮展开菜单）导致的布局变化不能算 CLS。那怎么判断呢？
浏览器提供了 hadRecentInput 字段。只要用户最近 500ms 内有过点击或按键，浏览器就会把这个字段标为 true。咱们代码里必须把这些“良民”过滤掉，只抓那些“莫名其妙”的抖动。
-
分数怎么算？
entry.value 就是每一次抖动的分数。比如一张大图突然插进来，把文字挤下去 100px，可能就贡献了 0.05 分。我们要做的就是一个无情的“加法器”，把这些分数全加起来。
-
为啥要监听两个卸载事件？
visibilitychange 和 pagehide 都是用来监听页面关闭/隐藏的。为啥要搞两个？因为浏览器脾气不一样：有的喜欢 pagehide（比如 Safari），有的推荐 visibilitychange。为了保证数据不丢，咱们搞个“双保险”，谁先触发就算谁的。
-
为啥不用 beforeunload？
早年间确实流行用
beforeunload 或 unload，但现在它们不靠谱了，尤其是在手机上。用户直接划掉 App、切后台，这些事件经常不会触发。而且它还会阻止浏览器做“往返缓存”（BFCache），拖慢页面后退速度。所以现在的标准姿势就是 visibilitychange + pagehide。
踩坑提醒
- 成绩线：CLS < 0.1 很好，> 0.25 需要重点优化
- 动态内容要“留坑位”：骨架屏/固定尺寸，能明显降低位移
- 广告/懒加载图片经常是元凶，优先排查
💡 进阶小贴士：
这里为了演示原理，我们使用了简单的累加法。但在生产环境中（特别是 SPA 单页应用），Google 推荐使用 Session Window（会话窗口） 算法
先说痛点（累加法的 Bug）：
以前的 CLS 算法是“无限累加”的。这就好比你在一个页面看了 10 分钟书，这期间广告每分钟抖一下（假设每次 0.01 分）。等你关页面时，总分就是 0.01 * 10 = 0.1，及格。
但如果你看了 10 个小时呢？总分就变成了 6.0，不及格！
这对 SPA（单页应用）尤其不公平：
-
传统网页：每次跳转页面都会刷新，指标清零重算，想拿低分（好成绩）很容易。
-
SPA 应用：用户在“首页 -> 列表页 -> 详情页”之间切换时，浏览器并没有刷新。如果你用累加法，这三个页面的抖动会全部加在同一个头上。用户用得越久，CLS 分数就越差，但这显然不符合实际体验（用户只关心当前看到的页面抖不抖）。
新算法（会话窗口）：
为了解决这个问题，Google 改成了“会话窗口”制。
想象一下，我们把每一次抖动看作一次“余震”。如果几次余震挨得很近（间隔小于 1 秒），并且总持续时间没超过 5 秒，我们就把它们算作一次大地震。
无论你页面开了多久，我们只取震级最高的那一次大地震作为最终成绩。这样，不管你待 10 分钟还是 10 小时，只要没有发生剧烈的连续抖动，你的 CLS 分数都是优秀的。
5. Network 监控：查查谁在拖后腿
先认个脸：
-
Resource Timing (资源计时)：专门管资源加载的。不管是图片、CSS、JS 文件，还是接口请求 (XHR/Fetch)，只要是从网络下载的东西，它都能记一笔。
-
核心指标：除了总耗时 (
duration)，还能细到 DNS 解析多久、TCP 建连多久、首字节时间 (TTFB) 等等。
三句话讲明白
-
查快递：你买东西（请求资源），想知道为什么这么慢？是卖家发货慢（TTFB），还是路上堵车（下载慢）？Resource Timing 就是那个详细的物流单。
-
不只是图片：别被名字骗了，它不光管图片 CSS，你的
fetch 请求、axios 请求，只要走了网络，它都能监控到。
-
严防死守：浏览器为了安全，对于跨域的资源（比如你用了百度的图片），默认只告诉你“用了多久”，不告诉你“怎么用的”（DNS/TCP 细节），除非对方给了通行证。
直接上代码：
export function startEntries() {
const observer = new PerformanceObserver((list) => {
for (const entry of list.getEntries()) {
// resource 类型包含了 img, script, css, fetch, xmlhttprequest, link 等
if (entry.entryType === 'resource') {
console.log(
'Resource:',
entry.name,
entry.initiatorType,
entry.duration
);
}
}
});
// 同样记得 buffered: true，防止漏掉页面刚开始加载的那些资源
observer.observe({ type: 'resource', buffered: true });
}
代码怎么理解？
-
entryType === 'resource'：这个频道包罗万象。图片 (img)、样式 (css)、脚本 (script) 甚至你的接口调用 (fetch/xmlhttprequest) 都在这儿。
-
initiatorType：这个字段告诉你资源是谁发起的。是 <img src="..."> 发起的？还是 fetch() 发起的？一看便知。
进阶用法：监控接口 (API) 耗时详情
有时候我们不关心图片资源，而是重点关注后端接口的响应耗时。通过过滤 fetch 和 xmlhttprequest，我们不仅能知道接口慢不慢，还能知道慢在哪里（是 DNS、TCP 还是服务端处理）。
export function startRequest() {
const entryHandler = (list) => {
const data = list.getEntries();
for (const entry of data) {
// 过滤出 API 请求 (Fetch 和 XHR)
if (
entry.initiatorType === 'fetch' ||
entry.initiatorType === 'xmlhttprequest'
) {
const reportData = {
name: entry.name, // 请求地址
type: 'performance',
subType: entry.entryType,
sourceType: entry.initiatorType,
duration: entry.duration, // 请求总耗时
dns: entry.domainLookupEnd - entry.domainLookupStart, // DNS 解析耗时
tcp: entry.connectEnd - entry.connectStart, // TCP 连接耗时
ttfb: entry.responseStart - entry.requestStart, // 首字节响应时间 (服务端处理时间)
transferSize: entry.transferSize, // 传输字节数
startTime: entry.startTime, // 请求开始时间
pageUrl: window.location.href,
};
console.log('Network Request:', reportData);
}
}
};
// 这里不调用 disconnect()，以便持续监听后续产生的网络请求
const observer = new PerformanceObserver(entryHandler);
observer.observe({ type: 'resource', buffered: true });
}
代码怎么理解？
踩坑提醒
-
跨域拿不到细节：这是最常见的坑。看到 DNS 时间是 0 别奇怪，八成是跨域了且没加
Timing-Allow-Origin 头。这是浏览器为了保护隐私。
-
别全报：一个页面可能有上百个资源，全报上去服务器受不了。建议设个门槛（比如只报 > 1 秒的），或者只报核心的 JS/CSS。
-
接口监控：很多人不知道
fetch 请求也能在这里抓到。其实用它来监控后端接口性能，比自己封装 axios 拦截器要准得多，因为它算的是浏览器底层的真实时间。
6. 必备工具函数：定位神器 (util/index.js)
最后，我们得有个工具能帮我们“指路”。只告诉老板“图片慢”没用，你得告诉他是“哪个图片慢”。
getElementSelector 就是这个“定位神器”。它能把一个 DOM 元素转换成 CSS 选择器（比如 body > div#app > h1），让你直接在代码里找到它。
// src/util/index.js
export function getElementSelector(element) {
if (!element || element.nodeType !== 1) return '';
// 如果有 id，直接返回 #id
if (element.id) {
return `#${element.id}`;
}
// 递归向上查找
let path = [];
while (element) {
let name = element.localName;
if (!name) break;
// 如果有 id，拼接后停止
if (element.id) {
path.unshift(`#${element.id}`);
break;
}
// 加上 class
let className = element.getAttribute('class');
if (className) {
name += '.' + className.split(/\s+/).join('.');
}
path.unshift(name);
element = element.parentElement;
}
return path.join(' > ');
}
7. 自定义指标：代码秒表
除了浏览器给的指标，有时候我们想知道某个具体函数到底跑了多久，或者滚动列表卡不卡。这时候就需要我们自己造个“秒表”。
(1) 函数耗时监控 (Wrapper)
三句话讲明白
-
不改业务代码：不用在每个函数里写
start 和 end，用这个“高阶函数”包一下就行。
-
支持异步：不管是普通的
for 循环，还是 await 数据库查询，都能监控。
-
自动抓报错：如果函数跑挂了，它还能顺便把错误信息记下来。
直接上代码：
/**
* 同步函数计时器
* 用法：const newData = timeFunction('处理数据', processData, rawData);
*/
export const timeFunction = (name, fn, ...args) => {
const start = performance.now();
try {
const result = fn(...args);
const duration = performance.now() - start;
console.log(`Function [${name}]:`, duration.toFixed(2) + 'ms');
return result;
} catch (error) {
console.error(`Function [${name}] Error:`, error);
throw error; // 别吞掉错误，继续抛出
}
};
/**
* 异步函数计时器 (Promise)
* 用法：const user = await timeAsyncFunction('获取用户', fetchUser, id);
*/
export const timeAsyncFunction = async (name, fn, ...args) => {
const start = performance.now();
try {
const result = await fn(...args); // 等待异步完成
const duration = performance.now() - start;
console.log(`Async Function [${name}]:`, duration.toFixed(2) + 'ms');
return result;
} catch (error) {
console.error(`Async Function [${name}] Error:`, error);
throw error;
}
};
(2) 滚动流畅度监控
三句话讲明白
-
不看帧率看延迟：算 FPS 太复杂。我们就看最朴素的道理：我划了一下屏幕，浏览器多久才画出下一帧？
-
搭便车 (rAF)：
requestAnimationFrame (rAF) 是浏览器的“渲染末班车”。我们在滚动事件里跳上这趟车，等车到站了（渲染完成了），看看表，就知道这一路花了多久。
-
抽查机制：滚动事件触发频率极高（一秒几百次）。我们没必要次次都查，每隔半秒（500ms）抽查一次“末班车”准不准点就行了。
直接上代码：
// src/interaction/scroll.js
export function startScroll() {
let lastScrollLog = 0;
const scrollMinInterval = 500; // ms，限流，每半秒检查一次
const onScroll = () => {
const start = performance.now();
// 没到时间就别折腾，省点 CPU
if (start - lastScrollLog < scrollMinInterval) return;
lastScrollLog = start;
// 核心逻辑：预约下一帧渲染
// 就像你对浏览器说：“兄弟，画完这帧叫我一声。”
requestAnimationFrame(() => {
const afterRAF = performance.now();
const duration = afterRAF - start; // 这一帧到底花了多久？
// 16ms 是 60Hz 屏幕的标准一帧时间
// 如果超过 16ms，说明浏览器忙不过来了，这就叫“掉帧”
if (duration > 16) {
console.log('Scroll Lag:', duration.toFixed(2) + 'ms');
}
});
};
// passive: true 告诉浏览器“我不阻止滚动”，能让滚动更丝滑
window.addEventListener('scroll', onScroll, { passive: true });
}
代码怎么理解？
-
为什么要用
requestAnimationFrame？
- JS 是单线程的。当你触发
scroll 事件时，浏览器可能正忙着处理别的事（比如重排重绘）。
-
requestAnimationFrame 会把你的代码放到浏览器准备画下一帧的时候执行。
- 所以，
start 是你触发滚动的时间，afterRAF 是画面终于画出来的时间。这俩的差值 (duration) 越大，说明浏览器卡得越久，你感觉到的“顿挫感”就越强。
8. 数据上报（sender.ts）
收集到数据后，如何发给后端？这看似简单，实则暗藏玄机。
1. 核心痛点：页面关了，请求还没发完怎么办？
用户看完网页直接关掉（或者刷新跳转），这时候浏览器会无情地杀掉当前页面进程里所有正在跑的异步请求（XHR/Fetch）。
结果就是：监控数据还没发出去，就死在半路上了。
2. 解决方案
为了确保数据必达，我们采用一套组合拳：
-
首选 Navigator.sendBeacon：
它是专门为“页面卸载上报”设计的。
特点：浏览器会在后台默默把数据发完，不阻塞页面关闭，也不会被杀掉。
-
次选 fetch + keepalive：
如果浏览器不支持 Beacon，或者你需要自定义 Header（Beacon 不支持自定义 Header），就用 fetch 并开启 keepalive: true。
特点：告诉浏览器“这个请求很重要，页面关了也请帮我发完”。
3. 代码实现
export const sendBehaviorData = (data: Record<string, any>, url: string) => {
// 1. 包装数据：加上一些公共信息（比如 UserAgent，屏幕分辨率等）
const dataToSend = {
...data,
userAgent: navigator.userAgent,
// screenWidth: window.screen.width, // 可选
};
// 2. 优先使用 sendBeacon (最稳，且不阻塞)
// 注意：sendBeacon 不支持自定义 Content-Type，默认是 text/plain
// 这里用 Blob 强制指定为 application/json
if (navigator.sendBeacon) {
const blob = new Blob([JSON.stringify(dataToSend)], {
type: 'application/json',
});
// sendBeacon 返回 true 表示进入队列成功
navigator.sendBeacon(url, blob);
return;
}
// 3. 降级方案：使用 fetch + keepalive
// 即使页面关闭，keepalive 也能保证请求发出
fetch(url, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(dataToSend),
keepalive: true, // <--- 关键参数！防止页面关闭时请求被杀
}).catch((err) => {
console.error('上报失败:', err);
});
};
3. 工程化构建配置
既然是 SDK，最好的分发方式当然是发布到 NPM。这样其他项目只需要一行命令就能接入你的前端错误监控系统。
这里我们选择 Rollup对代码进行打包，因为它比 Webpack 更适合打包库（Library），生成的代码更简洁。
3.1 package 配置 (package.json)
package.json 不仅仅是依赖管理，它还定义了你的包如何被外部使用。配置不当会导致用户引入报错或无法获得代码提示。
{
"name": "performance-sdk",
"version": "1.0.0",
"description": "A lightweight performance monitoring SDK",
"main": "dist/index.cjs.js",
"module": "dist/index.esm.js",
"browser": "dist/index.umd.js",
"type": "module",
"scripts": {
"build": "rollup -c",
"dev": "rollup -c -w"
},
"keywords": ["performance", "monitor", "sdk"],
"license": "MIT",
"files": ["dist"],
"devDependencies": {
"rollup": "^4.9.0",
"@rollup/plugin-typescript": "^11.1.0",
"@rollup/plugin-terser": "^0.4.0",
"typescript": "^5.3.0",
"tslib": "^2.6.0"
}
}
💡 关键字段解读：
-
name: 包的“身份证号”。在 NPM 全球范围内必须唯一，发布前记得先去搜一下有没有重名。
-
入口文件“三剑客”（决定了别人怎么引用你的包）：
-
main: CommonJS 入口。给 Node.js 环境或老旧构建工具（如 Webpack 4）使用的。
-
module: ESM 入口。给现代构建工具（Vite, Webpack 5）使用的。支持 Tree Shaking（摇树优化），能减小体积。
-
browser: UMD 入口。给浏览器直接通过 <script> 标签引入使用的（如 CDN）。
-
files: 发布白名单。指定 npm publish 时只上传哪些文件（这里我们只传编译后的 dist 目录）。源码、测试代码等不需要发上去，以减小包体积。
3.2 TypeScript 配置 (tsconfig.json)
我们需要配置 TypeScript 如何编译代码，并生成类型声明文件（.d.ts），这对使用 TS 的用户非常友好。
{
"compilerOptions": {
"target": "es5", // 编译成 ES5，兼容旧浏览器
"module": "esnext", // 保留 ES 模块语法，交给 Rollup 处理
"declaration": true, // 生成 .d.ts 类型文件 (关键！)
"declarationDir": "./dist", // 类型文件输出目录
"strict": true, // 开启严格模式，代码更健壮
"moduleResolution": "node" // 按 Node 方式解析模块
},
"include": ["src/**/*"] // 编译 src 下的所有文件
}
3.3 Rollup 打包配置 (rollup.config.js)
为了兼容各种使用场景，我们配置 Rollup 输出三种格式：
-
ESM (
.esm.js): 给现代构建工具（Vite, Webpack）使用，支持 Tree Shaking。
-
CJS (
.cjs.js): 给 Node.js 或旧版工具使用。
-
UMD (
.umd.js): 可以直接在浏览器通过 <script> 标签引入，会挂载全局变量。
import typescript from '@rollup/plugin-typescript';
import terser from '@rollup/plugin-terser';
export default {
input: 'src/index.ts',
output: [
{ file: 'dist/index.cjs.js', format: 'cjs', sourcemap: true },
{ file: 'dist/index.esm.js', format: 'es', sourcemap: true },
{
file: 'dist/index.umd.js',
format: 'umd',
name: 'PerformanceSDK',
sourcemap: true,
plugins: [terser()],
},
],
plugins: [
typescript({
tsconfig: './tsconfig.json',
declaration: true,
declarationDir: 'dist',
}),
],
};
4. 发布到 NPM (保姆级教程)
4.1 准备工作
-
注册账号：去 npmjs.com 注册一个账号（记得验证邮箱，否则无法发布）。
-
检查包名：在 NPM 搜一下你的
package.json 里的 name，确保没有被占用。如果不幸重名，改个独特的名字，比如 performance-sdk-vip。
4.2 终端操作三步走
打开终端（Terminal），在项目根目录下操作：
第一步：登录 NPM
npm login
- 输入命令后按回车，浏览器会弹出登录页面。
- 或者在终端根据提示输入用户名、密码和邮箱验证码。
- 登录成功后会显示
Logged in as <your-username>.
- 注意：如果你之前切换过淘宝源，发布时必须切回官方源：
npm config set registry https://registry.npmjs.org/
第二步：打包代码
确保 dist 目录是最新的，不要发布空代码。
npm run build
第三步：正式发布
npm publish --access public
-
--access public 参数用于确保发布的包是公开的（特别是当包名带 @ 前缀时）。
- 看到
+ performance-sdk-vip@1.0.0 字样，恭喜你，发布成功！
现在，全世界的开发者都可以通过 npm install performance-sdk-vip 来使用你的作品了！
5. 如何使用
SDK 发布后，支持多种引入方式，适配各种开发场景。
npm install performance-sdk
import PerformanceMonitor from 'performance-sdk';
const monitor = new PerformanceMonitor({
/* 可选：log, sampleRate, reportUrl */
});
monitor.init();
<script src="https://unpkg.com/performance-sdk@x.x.x/dist/index.umd.js"></script>
<script>
const monitor = new PerformanceSDK.PerformanceMonitor({
/* 可选配置 */
});
monitor.init();
</script>
6. 总结与展望
恭喜你！到这里，你已经亲手打造了一套麻雀虽小，五脏俱全的性能监控 SDK。
咱们再回头看看这四大支柱：
-
Loading (加载)：FP/FCP/LCP 负责盯着**“快不快”**。白屏时间短，用户才愿意留下来。
-
Interaction (交互)：FID/INP 负责盯着**“顺不顺”**。点击有反馈，用户才觉得好用。
-
Visual Stability (稳定性)：CLS 负责盯着**“稳不稳”**。页面不乱跳，用户才不心烦。
-
Network (网络)：Resource Timing 负责盯着**“通不通”**。接口响应快，体验才有底气。
下一步可以玩点啥？
性能监控只是前端监控体系的三分之一。如果你想打造一个无死角的监控系统，光看性能是不够的：
-
报错了咋办？ JS 挂了、接口 500 了、资源加载失败了……这些需要错误监控来兜底。
👉 传送门：
《【错误监控】别只做工具人了！手把手带你写一个前端错误监控 SDK》（https://juejin.cn/post/7580674010837549102）
-
用户在干啥？ 用户点了哪个按钮？在哪个页面停留最久？这些需要行为监控来分析。
👉 传送门：《【用户行为监控】别只做工具人了！手把手带你写一个前端埋点统计 SDK》（https://juejin.cn/post/7583612559443279923）
当然，你还可以结合：
-
可视化大屏：光有数据不行，得画成图表（ECharts/Grafana）。看着曲线波动，才有成就感。
-
报警机器人：LCP 超过 4 秒了？接口报错率飙升了？直接钉钉/飞书群里 @ 全体成员，把问题扼杀在摇篮里。
性能优化是一场没有终点的马拉松。希望这篇文章能是你打造专属监控系统的起点。Happy Coding!
如果觉得对您有帮助，欢迎点赞👍 收藏 ⭐ 关注 🔔 支持一下！
登录
