Google Analytics 4 设置技能

您正在为一个项目设置 Google Analytics 4 (GA4)。请按照这份全面指南正确添加分析功能。

参数

从 $ARGUMENTS 中解析以下内容：

• - 衡量 ID：格式 G-XXXXXXXXXX（必需，如果未提供则询问）
• --events：包含自定义事件跟踪辅助工具
• --consent：包含 Cookie 同意集成
• --debug：为开发启用调试模式

第 1 步：检测项目类型

扫描项目以确定框架/设置：

优先级检测顺序：

1. 1. next.config.js/ts → Next.js
2. nuxt.config.js/ts → Nuxt.js
3. astro.config.mjs → Astro
4. svelte.config.js → SvelteKit
5. remix.config.js → Remix
6. gatsby-config.js → Gatsby
7. vite.config.js + src/App.vue → Vue + Vite
8. vite.config.js + src/App.tsx → React + Vite
9. angular.json → Angular
10. 包含 react-scripts 的 package.json → Create React App
11. 仅有 index.html → 纯 HTML
12. _app.tsx/jsx → Next.js（App Router 检查：app/ 目录）

同时检查：

• - TypeScript 使用情况（tsconfig.json）
• 现有分析功能（搜索 gtag、GA、analytics）
• 包管理器（pnpm-lock.yaml、yarn.lock、package-lock.json）

第 2 步：验证衡量 ID

衡量 ID 必须：

• - 以 G- 开头（GA4 格式）
• 后跟恰好 10 个字母数字字符
• 示例：G-ABC1234567

如果用户提供 UA- ID，请告知他们：

您提供了一个 Universal Analytics ID (UA-)。GA4 使用以 G- 开头的衡量 ID。

Universal Analytics 已于 2024 年 7 月停用。您需要在 analytics.google.com 创建一个 GA4 媒体资源。

第 3 步：按框架实现

Next.js（App Router - app/ 目录）

创建 app/layout.tsx 修改或创建 components/GoogleAnalytics.tsx：

tsx
// components/GoogleAnalytics.tsx
use client

import Script from next/script

interface GoogleAnalyticsProps {
measurementId: string
}

export function GoogleAnalytics({ measurementId }: GoogleAnalyticsProps) {
return (
<>
src={https://www.googletagmanager.com/gtag/js?id=${measurementId}}
strategy=afterInteractive
/>


)
}

添加到根布局：
tsx
// app/layout.tsx
import { GoogleAnalytics } from @/components/GoogleAnalytics

// 在 或 内部添加：

Next.js（Pages Router - pages/ 目录）

修改 pages/_app.tsx：

tsx
// pages/_app.tsx
import type { AppProps } from next/app
import Script from next/script

const GAMEASUREMENTID = process.env.NEXTPUBLICGAMEASUREMENTID

export default function App({ Component, pageProps }: AppProps) {
return (
<>
src={https://www.googletagmanager.com/gtag/js?id=${GAMEASUREMENTID}}
strategy=afterInteractive
/>



)
}

React（Vite/CRA）

创建 src/lib/analytics.ts：

typescript
// src/lib/analytics.ts
export const GAMEASUREMENTID = import.meta.env.VITEGAMEASUREMENT_ID

declare global {
interface Window {
gtag: (...args: unknown[]) => void
dataLayer: unknown[]
}
}

export const initGA = () => {
if (typeof window === undefined) return

const script = document.createElement(script)
script.src = https://www.googletagmanager.com/gtag/js?id=${GAMEASUREMENTID}
script.async = true
document.head.appendChild(script)

window.dataLayer = window.dataLayer || []
window.gtag = function gtag() {
window.dataLayer.push(arguments)
}
window.gtag(js, new Date())
window.gtag(config, GAMEASUREMENTID)
}

export const pageview = (url: string) => {
window.gtag(config, GAMEASUREMENTID, {
page_path: url,
})
}

export const event = (action: string, params?: Record) => {
window.gtag(event, action, params)
}

在 src/main.tsx 中初始化：

tsx
import { initGA } from ./lib/analytics

// 在渲染前初始化
if (import.meta.env.PROD) {
initGA()
}

Vue 3（Vite）

创建 src/plugins/analytics.ts：

typescript
// src/plugins/analytics.ts
import type { App } from vue
import type { Router } from vue-router

const GAMEASUREMENTID = import.meta.env.VITEGAMEASUREMENT_ID

declare global {
interface Window {
gtag: (...args: unknown[]) => void
dataLayer: unknown[]
}
}

export const analyticsPlugin = {
install(app: App, { router }: { router: Router }) {
// 加载 gtag 脚本
const script = document.createElement(script)
script.src = https://www.googletagmanager.com/gtag/js?id=${GAMEASUREMENTID}
script.async = true
document.head.appendChild(script)

window.dataLayer = window.dataLayer || []
window.gtag = function gtag() {
window.dataLayer.push(arguments)
}
window.gtag(js, new Date())
window.gtag(config, GAMEASUREMENTID)

// 跟踪路由变化
router.afterEach((to) => {
window.gtag(config, GAMEASUREMENTID, {
page_path: to.fullPath,
})
})

// 提供全局方法
app.config.globalProperties.$gtag = window.gtag
}
}

Nuxt 3

创建 plugins/analytics.client.ts：

typescript
// plugins/analytics.client.ts
export default defineNuxtPlugin(() => {
const config = useRuntimeConfig()
const measurementId = config.public.gaMeasurementId

if (!measurementId) return

// 加载 gtag
useHead({
script: [
{
src: https://www.googletagmanager.com/gtag/js?id=${measurementId},
async: true,
},
{
innerHTML:
window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag(js, new Date());
gtag(config, ${measurementId});
,
},
],
})

// 跟踪路由变化
const router = useRouter()
router.afterEach((to) => {
window.gtag(config, measurementId, {
page_path: to.fullPath,
})
})
})

添加到 nuxt.config.ts：

typescript
export default defineNuxtConfig({
runtimeConfig: {
public: {
gaMeasurementId: process.env.NUXTPUBLICGAMEASUREMENTID,
},
},
})

Astro

创建 src/components/Analytics.astro：

astro

const { measurementId } = Astro.props