Vue / 系统课时
前端监控与线上排障
前端监控与线上排障
线上问题难排,通常不是因为缺少日志,而是错误、性能、请求和发布版本彼此断开。本节建立一条从浏览器事件到 release、路由和请求链的最小监控路径,并给出可重复的线上定位顺序。
学习目标
- 统一采集 Vue 错误、未处理异常、页面性能和异常请求
- 给监控事件附加 release、路由和请求 ID,形成可关联上下文
- 按“版本变化 → 前端堆栈 → 请求链 → 修复验证”的顺序排查线上故障
先统一监控事件上下文
每条事件都应带上稳定的 release 标识、当前路由和时间。请求监控再补充方法、路径、状态码、耗时和后端返回的请求 ID。不要采集 Authorization、Cookie、请求体、响应体和完整查询字符串,避免把令牌或个人数据送进监控系统。
下面是片段示例,依赖已有的 Vite + Vue 3 应用;monitoring.ts 作为项目内模块不独立运行。生产环境可以把 /monitor/events 替换成自己的采集入口,并在服务端继续做采样、脱敏和聚合。
import type { App } from 'vue'
type EventKind =
| 'vue-error'
| 'window-error'
| 'promise-rejection'
| 'navigation'
| 'request'
interface MonitorEvent {
kind: EventKind
release: string
path: string
timestamp: string
message?: string
stack?: string
method?: string
requestPath?: string
requestId?: string
status?: number
durationMs?: number
}
const endpoint = '/monitor/events'
const release = import.meta.env.VITE_APP_VERSION || 'dev'
function toMessage(value: unknown): string {
if (value instanceof Error) return value.message
if (typeof value === 'string') return value
return 'Unknown error'
}
function emit(event: Omit<MonitorEvent, 'release' | 'path' | 'timestamp'>): void {
const payload: MonitorEvent = {
...event,
release,
path: location.pathname,
timestamp: new Date().toISOString()
}
const body = JSON.stringify(payload)
if (import.meta.env.DEV) console.info('[monitor]', payload)
const sent = navigator.sendBeacon?.(
endpoint,
new Blob([body], { type: 'application/json' })
)
if (!sent) {
void fetch(endpoint, {
method: 'POST',
headers: { 'content-type': 'application/json' },
body,
keepalive: true
}).catch(() => undefined)
}
}
export function installMonitoring(app: App): void {
app.config.errorHandler = (err, _instance, info) => {
emit({
kind: 'vue-error',
message: `${info}: ${toMessage(err)}`,
stack: err instanceof Error ? err.stack : undefined
})
}
window.addEventListener('error', (event) => {
emit({
kind: 'window-error',
message: event.message,
stack: event.error instanceof Error ? event.error.stack : undefined
})
})
window.addEventListener('unhandledrejection', (event) => {
emit({
kind: 'promise-rejection',
message: toMessage(event.reason),
stack: event.reason instanceof Error ? event.reason.stack : undefined
})
})
window.addEventListener('load', () => {
const nav = performance.getEntriesByType('navigation')[0] as
| PerformanceNavigationTiming
| undefined
if (nav) emit({ kind: 'navigation', durationMs: Math.round(nav.duration) })
})
}
export async function observedFetch(
input: RequestInfo | URL,
init: RequestInit = {}
): Promise<Response> {
const method =
init.method ?? (input instanceof Request ? input.method : 'GET')
const rawUrl = input instanceof Request ? input.url : input.toString()
const requestPath = new URL(rawUrl, location.origin).pathname
const startedAt = performance.now()
try {
const response = await fetch(input, init)
const durationMs = Math.round(performance.now() - startedAt)
if (!response.ok || durationMs >= 1000) {
emit({
kind: 'request',
method,
requestPath,
requestId: response.headers.get('x-request-id') || undefined,
status: response.status,
durationMs
})
}
return response
} catch (error) {
emit({
kind: 'request',
method,
requestPath,
status: 0,
durationMs: Math.round(performance.now() - startedAt),
message: toMessage(error)
})
throw error
}
}该模块需要在应用启动时安装。下面同样是片段示例,依赖现有 App.vue 和 Vite 入口:
import { createApp } from 'vue'
import App from './App.vue'
import { installMonitoring } from './monitoring'
const app = createApp(App)
installMonitoring(app)
app.mount('#app')接入后可在开发环境浏览器控制台执行一次可控异常,验证全局错误链路:
setTimeout(() => {
throw new Error('monitor-smoke-test')
}, 0)预期结果
Uncaught Error: monitor-smoke-test
[monitor] <包含 kind="window-error"、release=<VALUE>、path=<PATH> 的事件对象>同时浏览器会向 /monitor/events 发送 POST。<VALUE> 与 <PATH> 会随实际构建版本和访问路由变化;跨域 API 若要让前端读取 x-request-id,服务端还需要允许该响应头对浏览器脚本可见。
业务 API 层应统一改用 observedFetch,而不是在每个组件重复写监控逻辑。生产环境还应注入不可变的 VITE_APP_VERSION,例如构建号或提交 ID,这样同一错误是否从某次发布开始出现就能被直接聚合。

按版本和请求链定位问题
线上排障先缩小范围,再追单个现场。顺序混乱时,很容易在海量日志中反复猜测。
- 先按时间窗口和 release 聚合错误率,确认问题是否只出现在某个新版本。
- 再按路由、错误信息和堆栈指纹聚类,判断是单页面回归还是全局故障。
- 请求失败时,用
requestId、状态码和请求路径去关联网关或后端日志;状态码为 0 通常意味着请求未获得 HTTP 响应,应继续检查网络、跨域或浏览器阻断。 - 前端堆栈若来自压缩产物,使用与该 release 一一对应的 source map 还原源码位置。source map 应在 CI 中归档或上传到监控系统,不要让不同 release 共用同一份映射。
- 修复上线后用新的 release 重新观察同一错误指纹和请求链,确认错误率下降,而不是只验证“本机不再复现”。
用现象选择第一证据
| 线上现象 | 第一证据 | 优先判断 |
|---|---|---|
| 新版本后 JS 错误陡增 | release、堆栈、路由 | 代码回归、资源缓存不一致 |
| 4xx/5xx 请求集中出现 | requestId、status、requestPath | 鉴权、接口契约、后端异常 |
| 页面无报错但明显变慢 | navigation/request duration | 慢接口、资源加载、网络质量 |
| 只有深层 URL 刷新 404 | Nginx 访问日志、部署配置 | SPA 回退缺失或路径不匹配 |
修复后验证监控闭环
监控系统自身也可能失效,因此发布验收要包含“事件能否上报”。测试环境至少主动触发一次可控异常和一次失败请求,确认采集端收到正确 release;再检查敏感头、请求体和查询参数没有被记录。
线上修复完成后,不要只看错误条数归零。还要确认新 release 的页面性能没有退化、请求失败率恢复到基线,并保留问题发生版本、影响路由、关联请求 ID、根因和修复版本,下一次同类故障就能直接复用证据链。