性能指标深度定制：构建符合业务需求的自定义 PerformanceEntry

构建自定义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