数据分析

🚀 Cheatsheet (快速上手)

目标: 5 分钟内启用 Umami 统计并开始追踪关键事件

# 1. 在 Umami 后台创建网站，复制 website id (UUID)
echo 'NEXT_PUBLIC_UMAMI_WEBSITE_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' >> .env.local

# 2. 如果使用自建 Umami，可覆盖脚本地址
echo 'NEXT_PUBLIC_UMAMI_SCRIPT_URL=https://analytics.example.com/script.js' >> .env.local

立即生效: 重新启动应用后，src/components/shared/Providers.tsx 中的 <AnalyticsScript /> 会自动加载 Umami 脚本并开始记录访问数据。

事件追踪示例:

import { useAnalytics } from "@analytics";

const { trackEvent } = useAnalytics();
trackEvent("signup_success", { source: "landing_page" });

🤔 我们的分析方案

默认提供商是 Umami，兼顾隐私与易用性。
若未设置 Umami，会按顺序回退到 Google Analytics 或百度统计。
所有提供商通过 @analytics 暴露统一的 AnalyticsScript 和 useAnalytics API，调用方式一致。

| 文件 | 作用 | | --- | --- | | src/modules/analytics/index.tsx | 读取环境变量、确定当前提供商、导出统一 API。 | | src/modules/analytics/provider/umami/index.tsx | 加载 Umami 脚本，封装 window.umami.track。 | | src/modules/analytics/provider/google/index.tsx | 使用 @next/third-parties/google 接入 GA4。 | | src/modules/analytics/provider/baidu/index.tsx | 注入百度统计脚本并封装 _hmt 事件。 | | src/components/shared/Providers.tsx | 在应用根部渲染 <AnalyticsScript />，配合 Cookie 同意组件。 |

"use client";

import { useAnalytics } from "@analytics";

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

  return (
    <button
      onClick={() => {
        trackEvent("signup_clicked", {
          plan: "pro",
          source: "pricing",
        });
      }}
    >
      注册账号
    </button>
  );
}

⚙️ 提供商配置

Umami (默认推荐)

环境变量
- NEXT_PUBLIC_UMAMI_WEBSITE_ID: 必填，Umami 后台提供。
- NEXT_PUBLIC_UMAMI_SCRIPT_URL: 选填，自建实例脚本地址，默认 https://cloud.umami.is/script.js。
加载方式: 脚本通过 defer 属性插入，不阻塞页面渲染。
事件模型: trackEvent(name, data) 调用 window.umami.track(name, data)。

Google Analytics 4

环境变量: NEXT_PUBLIC_GOOGLE_ANALYTICS_ID (例如 G-XXXXXXXXXX)。
依赖: 使用 Next.js 官方的 @next/third-parties/google，自动处理脚本加载与事件上报。
事件模型: trackEvent(name, data) 映射到 sendGAEvent，与 GA4 推荐事件格式一致。

百度统计

环境变量: NEXT_PUBLIC_BAIDU_ANALYTICS_ID。
加载方式: 通过 next/script 注入 _hmt，加载策略为 afterInteractive。
事件模型: trackEvent(name, data) 会执行 _hmt.push(['_trackEvent', category, action, label, value])。
- 建议传递 data.category、data.label、data.value 以获得更完整的报表。

🎯 推荐追踪事件

signup_started / signup_success: 注册漏斗
project_created: 核心产品成功指标
payment_completed: 付费转化
feature_used: 记录功能使用情况（配合 feature 字段）
share_clicked: 社交裂变 / 推广行为

使用统一 API 后，事件会自动发送到当前启用的分析平台，无需重复编写代码。

🆘 常见问题

没有任何数据?
- 检查 .env.local 是否写入了正确的 NEXT_PUBLIC_* 环境变量。
- 确认部署环境也注入了相同配置。
- 在浏览器控制台查看 window.umami 或 window._hmt 是否存在。
需要在特定环境禁用统计?
- 清空对应环境变量即可，AnalyticsScript 会自动返回 null。
想要基于 Cookie 同意后再加载?
- 将 <AnalyticsScript /> 包裹在自定义的同意逻辑中即可。目前 ConsentProvider 默认允许追踪，如需严格合规可调整对应逻辑。

📎 延伸阅读

下一步: 设置完分析后，可以继续阅读监控指南了解性能与错误监控的落地方案。

数据分析

🚀 Cheatsheet (快速上手)

🤔 我们的分析方案

🧱 模块结构总览

🧠 核心 API 与使用方式

1. 注入统计脚本

2. 手动事件追踪