Cloudflare Web Analytics 配置完全指南：代理站点自动注入、手动 Beacon 与 SPA 埋点实战

【免费下载链接】autoskillsOne command. Your entire AI skill stack. Installed.项目地址https://gitcode.com/gh_mirrors/au/autoskills点击查看免费下载本文基于 autoskills 技能仓库中 cloudflare-deploy 下的 Web Analytics 配置文档整理而成。作为一站式部署 Cloudflare 平台的技能参考涵盖 Workers、Pages、D1、R2、WAF 等产品其中 Web Analytics 部分专门解决站点流量与 Core Web Vitals 监控如何配置这一实战问题。读完本文你将掌握代理站点自动注入与外部站点手动 Beacon 两种接入方式、SPA 路由追踪的spa: true配置、CSP 兼容写法、令牌管理、安装验证与数据保留规则并了解其底层实现约束无 API、仅仪表盘展示等。什么是 Cloudflare Web AnalyticsCloudflare Web Analytics 是 Cloudflare 提供的一套隐私优先的 Web 分析方案在 cloudflare-deploy 技能中被归类为 Developer Tools 之一。它的核心定位是Core Web Vitals 监控LCP最大内容绘制、FID/INP交互延迟、CLS布局偏移、TTFB首字节时间等性能指标流量统计页面浏览Page Views、访问Visits、来源 Referrer 与路径分布且全程不使用 Cookie用户画像按设备、浏览器、操作系统、国家地区拆分访客构成隐私合规无 Cookie、无指纹识别、不采集 PII个人身份信息IP 地址不存储天然适配 GDPR/CCPA 场景免费且无上限不限页面浏览量pageviews。与常见的第三方统计不同Web Analytics 有一个关键约束——仅通过仪表盘Dashboard查看数据不存在任何编程式数据访问 API也没有实时数据通常有 5~10 分钟延迟。这一点贯穿了后续所有配置决策。接入方式总览Proxied 与 Non-Proxied 二选一配置 Web Analytics 的第一步是判断站点是否被 Cloudflare 代理即 DNS 是否走 Cloudflare橙色云朵开启。两种方式的能力与限制差异如下站点类型说明Beacon 注入方式站点数量限制Proxied代理DNS 通过 Cloudflare橙色云朵自动注入或手动不限Non-Proxied非代理外部托管、仅用 Cloudflare 统计仅手动每账号最多 10 个决策路径可以概括为Is your site proxied through Cloudflare? ├─ YES → 使用自动注入Dashboard 开启即可通常无需改代码 └─ NO → 手动接入 beacon需把 JS 片段加入 HTML详细的分支指引参见 web-analytics/README.md。方式一Proxied 站点自动注入对于已经通过 Cloudflare 代理的站点配置路径极短Dashboard → Web Analytics → Add site → Select hostname → Done随后进入注入选项Injection Option选择共四个档位注入选项说明Enable对所有访客自动注入 beacon默认Enable, excluding EU不对欧盟EU访客注入用于 GDPR 合规Enable with manual snippet关闭自动注入由你手动放置 beacon 脚本Disable暂停统计追踪自动注入的两个失败条件即使开启自动注入也存在两类会导致注入失败或行为异常的情况需要提前排查响应头Cache-Control: public, no-transform当源站响应包含该头时自动注入会失败。Cloudflare 出于缓存语义不会改写这类响应。解决方式是移除no-transform或者改用手动 Beacon 方案。这是文档明确标注的失败条件部署到 Cloudflare 的站点若命中此情况应优先检查响应头。CSP内容安全策略限制若站点配置了 CSP必须放行 Cloudflare 的统计脚本域否则浏览器会拦截 beacon 加载控制台报 Refused to load scriptscript-src https://static.cloudflareinsights.com https://cloudflareinsights.com;注意需要同时放行两个域名static.cloudflareinsights.com脚本托管域与cloudflareinsights.com数据上报域。更完整的写法通常还会显式包含self并可拆分为script-src与connect-src两条指令见下文手动接入章节。方式二Non-Proxied 站点手动接入站点未接入 Cloudflare DNS例如托管在 Vercel、自有服务器等外部环境时只能手动放置 beacon。操作路径Dashboard → Web Analytics → Add site → Enter hostname → Copy snippet将生成的片段放入 HTML推荐放在/body闭合标签之前script defer srchttps://static.cloudflareinsights.com/beacon.min.js >{ token: YOUR_TOKEN, spa: true }每个站点拥有唯一 token务必与仪表盘中显示的内容逐字符一致token 属于站点域绑定domain-locked标识不是密钥可以安全地直接暴露在 HTML 中正因为如此它也不适合承载权限语义。SPA 模式现代前端框架追踪的关键开关spa字段是手动接入时最关键的开关直接决定客户端路由跳转是否会被统计。场景推荐值原因React Router、Next.js、Vue Router、Nuxt、SvelteKit、Angularspa: true客户端路由导航也要计入 PV传统多页应用、静态站点、WordPressspa: false每次导航即整页加载无需额外追踪不开启spa: true的后果对于 React/Vue 等 SPA只有首次整页加载会被记录所有客户端路由切换产生的页面访问全部丢失——这是文档与 gotchas.md 中反复强调的头号问题症状只有 initial pageload 计数。一个重要限制Hash 路由#/path形式不被支持。Web Analytics 只监听 History API 的pushState/replaceState。若站点使用HashRouter唯一的解决方式是迁移到 History API 路由如BrowserRouter文档明确说明 hash 路由没有 workaround。各框架的 beacon 放置位置手动接入时不同框架的注入位置差异很大详见 integration.md核心场景如下框架放置位置备注React / Vitepublic/index.html需开启spa: trueNext.js App Routerapp/layout.tsx用Script strategyafterInteractiveNext.js Pages Routerpages/_document.tsx使用ScriptNuxt 3app.vue配合useHead()或用 pluginVue 3 / Viteindex.html需开启spa: trueGatsbygatsby-browser.js在onClientEntryhook 中加载SvelteKitsrc/app.html放在/body前AstroLayout 组件放在/body前Angularsrc/index.html需开启spa: trueDocusaurusdocusaurus.config.js放入scripts数组Next.js 场景下若遇到 hydration 警告可在Script上补充suppressHydrationWarningGatsby 场景则必须借助gatsby-browser.js保证只在客户端加载避免 SSR 阶段window未定义。CSP 与手动接入的完整兼容写法手动接入下CSP 可拆成更精细的两条指令分别管控脚本加载与数据上报script-src self https://static.cloudflareinsights.com; connect-src self https://cloudflareinsights.com;script-src允许从static.cloudflareinsights.com加载beacon.min.jsconnect-src允许浏览器向cloudflareinsights.com发起数据上报请求。如果两条域名都未放行控制台会出现 CSP 拦截错误仪表盘将长期无数据。排查时优先看 DevTools Network 面板中beacon.min.js与数据请求是否出现、是否有红色 CSP/CORS 报错。Token 管理与多环境配置Token 从哪来token 位于Dashboard → Web Analytics → Manage site每个站点独立生成。需要注意token 是域锁定的绑定站点域名它不是密钥Not secrets可以安全地写进 HTML 源码若 token 未被识别请核对是否与仪表盘中的字母数字串完全一致不能手输、不要带多余空格。按环境区分加载生产环境才加载 beacon 是最常见的实践// Only load in production if (process.env.NODE_ENV production) { // Load beacon }也可以为不同环境使用不同 token环境变量方案const token process.env.NEXT_PUBLIC_CF_ANALYTICS_TOKEN; // .env.production: production token // .env.staging: staging token或留空以禁用这样能实现staging 与 production 分离统计例如 staging 环境使用独立 token 甚至不加载避免测试流量污染生产数据。GDPR 场景的条件加载若需要先获得用户同意再加载统计脚本可改为动态创建 script 节点if (localStorage.getItem(analytics-consent) true) { const script document.createElement(script); script.src https://static.cloudflareinsights.com/beacon.min.js; script.defer true; script.setAttribute(data-cf-beacon, {token: YOUR_TOKEN, spa: true}); document.body.appendChild(script); }更简单的替代方案是在 Dashboard 中直接选择 Enable, excluding EU不对欧盟访客注入详见 patterns.md。安装验证清单完成配置后按以下三步确认 beacon 已正常工作Network 面板验证打开 DevTools → Network过滤关键字cloudflareinsights应能看到beacon.min.js脚本及其后的数据上报请求控制台无报错确认没有 CSP / CORS 相关的红色错误仪表盘出数Dashboard 中通常在5~10 分钟延迟后才出现 pageviews刚配置完看不到数据属于正常现象无需立即怀疑配置错误。如果长期无数据按 gotchas.md 提供的顺序排查等待延迟 → 核对 token → 检查脚本是否被拦 → 核对站点域名是否与真实 URL 一致若页面中重复放置了多个 beacon 脚本还会造成 pageviews 重复计数应保证每页只有一个 beacon。高级规则Sample Rate / Path / Host视套餐而定Web Analytics 提供规则Rules能力在 Dashboard 中按需配置但可用性取决于 Cloudflare 套餐——免费套餐可能受限或不可用请以仪表盘Web Analytics → Rules中的实际显示为准Sample Rate采样率降低高流量站点的采集比例。例如只追踪 50% 的访客以减小数据量Path-based基于路径按路由差异化行为。例如排除/admin/*、/internal/*等内部路径的统计Host-based基于主机多域名场景下分开统计。例如 staging 与 production 子域名各自独立追踪。数据保留与产品边界Web Analytics 的数据保留策略非常明确保留周期6 个月滚动窗口rolling window粒度1 小时桶1-hour bucket granularity导出不支持原始数据导出仅仪表盘展示。结合 gotchas.md 与 patterns.md其能力边界可以概括为一张该用 / 不该用对照表需求结论Core Web Vitals 监控、基础流量统计、隐私合规、免费无限 PV✅ Web Analytics 的强项自定义事件追踪、实时数据、用户级追踪、转化漏斗、数据导出/API 访问❌ 需改用其他分析方案其他已知限制还包括无 UTM 参数追踪、无 webhook/告警、无自定义 beacon 域名、不支持 Hash 路由、不支持会话录制与表单追踪。此外广告拦截器可能屏蔽cloudflareinsights.com文档估计约 25%~40% 的用户受影响且无官方 workaround因此 Dashboard 数据应视为基线下限完整流量请结合服务器日志交叉核对。常见故障速查表问题原因修复SPA 路由切换不计数未开spa: truedata-cf-beacon中加spa: true控制台 Refused to load scriptCSP 未放行加入static.cloudflareinsights.com与cloudflareinsights.com#/path路由不统计Hash 路由不支持迁移至 History APIBrowserRouter自动注入失败响应含Cache-Control: public, no-transform移除该头或改手动 beacon页面一直无数据延迟/错误 token/脚本被拦/域名不匹配依次核对 5~15 分钟延迟、token、Network 面板、站点域名pageviews 重复计数页面存在多个 beacon每页只保留一个 beacon10 个非代理站点配额已满免费套餐上限删除旧站点或改走 Cloudflare 代理不限量在 autoskills 技能体系中的定位在 autoskills 的 Cloudflare Deploy 技能中Web Analytics 属于 Developer Tools 类别与 Wrangler、Analytics Engine、Observability 并列见 SKILL.md 的 Product Index。该技能的设计思路是先用决策树判断需求归属再加载对应产品参考文档。当需求涉及站点流量监控、性能指标LCP/INP/CLS、GDPR 合规统计时即可切入本配置指南若需要更接近底层的事件型分析如 Worker 内埋点则应转向 analytics-engine 参考。二者定位不同Web Analytics 面向站点访问者侧的页面统计Analytics Engine 面向开发者自定义事件写入与查询。相关文档导航接入方式决策树与功能总览web-analytics/README.md本文Proxied/Non-Proxied 配置、SPA、Token、验证、规则、数据保留web-analytics/configuration.md各前端框架的 Beacon 集成代码web-analytics/integration.md常见故障排查web-analytics/gotchas.md性能优化与 GDPR、多环境等实战模式web-analytics/patterns.md赞分享【免费下载链接】autoskillsOne command. Your entire AI skill stack. Installed.项目地址https://gitcode.com/gh_mirrors/au/autoskills点击查看免费下载相关推荐Cloudflare Web Analytics 实战模式Core Web Vitals 调试、GDPR 合规与 SPA 埋点最佳实践Cloudflare Web Analytics 实战模式Core Web Vitals 调试、GDPR 合规与 SPA 埋点最佳实践 Cloudflare人工智能AI 技能AI 插件Cloudflare Analytics Engine API 实战指南writeDataPoint 埋点写入与 SQL 查询分析autoskills Cloudflare SkillCloudflare Analytics Engine API 实战指南writeDataPoint 埋点写入与 SQL 查询分析autoskills ClAmplitude Analytics Python SDK 服务端埋点实战指南amplitude-analytics 1.2.0Amplitude Analytics Python SDK 服务端埋点实战指南amplitude analytics 1.2.0 导读 本文以 Conte上一篇如何让老旧安卓电视流畅播放高清直播MyTV-Android轻量级解决方案详解下一篇告别网盘限速困扰8大主流平台直链解析工具深度解析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考