使用 GA4 监控网站浏览数据

概述

把文档站发布上线只是第一步——了解用户如何使用文档才是持续改进的关键。Google Analytics 4（GA4）是 Google 推出的最新一代网站分析平台，它采用事件驱动的跟踪模型，免费且功能强大。本节将从注册配置、代码集成、数据解读到优化决策，手把手教你用 GA4 监控文档站的浏览情况。

问答

Q：GA4 是什么？跟以前的 Universal Analytics 有什么不同？

A：GA4（Google Analytics 4）是 Google 于 2023 年正式取代 Universal Analytics（UA）的新一代分析平台。核心区别：

对比项	Universal Analytics (UA)	GA4
跟踪模型	基于会话（Session）	基于事件（Event）
数据流	仅 Web	Web + App 统一数据流
跨设备追踪	有限	原生支持（通过 Google Signals）
隐私合规	依赖 Cookie	无 Cookie 建模 + 同意模式
报告界面	经典视图	全新事件中心报告
预测指标	无	购买概率、流失概率等 AI 预测
免费额度	有采样限制	更宽裕，BigQuery 免费导出

简单说，GA4 更灵活、更面向未来，且所有新创建的 Google Analytics 资产都是 GA4 格式。

Q：如何创建 GA4 资产（Property）？

A：按以下步骤操作：

登录 Google Analytics：访问 analytics.google.com，用你的 Google 账号登录
创建资产：
- 点击左下角”管理”（Admin）齿轮图标
- 选择”创建” → “资产”（Property）
- 填写资产名称（如”ESP32 IoT 教程文档”）
- 选择时区和货币
- 点击”下一步”完成创建
获取 Measurement ID：
- 创建完成后，进入”数据流”（Data Streams）
- 点击”Web”数据流
- 你会看到一个 G-XXXXXXXXXX 格式的 Measurement ID——这就是你需要集成到站点的标识

[!TIP] 建议将 Measurement ID 存储为环境变量（如 PUBLIC_GA_ID），而不是硬编码在代码中。这样可以在不同环境（开发/生产）使用不同的 ID，避免开发阶段的测试数据污染生产统计。

Q：如何将 GA4 集成到 Starlight 文档站？

A：在 astro.config.mjs 中通过 Starlight 的 head 配置注入 gtag 脚本：

const gaId = process.env.PUBLIC_GA_ID || 'G-XXXXXXXXXX';

export default defineConfig({
  site: 'https://docs.yourcompany.com',
  integrations: [
    starlight({
      title: 'My Docs',
      head: gaId
        ? [
            {
              tag: 'script',
              attrs: {
                async: true,
                src: `https://www.googletagmanager.com/gtag/js?id=${gaId}`,
              },
            },
            {
              tag: 'script',
              content: `window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag('js', new Date());
gtag('config', '${gaId}');`,
            },
          ]
        : [],
    }),
  ],
});

代码解析：

条件注入：gaId ? [...] : [] 确保在没有设置 ID 时（如本地开发）不注入脚本
异步加载：async: true 不阻塞页面渲染
gtag('config', ...)：自动跟踪页面浏览（page_view 事件）

部署后，通常 5-30 分钟内就能在 GA4 后台看到实时数据。

Q：如何在 Vercel 中配置 GA4 环境变量？

A：如果使用 Vercel 托管，在 Vercel 控制台中添加环境变量：

进入 Vercel 项目 → Settings → Environment Variables
添加变量：
- Name: PUBLIC_GA_ID
- Value: G-M648KX24EK（替换为你的 Measurement ID）
- Environments: 选择 Production（只在生产环境启用）
重新部署（Redeploy）使环境变量生效

[!NOTE] 以 PUBLIC_ 开头的环境变量在 Astro 中会被暴露到客户端——这是 gtag 脚本需要的。不要将敏感信息（如 API 密钥）放在 PUBLIC_ 前缀的变量中。

Q：GA4 中哪些报告对文档站最有价值？

A：对于技术文档站，以下报告最值得重点关注：

1. 实时报告（Realtime）

位置：GA4 左侧菜单 → “报告” → “实时”
用途：发布新内容后立即查看是否有用户在浏览
关键指标：当前活跃用户数、热门页面、用户地理分布

2. 页面和屏幕（Pages and screens）

位置：报告 → “参与度” → “页面和屏幕”
用途：了解哪些文档页面被访问最多
关键指标：

指标	含义	决策参考
浏览量（Views）	页面被查看的总次数	识别热门内容和冷门内容
活跃用户数	看过该页面的独立用户	了解内容的实际覆盖范围
平均参与时间	用户在页面上的活跃时间	时间长=内容有价值；时间短=需优化
跳出率	只看一页就离开的用户比例	高跳出=着陆页不够吸引或信息不完整

3. 流量获取（Traffic acquisition）

位置：报告 → “获取” → “流量获取”
用途：了解用户从哪里来
常见渠道：
- Organic Search：从 Google/百度等搜索引擎来（SEO 效果的指标）
- Direct：直接输入 URL（品牌认知度的指标）
- Referral：从其他网站链接来（外链效果）
- Organic Social：从社交媒体来（社交传播效果）

4. 用户留存（Retention）

位置：报告 → “留存情况”
用途：了解用户是否会回来（文档质量的长期指标）

Q：如何查看具体哪些文档页面最受欢迎？

A：在”页面和屏幕”报告中，按路径查看：

进入报告 → 参与度 → 页面和屏幕
在表格上方选择”页面路径和屏幕类别”作为维度
你将看到类似这样的数据：

页面路径                              浏览量    活跃用户    平均参与时间
/introduction/                        1,234     890        3m 12s
/esp32-development-basics/01/          987     654        5m 45s
/mqtt-protocol/03/                     876     543        4m 22s
/zh/introduction/                      654     432        2m 56s

如何利用这些数据：

浏览量高 + 参与时间长：这些页面是”核心内容”，优先维护和更新
浏览量高 + 参与时间短：用户来了但没细看——检查内容是否过于复杂或缺乏结构
浏览量低：考虑是否需要更好的内部链接或 SEO 优化

Q：如何跟踪文档站的搜索使用情况？

A：Pagefind 搜索默认不会被 GA4 跟踪，但你可以添加自定义事件来追踪：

在 Starlight 项目中创建一个自定义脚本（如 public/analytics.js）：

// 监听 Pagefind 搜索事件
document.addEventListener('DOMContentLoaded', () => {
  // 等待 Pagefind 初始化
  const searchInput = document.querySelector('.pagefind-ui__search-input');
  if (searchInput && typeof gtag !== 'undefined') {
    let debounce;
    searchInput.addEventListener('input', (e) => {
      clearTimeout(debounce);
      debounce = setTimeout(() => {
        const query = e.target.value;
        if (query.length >= 2) {
          gtag('event', 'search', {
            search_term: query,
          });
        }
      }, 500);
    });
  }
});

然后在 head 配置中引入这个脚本：

head: [
  // ... gtag 脚本 ...
  {
    tag: 'script',
    attrs: { src: '/analytics.js', defer: true },
  },
]

配置后，可以在 GA4 → 报告 → 参与度 → 事件中查看”search”事件，了解用户在搜索什么关键词——这些搜索词是改进文档结构和内容的宝贵线索。

Q：如何设置自定义事件来追踪文档交互？

A：GA4 的事件驱动模型让你可以追踪任何用户行为。常见场景：

追踪代码块复制：

// 监听 Starlight 代码块的复制按钮
document.addEventListener('click', (e) => {
  const copyBtn = e.target.closest('button[aria-label*="Copy"]');
  if (copyBtn && typeof gtag !== 'undefined') {
    const codeBlock = copyBtn.closest('starlight-code-block') || copyBtn.closest('pre');
    const lang = codeBlock?.getAttribute('data-language') || 'unknown';
    gtag('event', 'code_copy', {
      language: lang,
    });
  }
});

追踪语言切换：

// 监听 Starlight 的语言切换
document.querySelectorAll('[data-astro-cid]').forEach((el) => {
  el.addEventListener('click', () => {
    const href = el.getAttribute('href');
    if (href?.startsWith('/zh/') && typeof gtag !== 'undefined') {
      gtag('event', 'language_switch', {
        target_language: 'zh-CN',
      });
    }
  });
});

在 GA4 后台，进入”管理” → “自定义事件”或”探索”来查看这些自定义事件的数据。

Q：如何设置 GA4 的关键转化事件？

A：对于文档站，以下行为可以设为转化事件（Conversion）：

事件名	触发条件	意义
`doc_completed`	用户滚动到长文档底部	衡量内容完读率
`code_copy`	用户复制了代码块	衡量代码示例的实用性
`external_link_click`	用户点击了外链（如 GitHub）	衡量文档的引导效果
`search`	用户执行了站内搜索	衡量搜索功能使用率

设置方法：

GA4 后台 → 管理 → 事件 → 创建事件
输入事件名和匹配条件
在”转化”中标记该事件为转化

Q：如何创建 GA4 自定义仪表板（Dashboard）？

A：使用 GA4 的”探索”（Explore）功能创建自定义报告：

进入 GA4 → 左侧菜单 → “探索”
选择”空白”模板
配置维度和指标：

推荐的文档站仪表板配置：

维度：页面路径、语言（/zh/ vs /）、日期
指标：浏览量、活跃用户、平均参与时间、事件数
筛选器：排除内部 IP（开发团队自己的访问）

你也可以使用 Looker Studio（原 Google Data Studio）连接 GA4 数据源，创建更专业的可视化仪表板，并分享给团队成员。

Q：如何排除自己团队的访问数据？

A：开发团队频繁访问文档会污染统计数据。排除方法：

按 IP 排除：
- GA4 → 管理 → 数据流 → 选择你的 Web 数据流
- 点击”配置标记设置” → “内部流量”
- 定义内部流量的 IP 地址范围
- 在”数据筛选器”中激活排除
按 Cookie 排除（更灵活）：
- 在 gtag 配置中添加条件判断：
```
// 如果存在特定 Cookie，则不跟踪
if (!document.cookie.includes('no_analytics=true')) {
  gtag('config', 'G-XXXXXXXXXX');
}
```
- 团队成员在浏览器控制台执行 document.cookie = "no_analytics=true" 即可关闭跟踪

Q：GA4 数据多久能看到？

A：

报告类型	延迟时间
实时报告	数秒
标准报告（页面、流量等）	24-48 小时
探索报告	24-48 小时
BigQuery 导出	约 24 小时

如果你刚部署上线，先在”实时”报告中确认 gtag 已正常工作，第二天再查看完整数据。

Q：如何根据 GA4 数据优化文档？

A：数据驱动的内容优化循环：

观察数据 → 发现问题 → 优化内容 → 验证效果

具体行动指南：

数据信号	可能的原因	优化行动
某页面浏览量高但跳出率高	内容太复杂或结构不清晰	添加目录、拆分步骤、增加示例
某页面浏览量持续下降	SEO 排名下降或内容过时	更新内容、添加关键词、优化标题
搜索关键词集中在某个主题	文档中缺少相关内容	创建新的专题页面
某语言版本浏览量远低于另一版	翻译质量差或未翻译	补全翻译、优化译文质量
代码复制事件多但后续无转化	示例代码可能有错误	验证代码示例的正确性

验证步骤

完成 GA4 集成后，按以下步骤验证：

本地验证：启动 npm run dev，打开浏览器 DevTools → Network，搜索 gtag，确认脚本已加载
GA DebugView：在 GA4 后台 → 管理 → DebugView，安装 Google Analytics Debugger Chrome 扩展，实时查看事件触发
实时报告：部署到生产环境后，打开 GA4 实时报告，确认 5 分钟内能看到活跃用户
事件验证：在页面中触发搜索、复制代码等操作，查看 GA4 DebugView 是否正确记录对应事件

下一步

掌握了 GA4 监控后，你可以进一步探索：

将 GA4 数据与 Google Search Console 关联，分析搜索关键词带来的流量
使用 BigQuery 导出原始数据进行深度分析
设置 GA4 自定义提醒，当流量异常波动时自动通知

正在开发商业 IoT 产品？

我们提供 ESP32 ODM 定制设计与制造服务。从原型到量产——编写这套教程的团队，可以和你一起实现。

联系我们 →