"GA4 与 Clarity"
"从创建两个统计项目到配置、构建、访客选择和上线验证。"
GA4 与 Clarity
GA4 用来看访问来源、国家/地区和页面访问,Clarity 用来看点击热图与操作回放。模板已经接好客户端代码,只需配置本站的两个 ID;默认都留空,开发默认不加载。
后台创建
Google Analytics 4
在 Google Analytics 的 Admin → Create → Property 为新产品建立媒体资源。已有 Analytics 账号可以继续用,原博客的媒体资源和网址保留;建议每个产品分开看报表。
名称填产品名,报告时区和币种按实际需求选。美国时区或东八区都能查看海外用户;时区决定每天数据如何分界。业务目标可以选了解网站流量和用户参与度/留存。
添加 Web 数据流,填写正式 HTTPS 域名与数据流名称。关闭 Enhanced measurement,再创建,复制 G-… 开头的 Measurement ID。数字 Stream ID 不填进下面的配置。
本模板手工记录 Nuxt 页面切换,因此关闭自动增强型衡量,避免重复页面访问和额外自动事件。不要另外贴 Google tag 或通过 GTM 重复接入。
Microsoft Clarity
在 Clarity 创建 Website 项目,填写站名和正式网址。进入 Settings → Overview 取得 Project ID,或者从安装脚本的最后一个字符串参数提取。核对 Consent Mode 开启,让后台与代码的同意信号配合。
模板使用官方 @microsoft/clarity npm 包,复制模板不需要再贴整段脚本。包仍会下载微软托管脚本,执行只在客户端且取得同意后发生。GA4 使用 Google 官方 Google tag。两个工具独立接入,本版没有关联账号,也没有额外发送播放/复制/支付等业务事件。
构建前配置
NUXT_PUBLIC_GA4_ID=G-EXAMPLE123
NUXT_PUBLIC_CLARITY_PROJECT_ID=example123
NUXT_PUBLIC_ANALYTICS_IN_DEV=false
把示例替换成本站的实际 ID,留空关闭对应服务。这些是公开接入标识,不是密钥。只填一项也可使用;两项都空则隐藏统计入口。调试时才显式打开开发开关,并使用替身脚本,避免制造真实统计数据。
Nuxt 默认读取 .env,不自动读取 .env.production。静态预渲染 HTML 会固化 ID 与隐私说明,更改后必须重新构建,单改 Worker 运行变量不会更新静态页面。
如果使用 .env.production:
npm run docs:build
npx nuxt build --dotenv .env.production
npx tsx scripts/use-production-config.ts
npx wrangler deploy --dry-run
# 核对正式目标和绑定后,发布同一份已检查的产物。
npx wrangler deploy
先按部署文档完成自己的生产目标、授权与已有密钥配置。npm run deploy:production 会重新构建,默认不会带上述 --dotenv;不要用它覆盖刚刚显式构建好的产物。
访客选择与采集范围
首次在公开页底部显示一条接受与拒绝,不使用挡住工具的对话框。接受后才加载脚本,拒绝不影响网站使用。页脚 Analytics preferences 可重新选择,偏好最多保存 180 天。撤回已启用统计会刷新当前页卸载脚本,提示用户先复制需要保留的内容。
GA4 广告存储、广告个性化与 Google signals 关闭;Clarity 只同意统计,广告用途保持拒绝。不设置账号标识。隐私政策按配置列出启用的服务。
认证、账号、账单、支付和 API 路径排除,含语言前缀。入口或来路含参数、未知片段时整个文档不启用统计;固定 #audio 锚点例外。UTM 落地访问首版也跳过,不声称完整营销归因。已加载统计的文档进入排除地址时会完整导航,让新文档没有统计环境。
模板内容容器默认遮罩;新增用户输出也应显式遮罩。输入框默认遮罩并不等于整张页面所有内容都安全,不在 URL、标题、元素 ID、CSS 或自定义事件中放用户信息。
验证与排查
npm run analytics:check:local
npm run typecheck
npm run build
npm run deploy:check
上述命令不等于真实后台已经收数。正式发布后,用无参数的公开地址,接受统计并切换页面:GA4 先看 Realtime,Clarity 看 Dashboard、Recordings 与 Heatmaps,抽查遮罩;再拒绝,确认刷新后不再加载。普通报表、录制和热图可能需要处理时间和样本。
无数据时依次看 ID、是否新构建并发布、是否接受统计、是否开发环境、是否命中参数/来路/敏感路径排除、广告拦截器和后台项目设置。数字翻倍时检查重复脚本及 Enhanced measurement。
GA4 与 Clarity 的计数受定义、同意状态、拦截和处理影响,不要求完全相等,也不用固定差异比例判断正常。
完整实现和验证记录见仓库 docs/analytics.md。规则在 shared/analytics.ts,偏好在 useAnalyticsConsent.ts,初始化在 app/plugins/analytics.client.ts,供应商封装在 app/utils/analytics-client.ts。