NEL与Report-To网络错误上报治理（Report-To/NEL/采样）最佳实践

---

title: NEL与Report-To网络错误上报治理（Report-To/NEL/采样）最佳实践

keywords:

• NEL
• Report-To
• 采样
• 错误上报
• 端点白名单

description: 通过配置Report-To与NEL头并设置采样与端点白名单，收集网络错误事件、提升可视化治理能力并降低噪音与风险。

categories:

• 文章资讯
• 技术教程

---

背景与价值

Network Error Logging（NEL）结合Report-To通道可采集网络错误事件。合理的采样与白名单治理能在降低噪音的同时提升监控价值。

统一规范

• Report-To：配置端点与采样比率、最大年龄与分组名称。
• NEL：绑定到Report-To的group，设置成功/失败采样比率与最大年龄。
• 端点白名单：仅允许受控域作为上报端点。

核心实现

头生成与校验

type ReportToEndpoint = { url: string }
type ReportTo = { group: string; max_age: number; endpoints: ReportToEndpoint[]; include_subdomains?: boolean }
type Nel = { report_to: string; max_age: number; success_fraction: number; failure_fraction: number }

const allowOrigins = new Set(['https://reports.example.com'])

function endpointAllowed(e: ReportToEndpoint): boolean { try { const u = new URL(e.url); return allowOrigins.has(u.origin) } catch { return false } }

function validReportTo(rt: ReportTo): boolean { return typeof rt.group === 'string' && Number.isInteger(rt.max_age) && rt.max_age > 0 && rt.endpoints.every(endpointAllowed) }

function validNel(n: Nel, rt: ReportTo): boolean { return n.report_to === rt.group && Number.isInteger(n.max_age) && n.max_age > 0 && n.success_fraction >= 0 && n.success_fraction <= 1 && n.failure_fraction >= 0 && n.failure_fraction <= 1 }

function renderHeaders(rt: ReportTo, nel: Nel): { reportTo: string; nel: string } { return { reportTo: JSON.stringify(rt), nel: JSON.stringify(nel) } }

示例

const rt: ReportTo = { group: 'net', max_age: 86400, endpoints: [{ url: 'https://reports.example.com/nel' }] }
const nel: Nel = { report_to: 'net', max_age: 86400, success_fraction: 0.0, failure_fraction: 0.1 }
const headers = renderHeaders(rt, nel)
// res.setHeader('Report-To', headers.reportTo)
// res.setHeader('NEL', headers.nel)

落地建议

• 在入口统一下发Report-To与NEL头，限制上报端点域并设置合理采样比率与年龄。
• 定期审计上报数据与噪音，优化采样与分组策略。

验证清单

• 上报端点是否命中白名单；采样比率与max_age是否合理；NEL是否绑定正确的group。