performance.measure 的两个参数必须都已存在，否则静默失败；常见漏打场景包括快速连点、钩子中 DOM 未就绪、路由跳转 mark 覆盖；验证需用 console.assert 检查 mark 是否存在；“渲染完成”应检测真实 DOM 内容或 LCP，而非仅依赖生命周期钩子；上报须节流、抽样、清理。
performance.measure 的两个参数必须都已存在，否则静默失败
调用 performance.measure('click_to_render', 'click_start', 'render_end') 时，如果 click_start 或 render_end 任一 mark 没打上，measure 就不会生成任何条目——控制台不报错，performance.getEntriesByType('measure') 里也查不到。这不是 bug，是规范行为。
常见漏打场景：
- 用户快速连点，第二次 click 事件触发时，第一次的
render_end还没执行（比如组件异步渲染未 resolve） -
render_end打在useEffect或mounted钩子里，但 DOM 节点实际为空或未挂载完成 - SPA 路由跳转中，旧页面的 mark 未清理，新页面同名 mark 被覆盖，导致 measure 取到错误时间戳
验证方式：上报前加一行 console.assert(performance.getEntriesByName('click_start', 'mark').length > 0 && performance.getEntriesByName('render_end', 'mark').length > 0, 'missing mark for click_to_render')，上线前可临时启用。
“组件渲染完成”的判定不能只依赖生命周期钩子
React 的 useEffect、Vue 的 mounted、甚至 requestIdleCallback 都不等于“用户可见内容已就位”。比如 SSR 后 hydration 完成但图片还没加载，或关键文本还在 font-display: swap 状态下闪烁。
更可靠的打点时机：
- 检测真实 DOM 内容：在
useEffect里用document.querySelector('#search-result-list')?.children.length > 0+getBoundingClientRect().height > 0 - 结合
PerformanceObserver监听largest-contentful-paint，但仅用于兜底校验，不作为主链路打点依据（LCP 触发太晚） - 对列表类组件，用
MutationObserver监听目标容器子节点插入，并配合isIntersecting判断是否进入视口
避免写成：performance.mark('render_end') 放在 useEffect(() => { /* 渲染逻辑 */ }, []) 里——它只代表 JS 执行完，不代表 UI 已稳定。
上报前必须做节流+抽样+清理，否则数据不可用
一个用户单页内可能触发 5–10 次搜索点击，每点都打 2 个 mark + 1 个 measure，不处理就会污染 PerformanceEntry 缓存，且上报量爆炸。
实操建议：
- 节流：对同一业务模块（如搜索），限制
measure上报频率为「每 30 秒最多 1 次」，用setTimeout+ 时间戳缓存控制 - 抽样：按
Math.abs(hash(userId)) % 100 做 2% 用户抽样，非核心链路可降到 0.1% - 清理：每次上报后立即调用
performance.clearMeasures('click_to_render')和performance.clearMarks('click_start')、performance.clearMarks('render_end')，防止历史条目累积拖慢后续getEntriesByType查询 - 必须用
navigator.sendBeacon()上报，payload 控制在 64KB 内，字段精简为{mark: 'click_to_render', duration: 342.7, url: window.location.pathname}
命名必须带业务上下文，且禁止复用 mark 名
写成 performance.mark('start') 和 performance.mark('end') 是自找麻烦。同一页面多个交互（搜索、下单、筛选）会互相覆盖，measure 取到的可能是上一个模块的时间戳。
正确命名规则：
- 前缀固定为业务模块：如
search_、checkout_、filter_ - 中间是阶段语义：
click、api_response、list_rendered - 后缀统一为
_start/_end，measure 名用_duration
例如：
performance.mark('search_click_start');
// ... fetch ...
performance.mark('search_api_response_end');
performance.mark('search_list_rendered_end');
performance.measure('search_click_to_list', 'search_click_start', 'search_list_rendered_end');
注意：同一个 mark 名多次调用会保留全部时间戳，getEntriesByName 返回数组，measure 默认取第一个——这在用户反复操作时极易出错，所以每个 mark 名必须唯一、一次一打。
