analytics-script：React/Next.js 轻量级分析脚本库

analytics-script 是一个轻量级的 React/Next.js 分析脚本库，支持多种主流分析平台，包括 Plausible、Umami、Google Analytics、DataFast、Mixpanel、Crisp Chat 和 Microsoft Clarity。它提供了简洁的组件化 API，让开发者能够快速集成网站分析功能，无需处理复杂的脚本标签配置。

项目简介

analytics-script 是一个开源的 npm 包，由 iAmCorey 开发维护。截至目前，该项目在 GitHub 上已获得 11 stars，使用 TypeScript 编写。该项目的设计理念是简化分析工具的集成流程，让开发者能够通过简单的 React 组件就能接入各种分析服务。

核心特性

多平台支持：内置支持 Plausible、Umami、DataFast、Google Analytics、Mixpanel、Crisp Chat、Microsoft Clarity 等主流分析工具
环境变量配置：所有组件都支持通过环境变量进行配置，无需硬编码敏感信息
开发模式支持：提供 allowLocalhost 选项，方便在本地开发环境测试
TypeScript 支持：完整的类型定义，提供优秀的开发体验
轻量级：按需导入，只打包使用的组件
GDPR 合规：Google Analytics 组件支持 Consent Mode，便于实现 GDPR 合规

技术栈

TypeScript - 提供完整的类型支持
React - 基于 React 组件封装
Next.js - 完美支持 Next.js 应用

安装指南

使用 npm

bash

npm i analytics-script

使用 pnpm

bash

pnpm add analytics-script

快速开始

Plausible Analytics

标准用法（传统格式）

tsx

import { Plausible } from 'analytics-script';

<Plausible
  domain="yourdomain.com"
  scriptUrl="https://plausible.io/js/script.js"
/>

Props 说明：

domain - 网站域名（或通过环境变量 NEXT_PUBLIC_PLAUSIBLE_DOMAIN 设置）
scriptUrl - Plausible 脚本 URL（或通过环境变量 NEXT_PUBLIC_PLAUSIBLE_SCRIPT_URL 设置）
defer - 延迟加载脚本（默认：true）
allowLocalhost - 在开发环境启用（默认：false）

初始化格式（新版）

tsx

import { PlausibleInit } from 'analytics-script';

<PlausibleInit scriptUrl="https://plausible.io/js/pa-XXXXX.js" />

Umami

tsx

import { Umami } from 'analytics-script';

<Umami
  websiteId="your-website-id"
  scriptUrl="https://cloud.umami.is/script.js"
/>

DataFast

tsx

import { DataFast } from 'analytics-script';

<DataFast
  websiteId="your-website-id"
  domain="yourdomain.com"
  scriptUrl="https://datafa.st/js/script.js"
/>

Props 说明：

websiteId - DataFast 网站 ID
domain - 网站域名
scriptUrl - DataFast 脚本 URL
apiUrl - 自定义 API 端点（可选）
allowedHostnames - 跨域跟踪的额外域名列表（可选）
allowFileProtocol - 支持 file:// 协议（默认：false）
debug - 启用调试模式（默认：false）

Google Analytics

tsx

import { GoogleAnalytics } from 'analytics-script';

<GoogleAnalytics gtagId="G-XXXXXXXXXX" />

发送自定义事件：

tsx

import { sendGAEvent } from 'analytics-script';

<button onClick={() => sendGAEvent('button_click', { category: 'engagement' })}>
  Click me
</button>

GDPR 合规配置：

tsx

<GoogleAnalytics
  gtagId="G-XXXXXXXXXX"
  defaultConsent={{
    ad_storage: 'denied',
    ad_user_data: 'denied',
    ad_personalization: 'denied',
    analytics_storage: 'denied'
  }}
/>

Mixpanel

tsx

import { Mixpanel } from 'analytics-script';

<Mixpanel
  token="your-mixpanel-token"
  autocapture={true}
  record_sessions_percent={true}
/>

Crisp Chat

tsx

import { Crisp } from 'analytics-script';

<Crisp websiteId="your-crisp-website-id" />

Microsoft Clarity

tsx

import { Clarity } from 'analytics-script';

<Clarity projectId="your-clarity-project-id" />

使用示例

DataFast 自定义目标追踪

客户端追踪：

tsx

import { trackDataFastGoal } from 'analytics-script';

// 简单目标追踪
<button onClick={() => trackDataFastGoal('signup')}>
  Sign Up
</button>

// 带自定义参数的追踪
<button onClick={() => trackDataFastGoal('checkout_initiated', {
  name: 'Elon Musk',
  email: 'elon@x.com',
  product_id: 'prod_123',
})}>
  Checkout
</button>

服务端追踪：

tsx

import { trackDataFastGoalServer } from 'analytics-script';

// API 路由中使用
export async function POST(request: Request) {
  const { visitorId, goalName, metadata } = await request.json();

  const result = await trackDataFastGoalServer({
    apiKey: process.env.DATAFAST_API_KEY!,
    visitorId,
    goalName,
    metadata,
  });

  if (result.success) {
    return NextResponse.json({ success: true });
  } else {
    return NextResponse.json(
      { success: false, error: result.error },
      { status: 500 }
    );
  }
}

结合 Cookie 同意组件

使用 react-cookie-consent 实现 GDPR 合规：

tsx

import { GoogleAnalytics, updateGoogleConsent } from 'analytics-script';
import CookieConsent from 'react-cookie-consent';

export default function App() {
  return (
    <>
      <GoogleAnalytics
        gtagId="G-XXXXXXXXXX"
        defaultConsent={{ analytics_storage: 'denied' }}
      />
      <CookieConsent
        location="bottom"
        buttonText="Accept"
        declineButtonText="Decline"
        enableDeclineButton
        onAccept={() => {
          updateGoogleConsent({ analytics_storage: 'granted' });
        }}
      >
        This website uses cookies to enhance the user experience.
      </CookieConsent>
    </>
  );
}

环境变量配置

支持的环境变量列表：

变量名	说明
`NEXT_PUBLIC_PLAUSIBLE_DOMAIN`	Plausible 域名
`NEXT_PUBLIC_PLAUSIBLE_SCRIPT_URL`	Plausible 脚本 URL
`NEXT_PUBLIC_UMAMI_WEBSITE_ID`	Umami 网站 ID
`NEXT_PUBLIC_UMAMI_SCRIPT_URL`	Umami 脚本 URL
`NEXT_PUBLIC_DATAFAST_WEBSITE_ID`	DataFast 网站 ID
`NEXT_PUBLIC_DATAFAST_DOMAIN`	DataFast 域名
`NEXT_PUBLIC_DATAFAST_SCRIPT_URL`	DataFast 脚本 URL
`NEXT_PUBLIC_MIXPANEL_TOKEN`	Mixpanel Token
`NEXT_PUBLIC_CRISP_WEBSITE_ID`	Crisp 网站 ID
`NEXT_PUBLIC_CLARITY_PROJECT_ID`	Clarity 项目 ID
`NEXT_PUBLIC_GOOGLE_TAG_ID`	Google Analytics ID

注意事项

生产环境默认：所有组件默认只在生产环境（NODE_ENV === "production"）渲染
本地开发测试：使用 allowLocalhost={true} 在开发环境启用
延迟加载：默认启用 defer，优化页面加载性能

项目链接

GitHub 仓库：https://github.com/iAmCorey/analytics-script
NPM 包：https://www.npmjs.com/package/analytics-script

许可证

MIT License