分析统计

🏗️ 分析系统架构

NEXTDEVKIT 的分析系统结构如下：

src/
├── config/
│   └── analytics.ts              # 分析提供商配置
├── components/
│   └── shared/
│       └── cookie/
│           ├── cookie-consent.tsx           # Cookie 同意组件
│           └── cookie-consent-config.ts     # 同意配置
├── app/
│   └── [locale]/
│       └── layout.tsx             # 布局中的分析集成
└── lib/
    └── metadata.ts                # SEO 元数据集成

⚙️ 分析配置

分析提供商

分析提供商在 src/config/analytics.ts 中配置：

src/config/analytics.ts

const analyticsConfig: AnalyticsConfig = {
	google: {
		enabled: !!process.env.NEXT_PUBLIC_GOOGLE_ANALYTICS_ID,
		label: "Google Analytics",
		config: {
			trackingId: process.env.NEXT_PUBLIC_GOOGLE_ANALYTICS_ID,
		},
		onAccept: () => {
			// Google Analytics 初始化代码
		},
	},
	umami: {
		enabled: !!process.env.NEXT_PUBLIC_UMAMI_WEBSITE_ID,
		label: "Umami Analytics",
		config: {
			url: process.env.NEXT_PUBLIC_UMAMI_SCRIPT_URL,
			websiteId: process.env.NEXT_PUBLIC_UMAMI_WEBSITE_ID,
		},
		onAccept: () => {
			// Umami Analytics 初始化代码
		},
	},
	plausible: {
		enabled: !!process.env.NEXT_PUBLIC_PLAUSIBLE_DOMAIN,
		label: "Plausible Analytics",
		config: {
			domain: process.env.NEXT_PUBLIC_PLAUSIBLE_DOMAIN,
			src: process.env.NEXT_PUBLIC_PLAUSIBLE_SCRIPT_URL,
		},
		onAccept: () => {
			// Plausible Analytics 初始化代码
		},
	},
};

环境变量

为您的分析提供商设置所需的环境变量：

.env

# Google Analytics
NEXT_PUBLIC_GOOGLE_ANALYTICS_ID=G-XXXXXXXXXX

# Umami Analytics
NEXT_PUBLIC_UMAMI_WEBSITE_ID=your-website-id
NEXT_PUBLIC_UMAMI_SCRIPT_URL=https://analytics.umami.is/script.js

# Plausible Analytics
NEXT_PUBLIC_PLAUSIBLE_DOMAIN=yourdomain.com
NEXT_PUBLIC_PLAUSIBLE_SCRIPT_URL=https://plausible.io/js/script.js

📈 分析提供商设置

Google Analytics 设置

创建 Google Analytics 账户：
- 访问 analytics.google.com
- 创建新属性
- 获取您的测量 ID（以 "G-" 开头）

环境变量：

NEXT_PUBLIC_GOOGLE_ANALYTICS_ID=G-XXXXXXXXXX

Umami Analytics 设置

创建 Umami 账户：
- 访问 umami.is 或设置自托管实例
- 创建新网站
- 获取您的网站 ID 和脚本 URL

环境变量：

NEXT_PUBLIC_UMAMI_WEBSITE_ID=your-website-id
NEXT_PUBLIC_UMAMI_SCRIPT_URL=https://cloud.umami.is/script.js

Plausible Analytics 设置

创建 Plausible 账户：
- 访问 plausible.io 或设置自托管实例
- 添加您的网站
- 获取您的域名和脚本 URL

环境变量：

NEXT_PUBLIC_PLAUSIBLE_DOMAIN=yourdomain.com
NEXT_PUBLIC_PLAUSIBLE_SCRIPT_URL=https://plausible.io/js/script.js

NEXTDEVKIT 与 vanilla-cookieconsent 集成，提供符合 GDPR 的 Cookie 管理：

src/components/shared/cookie/cookie-consent.tsx

'use client';

import { useEffect } from 'react';
import * as CookieConsent from 'vanilla-cookieconsent';
import 'vanilla-cookieconsent/dist/cookieconsent.css';
import getConfig from './cookie-consent-config';

const CookieConsentComponent = () => {
  useEffect(() => {
    const initCookieConsent = async () => {
      await CookieConsent.run(getConfig());
    };

    initCookieConsent().catch(console.error);
  }, []);

  return <></>;
};

export default CookieConsentComponent;

同意配置自动与您的分析提供商集成：

src/components/shared/cookie/cookie-consent-config.ts

import { getEnabledAnalytics, hasEnabledAnalytics } from "@/config/analytics";

const getConfig = () => {
  const enabledAnalytics = getEnabledAnalytics();
  const hasAnalytics = hasEnabledAnalytics();

  // 根据启用的分析动态构建服务对象
  const analyticsServices: Record<string, any> = {};

  Object.entries(enabledAnalytics).forEach(([key, provider]) => {
    analyticsServices[key] = {
      label: provider.label,
      onAccept: provider.onAccept,
    };
  });

  return {
    categories: {
      necessary: {
        enabled: true,
        readOnly: true,
      },
      ...(hasAnalytics && {
        analytics: {
          autoClear: {
            cookies: [
              { name: /^_ga/ },      // Google Analytics
              { name: "_gid" },      // Google Analytics
              { name: "__plausible" }, // Plausible
            ],
          },
          services: analyticsServices,
        },
      }),
    },
    // ... 其余配置
  };
};

布局集成

分析集成到主布局中：

src/components/shared/providers.tsx

export async function AppProviders({
	children,
	locale,
}: PropsWithChildren<{ locale: string }>) {
	const defaultMode = appConfig.ui.theme.defaultMode;

	return (
		<html lang={locale} suppressHydrationWarning>
			<body
				className={`${geistSans.variable} ${geistMono.variable} antialiased min-w-screen overflow-x-hidden`}
			>
				// 其他提供商
				{children}
			</body>
			<CookieConsentComponent />
		</html>
	);
}

🔧 故障排除

常见问题

分析未加载：

检查环境变量是否正确设置
验证 Cookie 同意已被接受
检查浏览器控制台中的 JavaScript 错误
确保分析脚本未被广告拦截器阻止

Cookie 同意未显示：

验证 hasEnabledAnalytics() 返回 true
检查是否已给予同意
确保 Cookie 同意组件已正确导入

事件未跟踪：

验证分析提供商已正确初始化
检查是否已给予分析 Cookie 同意
确保事件跟踪函数被正确调用

🔗 相关资源

🎯 下一步

现在您了解了分析系统，请探索这些相关功能：

🎨 主题
🔍 SEO
📚 文档

On this page