|
|
# H5 错误上报功能说明
|
|
|
|
|
|
## 概述
|
|
|
已为H5项目添加了全局错误上报功能，能够捕获和上报前端运行时错误，即使发生白屏也能获取到错误信息。
|
|
|
|
|
|
## 错误上报接口
|
|
|
- **接口地址**: `https://tj-h5.hnxdfe.com/api/H5/test`
|
|
|
- **请求方式**: POST
|
|
|
- **Content-Type**: application/json
|
|
|
|
|
|
## 上报的错误类型
|
|
|
|
|
|
### 1. JavaScript 运行时错误 (type: 'error')
|
|
|
- 语法错误
|
|
|
- 引用错误
|
|
|
- 类型错误
|
|
|
- 范围错误等
|
|
|
|
|
|
### 2. Promise 未处理错误 (type: 'promise')
|
|
|
- Promise rejection 错误
|
|
|
- async/await 未捕获的异常
|
|
|
|
|
|
### 3. uni-app 错误 (type: 'uni-app-error')
|
|
|
- uni-app 生命周期错误
|
|
|
- 页面加载错误
|
|
|
|
|
|
### 4. 早期错误 (type: 'error' / phase: 'early')
|
|
|
- 应用初始化前的错误
|
|
|
- 脚本加载错误
|
|
|
- 白屏问题的主要来源
|
|
|
|
|
|
### 5. 手动上报错误 (type: 'manual')
|
|
|
- 业务逻辑中的自定义错误
|
|
|
|
|
|
## 错误数据格式
|
|
|
|
|
|
```json
|
|
|
{
|
|
|
"type": "error", // 错误类型
|
|
|
"message": "xxx is not defined", // 错误信息
|
|
|
"stack": "Error: xxx...", // 堆栈信息
|
|
|
"url": "https://...", // 当前页面URL
|
|
|
"ua": "Mozilla/5.0...", // 用户代理
|
|
|
"timestamp": "2024-01-01T00:00:00.000Z", // 时间戳
|
|
|
"openId": "xxxxx", // 用户OpenID（如果存在）
|
|
|
"phase": "early" // 阶段标识（仅早期错误）
|
|
|
}
|
|
|
```
|
|
|
|
|
|
## 功能特性
|
|
|
|
|
|
### 1. 多重上报保障
|
|
|
错误上报采用三层保障机制，确保即使白屏也能上报：
|
|
|
|
|
|
1. **优先使用 navigator.sendBeacon**
|
|
|
- 即使页面关闭也能发送
|
|
|
- 不阻塞页面卸载
|
|
|
- 最可靠的方式
|
|
|
|
|
|
2. **备用方案 fetch with keepalive**
|
|
|
- keepalive 选项保证请求完成
|
|
|
- 适用于大多数浏览器
|
|
|
|
|
|
3. **兜底方案 uni.request**
|
|
|
- 使用 uni-app 的请求方法
|
|
|
- 100ms 延迟避免阻塞
|
|
|
|
|
|
### 2. 早期错误捕获
|
|
|
- 在 `index.html` 中尽早初始化错误监听
|
|
|
- 捕获应用初始化前的错误
|
|
|
- 使用错误缓冲区存储早期错误
|
|
|
- 应用加载后统一重新上报
|
|
|
|
|
|
### 3. 性能监控
|
|
|
自动上报以下性能指标：
|
|
|
- `loadTime`: 页面总加载时间
|
|
|
- `domReadyTime`: DOM就绪时间
|
|
|
- `firstPaint`: 首次渲染时间
|
|
|
|
|
|
## 使用方法
|
|
|
|
|
|
### 自动捕获（默认开启）
|
|
|
所有错误会自动上报，无需额外配置。
|
|
|
|
|
|
### 手动上报错误
|
|
|
```javascript
|
|
|
// 在业务代码中手动上报
|
|
|
uni.$lu.errorReport.report('自定义错误信息', {
|
|
|
// 额外的业务数据
|
|
|
userId: '123',
|
|
|
action: 'submitOrder'
|
|
|
})
|
|
|
```
|
|
|
|
|
|
### 手动上报错误对象
|
|
|
```javascript
|
|
|
try {
|
|
|
// 可能出错的操作
|
|
|
} catch (error) {
|
|
|
uni.$lu.errorReport.reportError(error, 'custom-error')
|
|
|
}
|
|
|
```
|
|
|
|
|
|
### 上报性能数据
|
|
|
```javascript
|
|
|
uni.$lu.errorReport.reportPerformance({
|
|
|
customMetric: 1234,
|
|
|
operation: 'loadData'
|
|
|
})
|
|
|
```
|
|
|
|
|
|
## 日志输出
|
|
|
|
|
|
在开发环境中，可以在控制台看到以下日志：
|
|
|
|
|
|
```
|
|
|
[早期错误捕获] 已初始化
|
|
|
[错误上报] 已初始化
|
|
|
[错误上报] 早期错误数量: 2
|
|
|
[错误上报] { type: 'error', message: '...', ... }
|
|
|
```
|
|
|
|
|
|
## 后端处理建议
|
|
|
|
|
|
### 1. 数据存储
|
|
|
建议将错误数据存储到数据库或日志系统：
|
|
|
- MongoDB: 适合存储灵活的JSON数据
|
|
|
- MySQL/PostgreSQL: 可以使用JSON字段
|
|
|
- ELK Stack: 适合日志分析和检索
|
|
|
|
|
|
### 2. 错误统计
|
|
|
可以统计以下指标：
|
|
|
- 错误类型分布
|
|
|
- 错误发生频率
|
|
|
- 受影响的用户数
|
|
|
- 错误来源页面
|
|
|
- iOS vs Android 错误对比
|
|
|
|
|
|
### 3. 告警机制
|
|
|
可以设置告警规则：
|
|
|
- 某类错误短时间内激增
|
|
|
- 同一用户连续报错
|
|
|
- 白屏类型错误（phase: 'early'）
|
|
|
|
|
|
## 调试方法
|
|
|
|
|
|
### 1. 测试错误上报
|
|
|
在浏览器控制台执行：
|
|
|
```javascript
|
|
|
// 触发一个错误
|
|
|
throw new Error('测试错误上报')
|
|
|
```
|
|
|
|
|
|
### 2. 查看网络请求
|
|
|
打开开发者工具 -> Network -> 查看POST请求到 `/api/H5/test` 的数据
|
|
|
|
|
|
### 3. 查看早期错误缓冲区
|
|
|
```javascript
|
|
|
console.log(window.__ERROR_BUFFER__)
|
|
|
```
|
|
|
|
|
|
### 4. 小程序 WebView 设备调试（重要）
|
|
|
|
|
|
由于小程序 WebView 无法查看控制台，已添加以下调试功能：
|
|
|
|
|
|
#### 调试按钮
|
|
|
页面右下角会显示三个调试按钮：
|
|
|
|
|
|
1. **🐛 查看日志**（红色）- 切换日志面板显示/隐藏
|
|
|
2. **🧪 测试**（绿色）- 测试日志功能是否正常工作
|
|
|
3. **🗑️ 清空**（橙色）- 清空所有日志
|
|
|
|
|
|
#### 自动显示日志
|
|
|
- 发生错误时，页面顶部会自动显示黑色半透明的调试面板
|
|
|
- 面板中会显示完整的错误信息和调试日志
|
|
|
- 点击 "🐛 查看日志" 按钮可手动切换显示状态
|
|
|
|
|
|
#### 日志内容
|
|
|
日志面板中会显示：
|
|
|
- `[时间] [原始error事件]` - 原始错误事件的详细信息
|
|
|
- `[时间] [早期错误捕获]` - 处理后的错误信息
|
|
|
- `[时间] 调试系统已初始化` - 调试系统启动时的测试日志
|
|
|
- 所有调试日志的时间戳和详细信息
|
|
|
|
|
|
#### 测试日志功能
|
|
|
1. 点击 **🧪 测试** 按钮
|
|
|
2. 如果日志面板出现并显示测试信息，说明日志功能正常
|
|
|
3. 如果点击没反应，可能是被小程序 WebView 的安全策略限制
|
|
|
|
|
|
#### 获取完整日志
|
|
|
如果需要将日志发送给开发者：
|
|
|
|
|
|
方法1：截图
|
|
|
- 将调试面板的内容截图
|
|
|
|
|
|
方法2：复制日志
|
|
|
```javascript
|
|
|
// 在浏览器控制台执行（需要能访问控制台）
|
|
|
console.log(JSON.stringify(window.__DEBUG_LOGS__, null, 2))
|
|
|
```
|
|
|
|
|
|
方法3：通过小程序调试工具
|
|
|
- 如果小程序有调试模式，可以通过调试工具访问 `window.__DEBUG_LOGS__`
|
|
|
|
|
|
#### 调试面板特性
|
|
|
- 自动滚动到最新日志
|
|
|
- 每条日志有分隔线，方便阅读
|
|
|
- 自动换行，长文本不会溢出
|
|
|
- 点击 "🐛 查看日志" 按钮切换显示/隐藏
|
|
|
|
|
|
## 注意事项
|
|
|
|
|
|
1. **隐私保护**: 错误数据不包含敏感信息，但建议后端做好脱敏处理
|
|
|
2. **性能影响**: 错误上报使用异步方式，不影响页面性能
|
|
|
3. **网络限制**: 如果网络不可用，错误会失败但不影响应用运行
|
|
|
4. **跨域问题**: 确保接口支持 CORS 或在同一域名下
|
|
|
|
|
|
## iOS 白屏问题排查
|
|
|
|
|
|
通过错误上报，可以收集以下信息来排查 iOS 白屏问题：
|
|
|
|
|
|
1. **早期错误 (phase: 'early')**
|
|
|
- 查看应用初始化前的错误
|
|
|
- 可能是脚本加载或语法错误
|
|
|
|
|
|
2. **用户代理 (ua)**
|
|
|
- 识别具体的 iOS 版本
|
|
|
- 区分不同的 WebView 环境
|
|
|
|
|
|
3. **错误堆栈 (stack)**
|
|
|
- 精确定位错误位置
|
|
|
- 了解错误调用链
|
|
|
|
|
|
4. **URL 信息**
|
|
|
- 判断是否特定页面白屏
|
|
|
- 检查路由参数是否正确
|
|
|
|
|
|
## 实际案例分析
|
|
|
|
|
|
### 案例1: iOS 14.5 微信小程序白屏
|
|
|
```json
|
|
|
{
|
|
|
"type": "error",
|
|
|
"message": "{}",
|
|
|
"stack": null,
|
|
|
"url": "https://tj-h5.hnxdfe.com/h5/#/pages/main/login/login?openid=oosgJj-yr2IrwSmBb3_ERy1hGMos",
|
|
|
"ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 14_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148 MicroMessenger/8.0.63(0x18003f2f) NetType/4G Language/zh_CN miniProgram/wxece13dd0a5b22c73",
|
|
|
"timestamp": "2026-02-05T11:43:07.707Z",
|
|
|
"phase": "early"
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**问题分析**：
|
|
|
- 错误信息为 `{}`，堆栈为 `null`
|
|
|
- 说明错误对象构建时出错，可能是早期错误对象结构异常
|
|
|
- 发生在登录页面，URL 中带有 openid 参数
|
|
|
- 环境是 iOS 14.5 + 微信 8.0.63 + 小程序 WebView
|
|
|
|
|
|
**可能原因**：
|
|
|
1. 微信小程序 WebView 在早期阶段触发了 error 事件
|
|
|
2. error 事件对象的结构与预期不同
|
|
|
3. 某些初始化脚本在特定环境下执行失败
|
|
|
|
|
|
**已优化**：
|
|
|
- 增强了 `buildErrorInfo` 函数，处理更多异常情况
|
|
|
- 添加了对 null/undefined 的特殊处理
|
|
|
- JSON.stringify 失败时的降级处理
|
|
|
- 确保 message 和 stack 永远不会是 null 或空对象
|
|
|
|
|
|
**建议后续观察**：
|
|
|
- 检查是否还有类似 `{}` 或 `null` 的错误信息
|
|
|
- 统计 iOS 14.5 的错误频率
|
|
|
- 检查登录页面是否是白屏高发页面
|
|
|
- 检查 openid 参数处理是否正常
|
|
|
|
|
|
## 扩展建议
|
|
|
|
|
|
未来可以考虑：
|
|
|
1. 添加错误采样率（避免上报过多）
|
|
|
2. 添加用户反馈功能（用户主动报告问题）
|
|
|
3. 集成第三方错误监控（如 Sentry）
|
|
|
4. 添加错误聚合和去重机制
|