企业官网建设流程全解析

本文基于 autoskills 技能仓库中 cloudflare-deploy 下的 Web Analytics 配置文档整理而成。作为一站式部署 Cloudflare 平台的技能参考（涵盖 Workers、Pages、D1、R2、WAF 等产品），其中 Web Analytics 部分专门解决"站点流量与 Core Web Vitals 监控如何配置"这一实战问题。读完本文，你将掌握代理站点自动注入与外部站点手动 Beacon 两种接入方式、SPA 路由追踪的spa: true配置、CSP 兼容写法、令牌管理、安装验证与数据保留规则，并了解其底层实现约束（无 API、仅仪表盘展示等）。

什么是 Cloudflare Web Analytics

Cloudflare 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（橙色云朵开启）。两种方式的能力与限制差异如下：

决策路径可以概括为：

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）选择，共四个档位：

自动注入的两个失败条件

即使开启自动注入，也存在两类会导致注入失败或行为异常的情况，需要提前排查：

1. 响应头Cache-Control: public, no-transform：当源站响应包含该头时，自动注入会失败。Cloudflare 出于缓存语义不会改写这类响应。解决方式是移除no-transform，或者改用手动 Beacon 方案。这是文档明确标注的失败条件，部署到 Cloudflare 的站点若命中此情况，应优先检查响应头。

2. CSP（内容安全策略）限制：若站点配置了 CSP，必须放行 Cloudflare 的统计脚本域，否则浏览器会拦截 beacon 加载（控制台报 "Refused to load script"）：

script-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 src='https://static.cloudflareinsights.com/beacon.min.js' >{ "token": "YOUR_TOKEN", "spa": true }

每个站点拥有唯一 token，务必与仪表盘中显示的内容逐字符一致；token 属于站点域绑定（domain-locked）标识，不是密钥，可以安全地直接暴露在 HTML 中（正因为如此，它也不适合承载权限语义）。

SPA 模式：现代前端框架追踪的关键开关

spa字段是手动接入时最关键的开关，直接决定客户端路由跳转是否会被统计。

不开启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，核心场景如下：

Next.js 场景下，若遇到 hydration 警告，可在<Script>上补充suppressHydrationWarning；Gatsby 场景则必须借助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.js；
• connect-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 已正常工作：

1. Network 面板验证：打开 DevTools → Network，过滤关键字cloudflareinsights，应能看到beacon.min.js脚本及其后的数据上报请求；
2. 控制台无报错：确认没有 CSP / CORS 相关的红色错误；
3. 仪表盘出数：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，其能力边界可以概括为一张"该用 / 不该用"对照表：

其他已知限制还包括：无 UTM 参数追踪、无 webhook/告警、无自定义 beacon 域名、不支持 Hash 路由、不支持会话录制与表单追踪。此外，广告拦截器可能屏蔽cloudflareinsights.com（文档估计约 25%~40% 的用户受影响，且无官方 workaround），因此 Dashboard 数据应视为基线下限，完整流量请结合服务器日志交叉核对。

常见故障速查表

在 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