构建自定义PerformanceEntry需在标准API内用mark/measurement打点并配合PerformanceObserver上报，确保语义明确、时序正确、兼容降级且上报聚合可追溯。
要构建符合业务需求的自定义 PerformanceEntry，关键不在于“造轮子”，而是在标准 Performance API 框架内精准打点、合理归类、稳定上报。浏览器原生不支持直接创建任意 PerformanceEntry 实例（如 new PerformanceEntry() 会报错），但可通过 performance.mark() 和 performance.measure() 配合 PerformanceObserver 实现等效效果，并赋予业务语义。
用 mark + measure 构建带业务含义的 entry
所有自定义性能指标都应基于用户可感知的关键路径，比如「商品详情页首屏渲染完成」「搜索结果列表加载耗时」「支付按钮点击到弹窗出现」。这类指标无法被 LCP、FCP 等通用指标覆盖，需手动标记：
- 在业务逻辑关键节点调用
performance.mark('product-detail-first-paint')，名称需唯一且语义明确 - 在后续完成点（如 DOM 渲染完毕、数据绑定完成）再次调用
performance.mark('product-detail-ready') - 立即执行
performance.measure('product-detail-ssr-to-client', 'product-detail-first-paint', 'product-detail-ready')，生成一条 type="measure" 的 entry - 该 entry 将出现在
performance.getEntriesByType('measure')结果中，name为 measure 名，duration为毫秒值，startTime为起始 mark 时间偏移
通过 PerformanceObserver 捕获并增强业务上下文
仅生成 entry 不够，还需注入业务维度信息（如页面类型、用户等级、AB 实验分组），这需在 observer 回调中完成：
- 注册 observer 时必须显式声明
{ entryTypes: ['measure'] }，否则回调永不触发 - 在回调中遍历
entryList.getEntries()，筛选出你关心的 measure name - 为每条 entry 补充字段：例如添加
pageType: 'product'、abGroup: 'v2'、isLogin: true，存入自定义上报 payload - 避免在回调中同步执行 heavy 操作（如 JSON.stringify 大对象或发请求），应节流或进队列
兼容性与防错要点
真实环境中，自定义打点极易因环境或误用失效，需主动防御：
-
mark 名重复会抛 SyntaxError：Vue 组件复用、React 路由守卫多次进入时常见。应在调用前检查：
if (performance.getEntriesByName('xxx').length === 0) performance.mark('xxx') - measure 依赖 mark 存在且顺序正确：异步逻辑中易出现 measure 先于 mark 执行，导致 duration=0。建议将 mark/meausre 封装成原子函数，或使用 Promise 链保证时序
-
低版本兼容 fallback：Web 态部分环境（如旧版 WebView）不支持
getEntriesByType，需降级为定时轮询performance.getEntries()并按entryType过滤 - 真机调试优先：开发者工具常不触发 PerformanceObserver 或返回空数组，务必在 iOS/Android 真机验证
上报设计：轻量、聚合、可追溯
自定义指标的价值体现在分析端，上报结构需兼顾灵活性与可查询性：
- 单次上报建议聚合多个 measure 条目（如一次 PV 上报 3–5 个业务耗时），减少请求数
- 每条数据包含：
name（业务标识）、duration（核心数值）、timestamp（performance.timeOrigin + entry.startTime）、navigationType（来自performance.navigation.type）、pagePath（当前 URL 或路由 path） - 添加
traceId字段，关联同一次用户操作下的多个指标（如从点击到接口响应再到渲染），便于下钻分析 - 使用
navigator.sendBeacon()上报，确保页面卸载前也能发出；若不可用，降级为 fetch + keepalive
