笔者在Vibe Coding 产品数据建设：5步框架与数据清单里，提到 GA4 作为工具选型的一环但没有展开。这篇补上 GA4 本身的实操细节，重点是半年实践中踩过的坑和演进出来的规范。

为什么单独写一篇？GA4 是 MVP 产品最容易"接了但没用好"的工具。接入只要一行代码，但要真正用出价值，自定义维度注册、埋点约定落文档、多工具口径对齐，这些坑 AI Agent 大概率不知道。

一、GA4 是什么

GA4 是 Google 提供的免费网站和应用分析工具，2023 年全面替代 Universal Analytics。核心变化从"页面浏览 + 会话"模型转向事件驱动模型：所有用户交互都是事件，页面浏览也不例外。不清楚也没关系，就当成页面计数器好了。

对小规模开发来说，GA4 的价值在于三点：免费、功能全（漏斗、留存、探索报表都有）、BigQuery 免费导出。代价也很明确：配置门槛高，学习曲线陡，生态相对封闭。但是你如果做出海、做谷歌生态，就没办法绕过它。

二、功能关注点

GA4 后台功能繁多，MVP 产品不需要全用。以下是按实用程度排的几个核心功能。

值得花时间的

探索报表：GA4 里最有价值的功能。自由形式的分析画布，可做漏斗、路径分析、同期群留存。标准报表是预设好的仪表盘，探索报表才是你真正需要的分析工具。它的学习曲线陡，第一次搭漏斗报表可能摸不着头脑。跟某些公司里的自定义报表没法比。

自定义维度与指标：最容易踩坑、代价最大的功能。GA4 的规则是：事件参数如果没有在后台注册为自定义维度或指标，数据进了系统也不进报表，Data API 查不到，且历史数据无法补回。后面 PageGrok 的案例会详细说这个坑。

增强衡量：滚动、外链点击、站内搜索、视频播放、文件下载，这些事件开箱即用，不需要额外埋点。

DebugView：实时查看单个设备发送的事件和参数。新埋点上线后，先在 DebugView 里确认事件到达、参数值正确，再去看报表。不验证就直接看报表，数据不对还不知道问题出在哪。

可以晚点再碰的

标准报表：预设的仪表盘，看个大盘趋势可以，做深度分析不够用。日常扫一眼流量来源和实时用户数就行。

受众群体：需要一定流量基础才有意义。日活不到 500 的时候，细分受众样本太小，分析不出什么。

Google Ads 集成：没投广告的话完全不用管。

三、关键配置项

基础接入不赘述，建属性、建数据流、拿到衡量 ID（G-XXXXXXX），加到网站里。下面是几个容易被忽略、但直接影响数据质量的配置。

数据保留期限

默认 2 个月，建议改为最长的 14 个月。这个设置只影响探索报表（标准报表不受限），而你真正需要的深度分析全在探索报表里。两个月后数据就查不到了，回头想做同期对比发现数据没了，就晚了。

路径：GA4 → 管理 → 数据设置 → 数据保留。

内部流量过滤

开发者自己频繁访问产品，不过滤的话数据会严重失真。操作分两步：

第一步，定义什么是内部流量。GA4 → 管理 → 数据流 → 选择你的流 → 配置标记设置 → 定义内部流量。在这里按 IP 地址（支持单 IP、IP 范围、CIDR 格式）定义规则，GA4 会给匹配的流量打上 traffic_type=internal 标签。

第二步，创建过滤器排除它。GA4 → 管理 → 数据设置 → 数据过滤器 → 创建过滤器，类型选"开发者流量"。注意过滤器有"测试"和"活跃"两个状态，先用"测试"跑几天确认没误杀正常用户，再切到"活跃"。

如果内部流量小，还不足以影响分析，这步其实可以后面补上。还能针对内部流量做专门分析。

跨域追踪

如果营销站和产品不在同一个域名下，不配跨域的话，用户从 A 域名点链接跳到 B 域名，GA4 会把这当成两个独立来源的会话。B 域名上的会话来源会显示为 A 域名的 referral，而不是用户最初的真实来源（比如 Google 搜索）。

举个具体场景：用户从 Google 搜索进入 www.quantfull.com，点了购买按钮跳到 Stripe 支付，完成后回到 www.quantfull.com/success。不配跨域的话，成功页的会话来源会变成 stripe.com 引荐，Google 搜索这个真实归因就丢了。

配置方法：GA4 → 管理 → 数据流 → 选择流 → 配置标记设置 → 列出需要关联的域名。GA4 会在跨域链接里自动追加 _gl 参数传递客户端 ID，从而把多个域名下的行为关联成同一个用户。

这个场景适合归因、多域名情况。

Google Signals

路径：GA4 → 管理 → 数据设置 → 数据收集。在"Google 信号数据收集"卡片里开启。

开启后可以利用用户的 Google 账号做跨设备关联。同一个人在手机和电脑上访问你的网站，GA4 能识别为同一个用户。

但有个副作用叫"数据阈值"：当某个报表维度组合的用户数太少时，GA4 会直接隐藏那些行来保护隐私。早期产品流量本来就小，开了 Signals 之后探索报表里经常出现"数据不足以显示"，反而看不到你最想看的细分数据。

建议：日活稳定超过 500 再考虑开启。在那之前，关掉它反而能看到更完整的数据。

转化事件标记

把北极星指标对应的事件标记为"关键事件"（GA4 2024 年起把"转化"改叫"关键事件"了，意思一样）。标记后 GA4 会在多处报表中高亮展示该事件的数据。如果后续接 Google Ads，出价优化也依赖这个标记。

四、实践与踩坑

笔者按 2026 年 2 月至 8 月扫了本地活跃仓库的 Git 历史。GA4 从"给网站挂一个访问统计脚本"，逐步发展成"有事件约定、有采集链路、有数据质量审计、能被 Agent 查询"的体系。但不同产品最终选择的职责边界并不相同。

最早期（3 月左右）几个产品基本只是把 gtag.js 放进全局 Layout，看个 PV 和来源。到 6 月 TrakToken 开始加产品行为事件，但全部发往 Vercel Analytics，GA4 继续只承担 pageview。“有埋点"不代表"事件已经进入 GA4”，这个认知直到需要数据反馈迭代产品时，才建立起来。

真正系统化的 GA4 落地，从 7 月开始。三个产品三条路。

QuantFull：GA4 做漏斗主口径

QuantFull 把 GA4 定为漏斗主口径，Vercel Analytics 保留但不替代，Clarity 补充会话行为。漏斗从 organic_landing 到 purchase，所有事件统一携带 landing_path、product_slug 等字段，缺值时发 not_set，不因字段缺失拆散口径。purchase 用 Stripe Session ID 做 transaction_id 去重。

PageGrok：自定义维度需注册

PageGrok 是浏览器扩展，广告拦截器会直接拦截 GA4 请求。最终改走自有 Vercel Edge 中转端点，服务端持有 Secret 转发给 GA4 Measurement Protocol。

然后忽视了一个情况：代码一直在上报 prompt_tokens、provider、code 等参数，但后台只注册了 1 个自定义维度、0 个自定义指标。GA4 没注册的参数不进报表、Data API 查不到。发布到发现之间的数据永久丢失，没有补回手段。

经验教训：事件参数写进代码的同一天，就去 GA4 后台注册对应的自定义维度和指标。 路径是 管理 → 数据显示 → 自定义定义 → 创建。参数名必须与代码里上报的逐字一致（区分大小写）。免费版上限 50 维度 + 50 指标。

同时建议开 BigQuery 导出（管理 → 产品链接 → BigQuery 链接）。免费版每天 100 万事件额度，早期产品完全够用。

TrakToken： 多工具分工的三层架构

TrakToken 没有把所有产品事件塞进 GA4，而是形成了明确的三层设计：

层 工具 负责什么 定位
流量基线 Vercel Web Analytics PV、UV、路径、来源、设备 零配置常驻，日常看它
渠道与留存 GA4 新老用户、渠道分组、落地页、留存 只收自动 pageview，不收自定义事件
产品行为 PostHog 漏斗、分群、事件级归因 回答"谁做了什么、接下来做了什么"

关键规则是同一个指标只属于一层，跨层的数字不做加减。自定义事件对 PostHog 与 Vercel 双写，GA4 不参与自定义事件，避免第三套需要对齐的口径。三层数字对不上是正常的，Vercel 通常比 GA4 高 30-40%，差值本身是要监控的指标。

为什么不集中到一个工具？每个工具有结构性优势：Vercel 零配置且不被拦截；GA4 的渠道归因和新老用户判定较准；PostHog 的漏斗和分群功能最灵活。硬要一个工具全干，要么配置复杂度爆炸，要么某个维度的数据质量下降。

广告拦截：接受损耗还是绕过去

GA4 的采集域名在主流去广告规则集里是主要拦截目标。笔者实际观察，Vercel Analytics 的访问量比 GA4 多 30-40%。

对大多数场景，接受 GA4 的数据损耗、用 Vercel Analytics 做交叉验证是更实际的方案。差值本身也是有用的信息。

埋点约定

QuantFull 早期的问题是：同一个"购买成功"事件，Stripe、后端、前端三个地方都在记，口径全不一样。最终是在独立的 Markdown 文档里把事件名、触发时机、参数、取值范围全部写死，代码和分析两边参照同一份文档。

TrakToken 把这个做法发展成了一份 600 行的 ANALYTICS.md，包含北极星指标定义、三层工具分工、17 个事件的完整规格、属性词表、命名规范、验证兜底和口径说明。看起来重，但写一次就不会再出现"这个事件到底算什么"的问题。

五、局限与互补

GA4 的核心局限

GA4 的上手成本在同类工具里偏高，对比 PostHog 一行 URL 接入、Vercel Analytics 零配置，GA4 的配置流程明显更重。免费版在数据量大时会触发采样，探索报表尤其明显，早期产品流量小时感知不到，流量起来后才会遇到。在 AI Agent 生态里，GA4 的封闭性也是个问题：近期分析厂商 MCP 横评中十家都出了 MCP，GA4 被归类为 “Read-Only Trap”，Agent 能读数据但不能写回任何东西，Amplitude 则开放了 24 个写操作工具。再加上 25-40% 的客户端流量可能被广告拦截器拦截，GA4 的数据天然就不完整。

产品互补

PostHog：2026 年 PMF 验证阶段最常被推荐的产品分析工具。免费版每月 1M 事件。远程 MCP 端点 https://mcp.posthog.com/mcp 本地什么都不用装，直接加到 Claude Code / Cursor 就能用，支持自然语言查询和 feature flag 管理。

Microsoft Clarity：免费，无流量上限，热力图和会话录制。GA4 能告诉你哪一步掉了人，Clarity 能让你看到掉的那个人当时在干什么。QuantFull 的实践是只在 Production 环境配置 Clarity，避免 Preview 会话污染生产基线。

Vercel Analytics：零配置、隐私友好、不被广告拦截器拦截。笔者用它做日常流量监控，GA4 做深度分析，两者交叉验证。不过需要开通 pro 账号，每月20刀。

AI Agent 接入

官方 analytics-mcp 是当前最直接的方案，但安装体验不佳，需要 pipx + GCP 建项目 + 开 Analytics Data API + 手配 ADC。笔者实测还踩了代理问题（MCP 进程拿不到 shell 的 HTTP 代理，直连 Google 超时），最终退回 gcloud auth + REST API。

社区还有两条路线：竞争性 MCP Server（比如 surendranb/google-analytics-mcp，针对大数据量做了行数预估和智能聚合），以及 CLI + Skill 路线（比如 Bin-Huang/google-analytics-cli，输出结构化 JSON，不需要 MCP 常驻进程）。

笔者建议不要在第三方工具上投入太多关注。它们的维护周期和你的产品生命周期不一定对齐，API 变更随时可能让工作流断掉，存在供应链风险。更稳妥的做法是手搓适合自己的 Skill，把查询逻辑和口径定义写进自己控制的代码里。

另一个值得注意的风险：AI 查询分析数据存在"指标漂移"问题，同一个自然语言问题在不同运行和不同 Agent 之间可能产生不同的查询和数字。有数据显示，不加语义约束的裸 text-to-SQL 在复杂 schema 上准确率只有 6-25%。简单的应对策略是在 Skill 里写死指标定义和允许的维度范围，让 Agent 从定义里选而不是自己蹦。

六、常见规范与边界

从半年实践中沉淀出的几条规范。

事件命名

固定格式 object_action，全小写下划线。上下文放属性里，不塞进事件名。

正例：cta_clicked + surface=hero 反例：hero_cta_clicked 和 footer_cta_clicked 各建一个事件

属性管理

统一词表，同一个概念全站只有一个属性名。新增属性先查词表，有的直接用，没有的先加词表再用。枚举类属性写死取值范围，枚举外的值上报 unknown 并当作埋点缺陷处理。

验证兜底

代码调用了埋点函数，不代表数据已经到达分析系统。新事件上线后，逐个在浏览器触发一次，按平台验收：

  • 在目标平台的实时视图或 DebugView 里确认事件出现
  • 逐个字段核对属性名和取值，重点查枚举类属性有没有出现枚举外的值
  • 确认自定义维度和指标已在 GA4 后台注册

口径对齐

多工具的数字对不上是正常的。关键规则：同一个指标只属于一层，跨层不做加减。明确记录哪些问题去哪个平台查：

问题 以哪层为准
站点有多少流量 Vercel
流量从哪来、新老用户 GA4
用户做了什么、漏斗转化 PostHog（或 GA4，取决于产品的选择）

埋点约定文档

写一份独立的 Markdown 文档，至少包含：北极星指标定义（含口径、分母、排除规则）、事件清单（触发时机、属性、取值范围）、各工具分工和单一真相源规则。写代码的 AI 照这份文档埋，做分析的 AI 照这份文档查，两边用同一套取值范围。

参考资料

GA4 实践

AI Agent 与 GA4

语义层与数据准确性

方法论（详见数据建设 5 步框架中的参考资料）

关于作者