Web Analytics 常见陷阱

# Web Analytics 常见问题 ## 关键问题 ### SPA 导航未被追踪 **症状：** 仅统计了初始页面加载 **修复：** 添加 `spa: true`： html ### CSP 阻止 Beacon **症状：** 控制台报错 "Refused to load script" **修复：** 允许以下两个域名： script-src 'self' https://static.cloudflareinsights.com https://cloudflareinsights.com; ### 不支持基于 Hash 的路由 **症状：** `#/path` 格式的 URL 无法被追踪 **修复：** 迁移至 History API（使用 `BrowserRouter` 而非 `HashRouter`）。Hash 路由目前无解决方案。 ### 数据未显示 **原因与修复：** 1. **延迟** - 等待 5-15 分钟 2. **Token 错误** - 确保与仪表板完全匹配 3. **脚本被拦截** - 在开发者工具的 Network 选项卡中检查 beacon.min.js 4. **域名不匹配** - 仪表板中的站点必须与实际 URL 匹配 ### 自动注入失败 **原因：** 存在 `Cache-Control: no-transform` 响应头 **修复：** 移除 `no-transform` 或手动安装 beacon ### 重复的页面浏览量 **原因：** 存在多个 beacon 脚本 **修复：** 每个页面仅保留一个 beacon ## 配置问题 | 问题 | 修复 | |-------|-----| | 达到 10 个站点限制 | 删除旧站点或通过 CF 代理（无限制） | | Token 无法识别 | 使用仪表板中提供的精确字母数字 Token | ## 框架特定说明 ### Next.js 水合警告 (Hydration Warning) tsx ### Gatsby Window 未定义 使用 `gatsby-browser.js` 仅在客户端加载。 ## 限制 | 资源 | 限制 | |----------|-------| | 非代理站点 | 10 | | 代理站点 | 无限制 | | 数据保留期 | 6 个月 | | 数据摄入延迟 | 5-10 分钟 | | API 访问 | 无（仅限仪表板） | ## 何时不应使用 Web Analytics 如果需要以下功能，请使用替代方案： - 自定义事件追踪 - 实时数据 - 用户级追踪 - 转化漏斗 - 数据导出/API 访问 **Web Analytics 的优势：** 核心网页指标 (Core Web Vitals)、基础流量统计、隐私合规、免费且无限制的页面浏览量统计。