feat: downgrade tech stack to stable versions and integrate GA4 error monitoring
- 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
This commit is contained in:
张翔
@@ -0,0 +1,347 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user