Skip to content

生产诊断与错误恢复 ​

默认能力 ​

模板统一收集 Vue、脚本、未捕获 Promise、资源、HTTP、路由、应用初始化及会话清理错误。记录包含错误类型、时间、消息、堆栈、版本、构建编号、路由及白名单上下文。生产构建保留 console.warn/error,去除业务 log/debug/info 和 debugger,单独保留一次应用启动版本输出。

默认只在当前页面内存保留最近 50 条并输出控制台,不写浏览器存储,也不向任何监控服务发送数据。页面刷新后记录消失;需要长期排障时应接入项目上报服务。预期的取消请求和常见 ResizeObserver 噪声会被忽略;10 秒内相同记录只累加次数。上报每分钟最多 20 条、同时最多 3 条,超出部分仍保留在有界内存中,不排无限队列。

默认不采集用户信息、组件实例、请求头、请求体或响应体。URL 去除查询、锚点和凭据,消息与堆栈会遮蔽常见 token、password、Authorization 等字段并限制长度。自由文本无法覆盖所有项目敏感信息,不应把业务数据拼入异常消息。路径参数仍可能包含业务标识,项目上报前可进一步处理。

接入上报 ​

在入口初始化阶段注入 reporter,无需修改业务页面:

ts
import { setDiagnosticReporter } from '@/utils/sys/diagnostics'

setDiagnosticReporter(async (record) => {
  // 使用独立传输,避免经过业务 HTTP 层造成 401 退出或递归上报。
  const response = await fetch('/monitor/frontend-errors', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(record),
    signal: AbortSignal.timeout(5000)
  })
  if (!response.ok) throw new Error('Diagnostic upload failed')
})

reporter 抛错或 Promise 拒绝均被隔离,不会触发业务退出或再次上报。调用 getDiagnosticRecords() 可获取记录副本,clearDiagnosticRecords() 清空当前内存记录,setDiagnosticReporter() 移除上报器。注入上报器后不补发历史记录;重复记录的累计次数保留在本地快照,避免重复上传。

构建与 sourcemap ​

  • 项目 package.json 的 version 标识应用发布版本。
  • 每次构建自动生成 buildId,可通过 VITE_BUILD_ID 注入唯一的 CI 构建编号。控制台、诊断记录和 version.json 共享同一份信息,详见版本与构建追踪。
  • VITE_BUILD_SOURCEMAP=true 生成 hidden sourcemap,默认关闭。hidden 仅去掉 JS 内的映射引用,不提供访问控制:CI 应上传对应版本映射后,从静态部署目录删除所有 .map 文件。

入口安装监听后,可捕获初始化流程错误;入口 JS 本身下载失败、静态 ESM 依赖尚未执行时发生的加载错误,仍需部署侧监控或独立 HTML 启动兜底处理。

恢复行为 ​

权限/菜单初始化失败进入 500,用户点击“重新加载页面”会清除失败状态并重新初始化。普通接口业务错误保留在原页面处理。

路由懒加载和 Vite preload 失败会记录诊断,进入随入口打包的 500 恢复页。用户点击“刷新并重试”后才整页刷新,恢复原目标地址并重新加载资源,不自动循环刷新。图片等普通资源失败仅记录,不强制跳页。