Next.js 15 Reporting API 错误与崩溃收集治理实践

正文在现代 Web 应用中，前端错误与网络失败的可观测性是稳定性的基石。本文基于 Next.js 15 的 App Router 与 Edge Runtime，整合浏览器 Reporting API 与 NEL（Network Error Logging），实现崩溃、弃用与干预等报告的可靠采集与治理。一、启用报告端点与网络错误日志通过中间件下发兼容性的响应头，支持新旧两套标准：// middleware.ts import { NextResponse } from 'next/server' export function middleware() { const res = NextResponse.next() // 新标准：Reporting-Endpoints（Chrome 支持），指向统一端点 res.headers.set('Reporting-Endpoints', 'default="/api/reporting"') // 旧标准：Report-To + NEL 组合，仍有兼容价值 res.headers.set('Report-To', JSON.stringify({ group: 'default', max_age: 10800, endpoints: [{ url: '/api/reporting' }] })) res.headers.set('NEL', JSON.stringify({ report_to: 'default', success_fraction: 0, failure_fraction: 1, sampling_fraction: 1 })) return res } 二、Edge 路由接收与归一化在 App Router 下为 `/api/reporting` 创建路由处理器，确保缓存禁用与最小化响应体：// app/api/reporting/route.ts export const runtime = 'edge' export async function POST(req: Request) { const payload = await req.json().catch(() => null) if (!payload) return new Response(null, { status: 400 }) const reports = Array.isArray(payload) ? payload : [payload] const ua = req.headers.get('user-agent') || '' const sanitized = reports.map((r: any) => ({ type: r.type, // 'network-error', 'crash', 'deprecation', 'intervention' 等 url: r.url || r.body?.url || '', body: r.body ?? null, user_agent: ua, ts: Date.now() })) // TODO: 持久化到日志管道或数据仓库（例如：Supabase/Postgres/对象存储） return Response.json({ ok: true, count: sanitized.length }, { headers: { 'Cache-Control': 'no-store', 'Vary': 'User-Agent' } }) } 三、ReportingObserver 收集弃用/干预事件部分浏览器支持 `ReportingObserver` 用于收集弃用与干预类报告：'use client' import { useEffect } from 'react' export default function ReportingBoot() { useEffect(() => { if (typeof (window as any).ReportingObserver === 'function') { const ReportingObserver = (window as any).ReportingObserver const obs = new ReportingObserver((reports: any[]) => { fetch('/api/reporting', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(reports), keepalive: true }) }, { buffered: true, types: ['deprecation', 'intervention'] }) obs.observe() } }, []) return null } 四、治理要点与验证参数缓存治理：对于错误上报端点，统一设置 `Cache-Control: no-store`，避免 CDN 层误缓存导致投递失败或复用。兼容性：同时下发 `Reporting-Endpoints` 与 `Report-To + NEL`，覆盖不同版本浏览器的实现差异。隐私与体量：上报仅包含必要字段（type/url/body/user_agent/ts），避免敏感数据泄露；体量大时推荐批量与压缩管道。可靠投递：`fetch(..., { keepalive: true })` 有助于页面关闭时的最后一次上报；服务端端点应返回 2xx 并最小化响应体。观测整合：与 Web Vitals RUM、`Server-Timing` 共同形成端到端观测闭环，前端异常与后端阶段耗时可在同一数据域内关联。五、落地建议将 `/api/reporting` 接入企业日志平台或数据仓库，并通过仪表盘展示：每日网络错误率（由 NEL 提供）浏览器弃用与干预事件趋势（由 ReportingObserver 提供）异常类型 Top-N 与影响页面 Top-N结合变更发布窗口与性能基线，建立异常阈值与告警策略，形成可回溯的稳定性治理流程。