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结合变更发布窗口与性能基线，建立异常阈值与告警策略，形成可回溯的稳定性治理流程。