【免费下载链接】analyticsjs-boilerplate
Examples and best practices for using analytics.js
analyticsjs-boilerplate 是一套面向 Google Analytics 的 analytics.js 最佳实践模板项目，专治前端"数据漏报"：它能完整捕获页面上抛出的 JavaScript 错误（包括埋点代码初始化之前发生的错误），并配合 beacon 传输、自定义维度与页面性能指标，把 JavaScript 错误追踪做成一条完整的数据链路。本文带你用最小的代码量，搭出一套可靠的前端错误上报方案。
🤔 为什么错误总会漏报？analytics.js 的 3 个盲区
很多开发者贴一段官方标准 snippet 就以为"埋点完成"了，但真实生产环境里，错误数据总在这 3 个环节流失：
| 盲区 | 表现 | 根本原因 |
|---|---|---|
| 早期错误 | 埋点代码加载完成前抛出的错误"人间蒸发" | 监听代码挂载太晚，错误发生时没人记录 |
| 请求丢失 | 用户一刷新/关闭页面，错误数据就没了 | 普通请求在页面卸载时被浏览器中断 |
| 维度缺失 | 报表看着有数，但没法切分定位问题 | analytics.js 会直接丢弃维度值为空的 hit |
analyticsjs-boilerplate 逐一解决了这三个问题。全部实现位于 src/analytics/ 目录下，按能力递进拆成了 3 个版本。
🧩 三套模板能力递进：按需选择你的版本
| 版本 | 文件 | 能力 |
|---|---|---|
| 基础版 | base.js | 未捕获错误追踪、自定义维度、初始 pageview、页面加载性能事件 |
| Autotrack 版 | autotrack.js | 在基础版上叠加 5 个插件：URL 清洗、最大滚动、外链、页面可见性、URL 变化（见 autotrack.js） |
| 多追踪器版 | multiple-trackers.js | 在 Autotrack 版上支持 prod/test 双 tracker 并行，先验证测试数据再进生产 |
入口文件 src/index.js 默认以异步方式懒加载追踪代码，不阻塞站点关键功能；想切换版本时，只需替换其中 import() 的路径即可。
🔍 核心拆解：JavaScript 错误的全链路追踪怎么做
第 1 步：先"抓住"初始化前的错误
关键手法在 index.html：页面一打开就用一行内联脚本捕获 error 事件，并把事件存入 window.__e 队列。这样即使错误发生在埋点代码加载之前，也一个都不会溜走。
第 2 步：回放历史错误，再监听未来错误
base.js 中的 trackErrors() 函数做了两件事：
- 回放：遍历
window.__e.q队列里暂存的每个历史错误事件，补报出来； - 监听：通过
window.addEventListener('error', ...)接管后续所有新错误。
它对没有 event.error 对象的老旧浏览器也做了优雅降级——用 message + 行号:列号 拼出位置信息。单测 base-test.js 正是模拟了这个场景并逐条断言上报内容。
第 3 步：把错误变成可查询的报表事件
base.js 导出的 trackError() 函数把错误名写入 eventAction、消息与堆栈写入 eventLabel，让你在报表中直接按错误类型切分：
- 未捕获错误使用
Uncaught Error类别； - 手动上报的错误使用
Error类别。
更贴心的是 trackError 是公开 API，业务代码里一行 fetch('/api.json').catch(trackError)，异步请求的失败也能进报表。
隐藏关键：beacon 传输保证送达
base.js 通过 transport: 'beacon' 让所有 hit 都走 navigator.sendBeacon()。这条通道不受页面跳转、关闭的影响——这正是"全链路"的最后一公里，否则抓到的错误可能在传输途中被丢弃。
📊 不止报错误：自定义维度让数据可筛选
base.js 中定义了 8 个自定义维度（追踪版本号、客户端 ID、窗口 ID、hit ID、hit 时间、hit 类型、来源、页面可见性）和 3 个自定义指标（响应结束、DOM 就绪、窗口加载），并且给所有维度都设了 (not set) 默认值，避免空值导致报表丢行。
buildHitTask 钩子（见 base.js）会在每次 hit 发送前自动补记一整套上下文，方便你事后核对"哪条 hit、何时、以什么状态发出"。
🚀 三步在本地跑起来：新手快速上手
# 1. 获取项目
git clone https://gitcode.com/gh_mirrors/an/analyticsjs-boilerplate.git
cd analyticsjs-boilerplate
# 2. 安装依赖
npm install
# 3. 启动本地开发服务
npm start
然后在浏览器打开 localhost:8080，打开开发者控制台，就能看到 analytics.js 一条条输出的调试 hit（本地演示加载的是 analytics_debug.js，部署生产前记得换回 analytics.js，见 index.html 的注释提醒）。
💡 项目使用 webpack 与 webpack-dev-server 构建，配置见 webpack.config.js；基于 Mocha 的单元测试在 test/analytics/ 目录，可作为你验证埋点正确性的参考写法。
🎯 选哪个版本？一张表快速决策
| 你的场景 | 推荐版本 |
|---|---|
| 只需要错误追踪 + 基础数据 | base.js，代码量小、一遍读完 |
| SPA 或想要自动页面/滚动/外链追踪 | autotrack.js |
| 多环境发布、想先验证数据 | multiple-trackers.js，用 ALL_TRACKERS 统一管理 prod 与 test 追踪器，gaProd / gaTest 代理函数可按环境分流上报 |
✅ 写在最后
analyticsjs-boilerplate 用 3 个可直接套用的模板告诉我们：JavaScript 错误全链路追踪的关键，是先捕获错误、后挂载追踪，再用 beacon 传输兜底送达，最后靠自定义维度让每条数据可定位、可筛选。如果你的网站报表一直"差那么一点"，不妨按上面的三步在本地跑起 demo，对照 README 逐个版本体验，漏报问题基本都能迎刃而解。
【免费下载链接】analyticsjs-boilerplate
Examples and best practices for using analytics.js
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
