数据统计

概览

01MVP 内置了多统计服务的支持，采用模块化架构。默认保留轻量的第三方统计入口，可选接入 Google Analytics、百度统计和 Umami，通过环境变量切换。

Google Analytics — 全功能流量分析，通过 NEXT_PUBLIC_GOOGLE_ANALYTICS_ID 启用
百度统计 — 面向国内用户的流量分析，通过 NEXT_PUBLIC_BAIDU_ANALYTICS_ID 启用
Umami — 开源、隐私友好的统计方案，通过 NEXT_PUBLIC_UMAMI_WEBSITE_ID 启用

不配置统计环境变量时，模板不会注入额外统计脚本。域名已经接入 Cloudflare 时，可以先使用 Cloudflare Web Analytics。

环境变量

变量名	说明	何时使用
`NEXT_PUBLIC_GOOGLE_ANALYTICS_ID`	Google Analytics 4 衡量 ID	接入 Google Analytics 时
`NEXT_PUBLIC_BAIDU_ANALYTICS_ID`	百度统计站点 ID	接入百度统计时
`NEXT_PUBLIC_UMAMI_WEBSITE_ID`	Umami 网站 ID	接入 Umami 时
`NEXT_PUBLIC_UMAMI_SCRIPT_URL`	Umami 脚本地址（可选）	自托管 Umami 时填写，默认使用 `https://cloud.umami.is/script.js`

自定义事件追踪

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

"use client";

import { useAnalytics } from "@/modules/analytics";

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

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

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

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

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

统计服务优先级

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

NEXT_PUBLIC_GOOGLE_ANALYTICS_ID（优先）
NEXT_PUBLIC_BAIDU_ANALYTICS_ID（次选）
无：useAnalytics 返回空操作

优先级逻辑会影响 AnalyticsScript 和 useAnalytics 的目标。需要多平台同时上报时，建议新增组合 provider，而不是在页面里手动插多个脚本。

架构说明

统计模块位于 apps/01mvp-web/src/modules/analytics/，结构如下：

modules/analytics/
  index.tsx            # 统一入口，环境变量选择 provider
  provider/
    google/index.tsx   # Google Analytics 实现
    baidu/index.tsx    # 百度统计实现
    umami/index.tsx    # Umami 实现

每个 provider 导出两个函数：