如何利用 performance.mark 搭建从逻辑触发到渲染上帧的精细化业务全链路耗时

作者：袖梨 2026-06-16

performance.mark 本身不触发渲染，也不能保证标记时间点与“上帧”对齐；需配合 requestAnimationFrame 等生命周期钩子，分阶段锚定 JS 执行完成、DOM 更新完成、视觉呈现完成三个关键节点。

直接结论：performance.mark 本身不触发渲染，也不能保证标记时间点与“上帧”对齐；要建立从逻辑触发到真正上帧的链路，必须把 mark 和浏览器渲染生命周期的关键钩子（如 requestAnimationFrame、setTimeout(0)、queueMicrotask）配合使用，并明确区分「JS 执行完成」「DOM 更新完成」「视觉呈现完成」三个阶段。

为什么 performance.mark('render-end') 不等于“上帧”

performance.mark('render-end') 只记录 JS 调用那一刻的时间戳，但此时 DOM 可能还没更新，更不意味着像素已绘制到屏幕。常见误判场景：

在 React 的 useEffect 或 Vue 的 nextTick 回调里打点，只代表虚拟 DOM 已提交，不代表真实 DOM 已插入或样式已计算
调用 element.innerHTML = ... 后立刻 mark('dom-ready')，但 layout/paint 尚未触发，getBoundingClientRect() 可能仍返回旧值
依赖 DOMContentLoaded 或 load 事件打点，它们和首帧渲染无强关联，尤其在 SSR/SSG 场景下偏差可达数百毫秒

怎么打点才能对齐“上帧”时刻

关键不是“打得多”，而是每个 mark 是否锚定在可验证的渲染就绪信号上。推荐组合方式：

逻辑触发起点：在用户交互回调开头打 performance.mark('click-start')（如按钮 onclick）
DOM 更新确认点：在 requestAnimationFrame 回调中打 performance.mark('raf-dom-updated') —— 这是浏览器保证 DOM 已更新、样式已计算、布局已完成的最早时机
视觉呈现确认点：再套一层 requestAnimationFrame（即第二次 rAF），打 performance.mark('raf-painted') —— 此时浏览器已将帧提交至合成器，大概率已上屏（注意：仍受 vsync 和 compositor pipeline 影响，但已是前端可捕获的最接近“上帧”的信号）
避免用 setTimeout(0) 或 queueMicrotask 替代 rAF：它们只能保证 JS 执行顺序，无法确保 layout/paint 完成，打点会偏早

measure 配对时最容易漏掉的两个条件

performance.measure() 看似简单，但在渲染链路中极易静默失败：

必须确保两个 mark 都存在于同一帧上下文内：如果用户快速连续点击，前一次的 'raf-painted' 可能被后一次的 mark 覆盖（因同名覆盖机制），建议用唯一 trace ID 构造名称，例如 `raf-painted-${traceId}`
rAF 回调可能不执行：页面被切到后台、tab 冻结、或主线程长时间阻塞时，rAF 会被跳过。应在 rAF 回调里加 guard 判断，比如检查目标元素是否已挂载、offsetHeight > 0 是否为真，再打点
不要跨帧 measure：比如在第 1 帧打 'click-start'，在第 3 帧打 'raf-painted'，然后 measure —— 数据虽能算出，但已失去“单次交互响应”的业务意义；应按 trace ID 分组，在同一流程内闭环

上报前必须做的三件事

渲染链路数据天然稀疏且易丢失，不处理好这三点，大盘基本不可信：

用 PerformanceObserver 监听 'measure' 类型，而不是轮询 getEntriesByType('measure')：前者能实时捕获，后者在页面卸载前可能来不及读取
上报必须用 navigator.sendBeacon()，且 payload 中显式包含 entry.startTime 和 entry.duration：因为 entry.name 是字符串，服务端需靠它做路由分发（如识别 'search-click-to-paint'）
每次关键流程结束后，调用 performance.clearMarks(traceIdPrefix)：否则长期运行的 SPA 页面会堆积大量无用 mark，拖慢 DevTools 加载，甚至触发浏览器 entry 限制（默认约 150 条）