统计与分析

概览

Muse 的统计分两层：

• 站点访问统计：看有没有人访问、来源从哪里来、哪些页面有人看、真实用户页面性能如何。
• 应用内事件统计：看用户点击了什么、是否注册、是否购买、是否完成上传、AI 生成等关键动作。

如果域名已经接入 Cloudflare，早期优先使用 Cloudflare Web Analytics。它不需要先改业务代码，也不需要配置 VITE_* 环境变量。等产品开始有注册、付费、上传、AI 生成等关键动作，再接入 GA4、百度统计、Umami 或其他应用内事件统计工具。

怎么选

Cloudflare Web Analytics

Muse 默认推荐 Zeabur + Cloudflare。应用跑在 Zeabur，Cloudflare 作为域名入口、HTTPS、WAF 和轻量统计层。

Muse 使用 TanStack Router，不是 hash 路由。Cloudflare Web Analytics 可以自动跟踪基于 History API 的 SPA 路由变化，所以文档页、登录页、后台页之间的前端跳转也能记录为页面访问。

如果网站没有设置 CSP，可以不管这一项。Muse 模板默认带 CSP 安全头，已经在 script-src 放行 https://static.cloudflareinsights.com。小橙云自动注入时，数据会上报到当前域名下的 /cdn-cgi/rum，模板现有的 connect-src 'self' 已经覆盖。

只有 DNS-only 站点手动粘贴 Cloudflare snippet 时，才需要额外把 https://cloudflareinsights.com 加到 connect-src。

应用内统计

应用内统计可选接入 Google Analytics、百度统计和 Umami。Google Analytics 和百度统计通过环境变量切换；Umami 在代码里默认关闭，启用前需要先打开 provider 开关。没有配置统计环境变量时，应用不会注入对应统计脚本。

• Google Analytics — 全功能流量分析，通过 VITE_GOOGLE_ANALYTICS_ID 启用
• 百度统计 — 面向国内用户的流量分析，通过 VITE_BAIDU_ANALYTICS_ID 启用
• Umami — 开源、隐私友好的统计方案，先在 analytics-provider.tsx 打开 ENABLE_UMAMI_ANALYTICS，再配置 VITE_UMAMI_WEBSITE_ID

环境变量

自定义事件追踪

系统提供了统一的 useAnalytics hook，在组件中发送自定义事件：

"use client";

import { useAnalytics } from "@/shared/analytics/analytics-provider";

export function DownloadButton() {
  const { trackEvent } = useAnalytics();

  const handleClick = () => {
    trackEvent("download_click", { file: "guide.pdf" });
    // 开始下载...
  };

  return <button onClick={handleClick}>下载指南</button>;
}

useAnalytics 会根据当前启用的统计服务，自动将事件发送到对应的平台：

• Google Analytics — 使用 gtag("event", ...)
• 百度统计 — 使用 _hmt.push(['_trackEvent', ...])
• Umami — 使用 umami.track()
• 未配置任何服务 — trackEvent 为空操作，不报错

统计服务优先级

如果同时配置了多个统计 ID，系统按以下优先级选择一个统计服务：

1. VITE_GOOGLE_ANALYTICS_ID（优先）
2. VITE_BAIDU_ANALYTICS_ID（次选）
3. ENABLE_UMAMI_ANALYTICS + VITE_UMAMI_WEBSITE_ID（再次选）
4. 无：useAnalytics 返回空操作

Cloudflare Web Analytics 不在这个优先级里。它由 Cloudflare 在站点层注入或上报，不需要 VITE_* 环境变量，和应用内 provider 可以并存。

架构说明

统计模块位于 products/muse/apps/web/src/shared/analytics/，结构如下：

shared/analytics/
  analytics-provider.tsx   # 统一入口，环境变量选择 provider

当前实现集中在 analytics-provider.tsx，对外提供：

• AnalyticsScripts — 组件，渲染统计脚本标签
• useAnalytics — hook，返回 { trackEvent }

如需接入新的统计服务，先在这里新增 provider 选择逻辑，再按需要拆出单独文件。不要在页面里到处手动插脚本。

各统计服务接入指南

推荐接入顺序

对于 Muse 模板的早期项目，建议按阶段接入，不要一开始就装太多：

第一阶段（必须）：

• Google Search Console — 查看 Google 收录、搜索关键词、Core Web Vitals
• Cloudflare Web Analytics — 基础访问统计、来源、热门页面和真实用户性能

第二阶段（有注册/付费后）：

• Umami / GA4 / PostHog — 用户行为分析、转化漏斗和自定义事件

如果部署在 Zeabur 并通过 Cloudflare 代理，早期可以先用 Cloudflare Web Analytics + PageSpeed Insights；需要自定义事件再启用 Umami、GA4 或其他事件分析工具。

常见问题

要不要手动把 Cloudflare 脚本写进项目？

如果正式域名已经走 Cloudflare 代理，不需要。自动配置会把 beacon 注入 HTML 响应。

只有 DNS-only、没有走 Cloudflare 代理，或者你明确关闭自动注入时，才需要手动添加 Cloudflare 提供的 JS snippet。

为什么看到 /cdn-cgi/rum 的 405？

Cloudflare 的 RUM 端点只接受 beacon 发出的 POST 请求。浏览器地址栏、爬虫或测试工具用 GET 请求它时会返回 405。只要正常页面里的 beacon 上报成功，这类 405 通常不用当成应用错误。

相关资源

• Cloudflare Web Analytics: Enable Web Analytics
• Cloudflare Web Analytics: Data origin and collection
• Cloudflare Web Analytics for SPAs
• Cloudflare Web Analytics FAQ