自建访问统计:SSR 采集、心跳和会话合并

2026-11-19 前端开发 有希 42 views

用前端埋点统计 PV,常见结果是首屏漏记、刷新重复、切后台后停留时长还在涨。原因通常不是埋点少,而是把“页面渲染”“路由切换”“页面可见性”混成了同一个事件。本文按门户的自建统计实现,说明服务端和浏览器各自负责什么、会话怎么合并,以及看板聚合时最容易写错的 SQL 顺序。

先给结论

访问统计要分两层:

  • 服务端在每次 HTML 渲染时记首屏 PV,能拿到真实 IP、UA、Referer,也不依赖 JavaScript 是否执行。
  • 浏览器只补服务端看不到的部分:SPA 路由切换、页面可见性变化、停留时长和会话续期。

两层用同一套 visitorId、sessionId 和路径口径,事件才能在后台合并。首屏 PV 只由服务端记一次,客户端不要重复记;否则刷新一次就多一次 PV。

现象:PV 重复、时长不动、会话碎掉

现象常见原因
首屏 PV 是 2服务端记了一次,客户端挂载后又记一次
刷新一次 PV 加 2 或 3SPA 路由钩子和页面加载都上报 PV
后台标签页停留时长一直涨没有在 visibilitychange 时停止计时
同一用户被算成多个会话会话 cookie 没有滑动续期,或客户端每次新生成
页面排行平均停留恒为 0聚合时先过滤了 pv,再对 leave 的时长求平均
错误页进入排行没排除 __nuxt_error 或静态资源

这些问题单独看都像“埋点不准”,实际是事件边界没有定义清楚。

服务端:只统计 HTML 页面渲染

门户在 Nitro 中间件里采集,判断条件有五条:

function isPageRender(event: any): boolean {
  if (event.method !== 'GET') return false

  const path: string = event.path || ''
  if (!path.startsWith('/')) return false

  if (
    path.startsWith('/_nuxt') ||
    path.startsWith('/_ipx') ||
    path.startsWith('/imgly-data') ||
    path.startsWith('/__nuxt_error')
  ) {
    return false
  }

  const lastSegment = path.split('/').pop() || ''
  if (lastSegment.includes('.')) return false

  const accept = String(event.node.req.headers.accept || '')
  return accept.includes('text/html')
}

逐条对应一个误判来源:

条件排除的情况
GET表单提交、API 写请求
路径以 / 开头非法或内部路径
排除 /_nuxt、/_ipxJS、CSS、图片优化资源
排除 /imgly-data图片编辑器的本地数据路由
排除 /__nuxt_error错误页的内部二次渲染
最后一段不含 ..png、.ico、.js 等静态文件
Accept 含 text/htmlfetch 的 JSON、图片、流式请求

/__nuxt_error 这一条尤其重要。Nuxt 渲染错误页时会内部再走一次中间件,真实路径在外层已经记过;不排除,错误页会把排行和 PV 都污染一遍。

服务端在响应里种两个 cookie:

Cookie有效期用途
vid1 年访客标识,用于 UV
sid30 分钟会话标识,用于会话数和停留

sid 是滑动过期:每次页面渲染或事件上报都会重新写一次 30 分钟。用户持续访问时,会话不会因为固定 30 分钟到期而断成两段;停止访问 30 分钟后,下一次访问才生成新会话。

setCookie(event, VISITOR_COOKIE, visitorId, {
  maxAge: 60 * 60 * 24 * 365,
  path: '/',
  sameSite: 'lax'
})
setCookie(event, SESSION_COOKIE, sessionId, {
  maxAge: 60 * 30,
  path: '/',
  sameSite: 'lax'
})

cookie 值损坏或伪造时,decodeURIComponent 可能抛错。两端的读取函数都按“缺失”处理,再用新 UUID 覆盖,避免统计上报把页面渲染打断。

路径口径:剥掉语言前缀

同一个页面有 /zh/about、/en/about 和无前缀的 /about。如果直接按 event.path 排行,一个页面会被拆成三份。服务端和客户端都剥掉已知语言前缀:

for (const prefix of ['/zh-Hant', '/zh', '/en']) {
  if (statsPath === prefix) {
    statsPath = '/'
    break
  }
  if (statsPath.startsWith(prefix + '/')) {
    statsPath = statsPath.slice(prefix.length)
    break
  }
}

前缀顺序必须长的在前,/zh-Hant 放在 /zh 前面,否则会被短前缀先匹配,剩下 -Hant/...。

客户端:只补服务端看不到的事件

首屏 PV 已由服务端记录,客户端插件启动时只登记当前位置和进入时间,不再发 PV:

let lastPath = statsPath(router.currentRoute.value.fullPath)
let enteredAt = Date.now()
let left = false

路由切换:leave 和 pv 合并成一个请求

router.afterEach((to) => {
  const path = statsPath(to.fullPath)
  if (path === lastPath) return

  const events: Record<string, unknown>[] = []
  if (!left) {
    events.push(makeEvent('leave', lastPath, Date.now() - enteredAt))
  }
  events.push(makeEvent('pv', path))
  send({ platform: 'web', events })

  lastPath = path
  left = false
  enteredAt = Date.now()
})

一次导航只发一个请求,events 数组里同时有上一页的 leave 和下一页的 pv。如果分两个请求,网络抖动时可能只到了 PV、没到 leave,停留时长就丢了。

心跳:只在页面可见时续会话

setInterval(() => {
  if (document.visibilityState === 'visible') {
    event('heartbeat', lastPath)
  }
}, 30_000)

心跳有三个作用:

  1. 续期 sid,让持续阅读不被 30 分钟边界切断。
  2. 让服务端知道这个会话仍然活跃。
  3. 给停留时长一个上限参考,避免用户直接关掉进程时完全没记录。

页面隐藏时不发心跳。后台标签页停留不计入本页时长,这是有意为之:用户没有在看页面,不应该算阅读时间。

离开:visibilitychange 和 pagehide 去重

const leaveOnce = (): void => {
  if (left) return
  left = true
  event('leave', lastPath, Date.now() - enteredAt)
}

document.addEventListener('visibilitychange', () => {
  if (document.visibilityState === 'hidden') {
    leaveOnce()
  } else {
    left = false
    enteredAt = Date.now()
  }
})

window.addEventListener('pagehide', leaveOnce)

visibilitychange 和 pagehide 经常在同一时刻触发,left 标志保证只发一次 leave。切回前台时 left 复位,enteredAt 重新起算,后台时间不会被算进停留。

用 fetch(..., { keepalive: true }) 而不是 navigator.sendBeacon,是因为上报体很小,keepalive 足够,而且能统一走 JSON 和现有 API 封装。它不保证一定送达,统计失败会静默丢弃,不影响页面。

事件合并:PV、UV、会话和停留

四个指标的口径要分开:

指标口径不能怎么做
PVpv 事件条数把 heartbeat 也算进去
UV去重后的 visitorId按 IP 去重,NAT 下会严重偏低
会话数去重后的 sessionId按天固定切分会话
平均停留leave 事件的 durationMs 平均先过滤 pv 再对所有事件求平均
跳出率只有 1 个 PV 的会话占比用 PV 总数除以会话数

最隐蔽的错误是停留时长的聚合顺序。durationMs 只出现在 leave 事件里,如果 SQL 写成:

SELECT path, AVG(duration_ms)
FROM stats_event
WHERE event_type = 'pv'
GROUP BY path;

那么参与平均的行全是 pv,duration_ms 为 NULL 或 0,页面排行的平均停留会恒为 0。正确做法是先按会话和页面聚合 leave,或者只对 event_type = 'leave' 求平均,再和 PV 排行关联。

SELECT path, AVG(duration_ms) AS avg_dwell
FROM stats_event
WHERE event_type = 'leave' AND duration_ms > 0
GROUP BY path;

看板的五个接口——概览、页面排行、渠道、设备、地域——应该共享同一套时间范围和过滤条件,否则同一段时间的 PV 在不同卡片上会对不上。

验证:一次访问应该产生哪些事件

操作期望事件
首次打开页面服务端 1 条 pv,客户端不发首屏 PV
点击站内链接1 个请求,含上一页 leave + 新页 pv
停留 30 秒1 条 heartbeat
切到后台 5 分钟1 条 leave,duration 约为前台停留时间
切回前台不发事件,重新计时
关闭标签页若之前没发过 leave,补 1 条;已发过则不重复

验证时看 Network 面板的请求体和 cookie,不要只看页面上的数字。数字是聚合结果,错了很难反推是采集、合并还是查询的问题。

边界与坑

预取可能被算成 PV。 只按 GET + text/html + 无扩展名 过滤,浏览器或框架预取的 HTML 也可能符合条件。需要更严格时,再检查 Purpose、Sec-Purpose 等请求头。

爬虫和监控会进入统计。 服务端采集不区分人机。对 PV 绝对值要求高时,要加 UA 过滤或独立的机器人规则。

keepalive 不是可靠投递。 它只保证请求在页面卸载时尽量发出,不保证到达。统计允许丢失,不要把它当计费数据。

会话 cookie 过期后,隐藏的标签页不会自动续期。 后台不发心跳,超过 30 分钟再回来会产生新会话。这是会话语义的自然结果,不是丢数据。

IP 不是用户。 同一个 NAT 后面可能有几百个访客;用 IP 算 UV 会严重偏低。IP 只适合做地域和风控参考。

看板查询要统一口径。 PV、UV、会话、停留来自不同事件类型,过滤条件必须一致。先过滤事件类型再聚合,是最容易写反的一步。

相关工具

排查上报里的 User-Agent 时,可以用 UA 解析工具 对照浏览器和爬虫标识;需要看请求链路时用 Traceparent 生成工具。更多自建服务和前端埋点的记录放在 技术笔记。

FAQ

为什么首屏 PV 要放在服务端记?

服务端在 HTML 渲染时就能拿到请求,不依赖 JavaScript 是否执行,也能直接读到 IP、UA 和 Referer。客户端再记一次会重复,刷新时尤其明显。

会话为什么要 30 分钟滑动续期?

固定过期会把持续阅读切成多段;滑动过期让活跃会话保持连续,停止访问 30 分钟后才结束。心跳和每次事件上报都会续期。

后台标签页为什么不算停留时长?

用户没有在看页面,算进去会虚高。页面隐藏时上报 leave,切回前台重新计时,停留只统计可见时间。

为什么页面排行的平均停留会是 0?

常见原因是 SQL 先过滤 event_type = 'pv',再对 duration_ms 求平均,而时长只存在于 leave 事件。应按 leave 聚合停留,再和 PV 关联。

自建统计不难在采集,难在事件边界:首屏只记一次、路由合并上报、隐藏即离开、聚合前分清事件类型。把这四条固定下来,PV 和停留才有解释力。

Comments

Sign in to join the discussion

No comments yet — be the first to say something

Related Articles