zhangyan
/
hainan_2024_zhenghe
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
main
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'main'
${ noResults }
hainan_2024_zhenghe/h5/ERROR_REPORT.md

7.9 KiB
Raw Permalink Blame History Unescape Escape

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')

  • 业务逻辑中的自定义错误

错误数据格式

{
  "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: 首次渲染时间

使用方法

自动捕获（默认开启）

所有错误会自动上报，无需额外配置。

手动上报错误

// 在业务代码中手动上报
uni.$lu.errorReport.report('自定义错误信息', {
  // 额外的业务数据
  userId: '123',
  action: 'submitOrder'
})

手动上报错误对象

try {
  // 可能出错的操作
} catch (error) {
  uni.$lu.errorReport.reportError(error, 'custom-error')
}

上报性能数据

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. 测试错误上报

在浏览器控制台执行：

// 触发一个错误
throw new Error('测试错误上报')

2. 查看网络请求

打开开发者工具 -> Network -> 查看POST请求到 /api/H5/test 的数据

3. 查看早期错误缓冲区

console.log(window.__ERROR_BUFFER__)

4. 小程序 WebView 设备调试（重要）

由于小程序 WebView 无法查看控制台，已添加以下调试功能：

调试按钮

页面右下角会显示三个调试按钮：

  1. 🐛 查看日志（红色）- 切换日志面板显示/隐藏
  2. 🧪 测试（绿色）- 测试日志功能是否正常工作
  3. 🗑️ 清空（橙色）- 清空所有日志

自动显示日志

  • 发生错误时，页面顶部会自动显示黑色半透明的调试面板
  • 面板中会显示完整的错误信息和调试日志
  • 点击 "🐛 查看日志" 按钮可手动切换显示状态

日志内容

日志面板中会显示：

  • [时间] [原始error事件] - 原始错误事件的详细信息
  • [时间] [早期错误捕获] - 处理后的错误信息
  • [时间] 调试系统已初始化 - 调试系统启动时的测试日志
  • 所有调试日志的时间戳和详细信息

测试日志功能

  1. 点击 🧪 测试 按钮
  2. 如果日志面板出现并显示测试信息，说明日志功能正常
  3. 如果点击没反应，可能是被小程序 WebView 的安全策略限制

获取完整日志

如果需要将日志发送给开发者：

方法1：截图

  • 将调试面板的内容截图

方法2：复制日志

// 在浏览器控制台执行（需要能访问控制台）
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 微信小程序白屏

{
  "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. 添加错误聚合和去重机制