张翔
8840c4398a
- Downgrade Next.js 16→14.2, React 19→18.3, Tailwind 4→3.4 - Add comprehensive GA4 error monitoring system - Create Jenkins CI/CD pipeline with quality gates - Fix build issues: ESLint, SWC conflict, config format - Add documentation for deployment and error tracking
348 lines
9.5 KiB
Markdown
348 lines
9.5 KiB
Markdown
# 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，包含以下参数：
|
||
|
||
```javascript
|
||
{
|
||
event_name: 'exception', // 固定事件名
|
||
description: '[error_type] msg', // 错误描述（包含类型前缀）
|
||
fatal: 'true' | 'false', // 是否致命错误
|
||
url: '当前页面URL', // 发生错误的页面
|
||
timestamp: 'ISO时间戳', // 发生时间
|
||
// ... 其他上下文信息（可选）
|
||
}
|
||
```
|
||
|
||
### 3. ErrorBoundary 集成
|
||
|
||
React 组件渲染错误会自动被 [ErrorBoundary](src/components/ui/error-boundary.tsx) 捕获并上报：
|
||
|
||
```typescript
|
||
componentDidCatch(error: Error, errorInfo: React.ErrorInfo) {
|
||
console.error('Error caught by boundary:', error, errorInfo);
|
||
trackError('react_error', error.message, true); // 标记为致命错误
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🧪 测试与验证
|
||
|
||
### 快速测试步骤
|
||
|
||
1. **启动开发服务器**
|
||
```bash
|
||
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](https://analytics.google.com/)
|
||
- 报告 → 实时 → 事件计数
|
||
- 搜索 `exception`
|
||
- 应该能在 30 秒内看到错误事件
|
||
|
||
---
|
||
|
||
## 📈 在生产环境使用
|
||
|
||
### 1. 确保环境变量已配置
|
||
|
||
检查 `.env.local` 或 `.env.production` 文件：
|
||
|
||
```env
|
||
NEXT_PUBLIC_GA_MEASUREMENT_ID=G-LGTLCR15KM
|
||
```
|
||
|
||
### 2. 构建并部署
|
||
|
||
```bash
|
||
npm run build:clean
|
||
# 然后执行部署脚本
|
||
./deploy-dist.sh
|
||
```
|
||
|
||
### 3. 监控错误报告
|
||
|
||
#### 方法 A：实时监控（推荐用于上线初期）
|
||
- GA4 后台 → 报告 → 实时
|
||
- 查看实时错误流
|
||
|
||
#### 方法 B：定期审查（日常运维）
|
||
- GA4 后台 → 报告 → 参与度 → 事件
|
||
- 筛选 `exception` 事件
|
||
- 导出数据进行分析
|
||
|
||
#### 方法 C：设置自动告警（高级）
|
||
- 使用 Google Data Studio 创建仪表盘
|
||
- 设置异常检测规则
|
||
- 配置邮件通知
|
||
|
||
---
|
||
|
||
## 🎨 自定义配置
|
||
|
||
### 忽略特定错误
|
||
|
||
编辑 [GlobalErrorTracker.tsx](src/components/analytics/GlobalErrorTracker.tsx)：
|
||
|
||
```typescript
|
||
const IGNORED_ERRORS = [
|
||
/_AutofillCallbackHandler/,
|
||
/ResizeObserver loop limit exceeded/,
|
||
// 添加你想要忽略的错误模式...
|
||
];
|
||
```
|
||
|
||
### 添加自定义错误上下文
|
||
|
||
```typescript
|
||
trackError('custom_error', 'Something went wrong', false, {
|
||
user_id: '12345',
|
||
feature_name: 'checkout',
|
||
session_id: 'abc-xyz',
|
||
});
|
||
```
|
||
|
||
### 修改致命错误阈值
|
||
|
||
默认情况下，React 渲染错误会被标记为 `fatal: true`。你可以根据业务需求调整：
|
||
|
||
```typescript
|
||
// 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: 可以在错误上下文中添加环境标识：
|
||
|
||
```typescript
|
||
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)
|