novalon-website/docs/ga4-error-tracking-integration.md

GA4 错误监控集成完成报告

📊 集成概述

日期: 2026-01-15 技术方案: Google Analytics 4 (GA4) 异常事件追踪 成本: 完全免费（使用现有 GA4 账户） 状态: ✅ 已完成并验证

---

🎯 实现目标

1. 零成本错误监控 - 利用现有 GA4 账户，无需额外付费服务
2. 全自动错误捕获 - 无需手动埋点，自动捕获所有 JavaScript 错误
3. 生产环境可用 - 已通过 TypeScript 检查和构建测试
4. 智能过滤 - 自动忽略无关错误（ResizeObserver、Script error 等）

---

📁 新增/修改的文件

核心文件

文件	操作	说明
src/lib/analytics.ts	新建	Analytics 核心模块，包含所有追踪函数
src/components/analytics/GlobalErrorTracker.tsx	新建	全局错误追踪器组件
src/app/layout.tsx	修改	集成 GlobalErrorTracker
src/app/test-error-tracking/page.tsx	新建	错误监控测试页面

辅助文件

文件	操作	说明
src/components/analytics/CookieConsent.tsx	修改	修复 CookiePreferences 类型定义

---

🔧 技术实现细节

1. 错误捕获机制

GlobalErrorTracker 组件（客户端）
    ↓
useEffect 初始化时添加事件监听器：
├── window.addEventListener('error', handleGlobalError)
│   └── 捕获 JavaScript 运行时错误
│       └── trackError('javascript_error', message, false, {filename, lineno, colno, stack})
│
├── window.addEventListener('unhandledrejection', handleUnhandledRejection)
│   └── 捕获 Promise 未捕获异常
│       └── trackError('unhandled_promise_rejection', message, false, {reason_type, stack})
│
└── document.addEventListener('error', handleResourceError, true)
    └── 捕获资源加载失败（图片、脚本、样式等）
        └── trackError('resource_loading_error', 'Failed to load resource', false)

2. GA4 事件数据结构

每个错误都会作为 exception 事件发送到 GA4，包含以下参数：

{
  event_name: 'exception',           // 固定事件名
  description: '[error_type] msg',   // 错误描述（包含类型前缀）
  fatal: 'true' | 'false',          // 是否致命错误
  url: '当前页面URL',               // 发生错误的页面
  timestamp: 'ISO时间戳',           // 发生时间
  // ... 其他上下文信息（可选）
}

3. ErrorBoundary 集成

React 组件渲染错误会自动被 ErrorBoundary 捕获并上报：

componentDidCatch(error: Error, errorInfo: React.ErrorInfo) {
  console.error('Error caught by boundary:', error, errorInfo);
  trackError('react_error', error.message, true); // 标记为致命错误
}

---

🧪 测试与验证

快速测试步骤

1. 启动开发服务器

   npm run dev
   

2. 访问测试页面

   http://localhost:3000/test-error-tracking
   

3. 点击测试按钮

   • 📛 测试 JavaScript 错误
   • ⚠️ 测试 Promise 异常
   • 💥 测试 React 致命错误
   • 🌐 测试网络错误

4. 查看控制台日志（开发模式）

   [GA4] Error tracked: {
     description: "[javascript_error] 测试错误...",
     fatal: "false",
     url: "http://localhost:3000/test-error-tracking",
     ...
   }
   

5. 在 GA4 后台验证

   • 登录 Google Analytics
   • 报告 → 实时 → 事件计数
   • 搜索 exception
   • 应该能在 30 秒内看到错误事件

---

📈 在生产环境使用

1. 确保环境变量已配置

检查 .env.local 或 .env.production 文件：

NEXT_PUBLIC_GA_MEASUREMENT_ID=G-LGTLCR15KM

2. 构建并部署

npm run build:clean
# 然后执行部署脚本
./deploy-dist.sh

3. 监控错误报告

方法 A：实时监控（推荐用于上线初期）

• GA4 后台 → 报告 → 实时
• 查看实时错误流

方法 B：定期审查（日常运维）

• GA4 后台 → 报告 → 参与度 → 事件
• 筛选 exception 事件
• 导出数据进行分析

方法 C：设置自动告警（高级）

• 使用 Google Data Studio 创建仪表盘
• 设置异常检测规则
• 配置邮件通知

---

🎨 自定义配置

忽略特定错误

编辑 GlobalErrorTracker.tsx：

const IGNORED_ERRORS = [
  /_AutofillCallbackHandler/,
  /ResizeObserver loop limit exceeded/,
  // 添加你想要忽略的错误模式...
];

添加自定义错误上下文

trackError('custom_error', 'Something went wrong', false, {
  user_id: '12345',
  feature_name: 'checkout',
  session_id: 'abc-xyz',
});

修改致命错误阈值

默认情况下，React 渲染错误会被标记为 fatal: true。你可以根据业务需求调整：

// ErrorBoundary 中
componentDidCatch(error: Error, errorInfo: React.ErrorInfo) {
  const isFatal = error.message.includes('critical');
  trackError('react_error', error.message, isFatal);
}

---

⚠️ 注意事项与限制

GA4 错误监控的限制

1. 数据延迟：GA4 数据通常有 24-48 小时的处理延迟（实时报告除外）
2. 采样率：高流量网站可能会有数据采样
3. 数据保留：GA4 免费版数据保留 2 个月（付费版 14 个月）
4. 事件限制：每个 session 最多 500 个事件
5. 参数限制：每个事件最多 25 个参数

与专业错误监控工具对比

特性	GA4 错误监控	Sentry (免费版)	Fundebug (免费版)
成本	✅ 免费	✅ 免费（5K 次/月）	✅ 免费（3K 次/月）
国内访问	✅ 可访问（需 VPN）	❌ 受限	✅ 可访问
错误聚合	⚠️ 基础	✅ 高级	✅ 高级
Source Map	❌ 不支持	✅ 支持	✅ 支持
性能影响	✅ 低	⚠️ 中等	⚠️ 中等
告警通知	⚠️ 有限	✅ 完善	✅ 完善
团队协作	⚠️ 基础	✅ 完善	✅ 完善

建议

• 适合场景：个人项目、小型网站、预算有限的项目
• 升级时机：当需要更专业的错误分析、Source Map 支持、团队协作功能时，考虑迁移到 Sentry 或 Fundebug
• 混合方案：同时使用 GA4 + Sentry/Fundebug，GA4 用于业务分析，专业工具用于错误调试

---

🔄 后续优化建议

短期优化（1-2 周）

1. 设置 GA4 告警

   • 配置自定义异常检测
   • 设置每日错误摘要邮件

2. 创建错误仪表盘

   • 使用 Google Data Studio
   • 可视化错误趋势、类型分布

3. 添加用户标识

   • 在错误上下文中包含用户 ID（如果适用）
   • 便于复现问题

中期优化（1-3 个月）

1. 错误分类体系

   • 定义错误严重级别（P0/P1/P2/P3）
   • 建立响应 SLA

2. 与 CI/CD 集成

   • 将错误率纳入质量门禁
   • 自动化回归测试

3. 性能关联分析

   • 关联 Core Web Vitals 与错误率
   • 发现性能瓶颈

长期优化（3-6 个月）

1. A/B 测试影响评估

   • 分析新功能上线后的错误变化
   • 量化代码质量改进效果

2. 预测性错误预防

   • 基于历史数据预测潜在问题
   • 主动修复高风险代码路径

3. 考虑迁移到专业工具

   • 如果错误量增长或需求复杂化
   • 评估 Sentry/Fundebug 的 ROI

---

📞 支持与故障排除

常见问题

Q: 为什么我在 GA4 后台看不到错误？

A: 请检查以下几点：

1. 确保 NEXT_PUBLIC_GA_MEASUREMENT_ID 环境变量已正确设置
2. 使用"实时"报告而非普通报告（有 24-48 小时延迟）
3. 检查浏览器控制台是否有 [GA4] Error tracked: 日志
4. 确认没有广告拦截器阻止 gtag.js 加载

Q: 如何区分开发和生产环境的错误？

A: 可以在错误上下文中添加环境标识：

trackError('test_error', 'Test message', false, {
  environment: process.env.NODE_ENV,
});

Q: 错误数据量太大怎么办？

A: GA4 免费版每个属性每月最多 1000 万次事件。如果超出：

1. 调整 IGNORED_ERRORS 过滤更多无关错误
2. 降低采样率（只上报部分错误）
3. 升级到 GA4 360 或迁移到专业错误监控工具

---

📊 成功指标

上线后应关注的核心指标

1. 错误率：< 1% 的 session 包含至少一个错误
2. 致命错误率：< 0.1% 的 session 包含致命错误
3. 平均修复时间 (MTTR)：< 24 小时（P0 错误 < 4 小时）
4. 错误趋势：周环比下降或持平

基准线建立建议

上线第一周：

• 收集基准数据
• 识别主要错误类型
• 建立监控仪表盘

第二周起：

• 设定改善目标
• 定期审查错误报告
• 持续优化代码质量

---

🎉 总结

✅ 已完成：GA4 错误监控完全集成 ✅ 已验证：TypeScript 检查通过，构建成功 ✅ 可测试：提供专用测试页面 /test-error-tracking ✅ 可扩展：支持自定义错误过滤和上下文 ✅ 零成本：利用现有 GA4 账户，无需额外费用

下一步行动：

1. 访问测试页面验证功能
2. 部署到生产环境
3. 在 GA4 后台设置监控
4. 建立定期审查流程

---

文档版本: v1.0 最后更新: 2026-01-15 维护者: 张翔 (Zhang Xiang)