如何在 React 或 Vue 单页应用中跟踪分析数据

发布于 2025 年 3 月 12 日 • statpx 团队 • 6 分钟阅读

使用 React、Vue、Next.js 或 Nuxt 构建的单页应用 (SPA) 的工作方式与传统多页网站有根本区别。与为每次导航加载新的 HTML 页面不同，应用在原地更新 DOM，同时通过 History API 更改 URL。这为大多数分析脚本造成了一个问题：它们只在初始页面加载时运行，因此应用内的后续导航无法被跟踪。

为什么标准分析脚本在 SPA 中会失效

传统的分析脚本通过在 HTML 页面加载时执行、读取当前 URL 并发送页面浏览事件来工作。在多页网站中，每次点击新页面都会导致完整的页面加载，从而每次都触发该脚本。在 SPA 中，用户可以在不触发初始加载后的完整页面加载的情况下，浏览数十个"页面"。

结果是：如果在 React 应用中安装标准分析脚本，无论用户访问多少个路由，您都只会看到每个会话一次页面浏览（初始加载）。您的分析数据将几乎无用。

History API 问题

SPA 使用浏览器的 History API —— 特别是 history.pushState() 和 history.replaceState() —— 来在不触发页面重新加载的情况下更改 URL。有些还使用基于哈希的路由（/#/route）。不监听这些事件的分析工具将完全遗漏所有应用内导航。

SPA 感知分析跟踪的工作原理

适当的 SPA 分析跟踪通过拦截 History API 调用来工作。该脚本修补原生 history.pushState 和 history.replaceState 函数，并为 popstate 事件添加事件侦听器（由后退/前进按钮触发）。只要其中任何一个触发，脚本就会读取新 URL 并发送页面浏览事件。

某些分析工具还监听 hashchange 事件，以支持像 Vue Router 哈希模式这样的旧框架使用的基于哈希的路由。

最少实现

如果您正在构建自己的跟踪解决方案或需要手动检测不原生支持 SPA 的脚本，这是纯 JavaScript 中的核心模式：

// Patch pushState to detect SPA navigation
const _origPush = history.pushState.bind(history);
history.pushState = function(...args) {
  _origPush(...args);
  sendPageview(location.href);
};

// Also listen for back/forward navigation
window.addEventListener('popstate', () => {
  sendPageview(location.href);
});

function sendPageview(url) {
  // Send the current URL to your analytics endpoint
  fetch('/collect?url=' + encodeURIComponent(url));
}

特定于框架的注意事项

React 和 Next.js

在 React Router 中，路由更改触发 pushState，因此 History API 拦截方法效果很好。在 Next.js 中，您还可以使用 router.events API 来监听 routeChangeComplete 事件，如果您的分析脚本不能自动检测，请手动触发页面浏览调用。

Vue 和 Nuxt

Vue Router 也使用 pushState，因此 History API 拦截有效。在 Nuxt.js 中，类似的路由事件钩子也可用。如果您正在使用 SPA 感知的分析工具，通常无需配置任何内容 —— 它会自动处理。

使用自动处理 SPA 的分析工具

最简单的方法是使用已自动拦截 History API 事件的分析工具。您粘贴一次代码片段 —— 通常在根 HTML 模板或全局组件中 —— 它无需任何特定于框架的配置即可跟踪每个路由更改。

statpx 的跟踪脚本会自动修补 history.pushState 并监听 popstate 事件，为您提供 React、Vue、Next.js、Nuxt 和开箱即用的任何其他 SPA 框架中准确的按路由页面浏览跟踪。

SPA 分析，正常工作 —— 免费

statpx 在 React、Vue、Next.js 和任何 SPA 中自动跟踪导航。在您的 index.html 中粘贴一次代码片段，您就完成了。无需配置。

免费试试 →

验证您的 SPA 跟踪是否有效

安装分析脚本后，在浏览器中打开您的网站并在多个路由之间导航。然后检查您的分析仪表盘的实时视图。您应该会看到为您访问的每个路由记录的新页面浏览，而不仅仅是初始页面加载。如果您每个会话只看到一次页面浏览，您的跟踪脚本不支持 SPA 导航，您需要切换到支持的或添加上面的手动检测。

还要检查您的热门页面报告是否显示多个路由 —— 而不仅仅是根 URL 占据所有流量。如果每次访问似乎都着陆在 /，这是 SPA 导航未被跟踪的明确迹象。

总结

单页应用打破了分析工具所做的最基本假设 —— 即每次页面浏览都始于完整的页面加载。获取准确的 SPA 数据需要一个主动拦截 History API 事件而不是等待它们自然发生的跟踪器。如果您正在 React、Vue 或 Next.js 中构建，获得可靠路由级分析的最快方法是放入一个自动处理 pushState 和 popstate 的脚本，无需任何特定于框架的连接。statpx 的跟踪代码片段恰好做到这一点，所以您的热门页面报告从安装之时起就反映真实的用户导航。