NEL策略头是浏览器网络错误日志机制的核心配置，由服务端通过Report-To和Content-Security-Policy（含nel指令）两个严格匹配的HTTP响应头协同启用；仅HTTPS站点生效，前端JS无法主动触发，必须后端正确下发且满足JSON格式、组名一致、端点合法等条件，否则浏览器完全不采集上报。
什么是NEL策略头，为什么浏览器不发日志
NEL（Network Error Logging）不是前端JS能主动触发的机制，它完全依赖HTTP响应头 Report-To 和 Content-Security-Policy 中的 nel 指令协同生效。浏览器只在收到合法NEL策略后，才对后续同源网络错误（如DNS失败、TCP连接超时、TLS握手失败、HTTP请求被拦截）自动采集并上报日志——HTML本身不参与日志生成，也不支持用<script>手动提交NEL格式日志。</script>
常见错误现象：Failed to execute 'report' on 'ReportingObserver': Reporting is not enabled 或控制台完全看不到NEL日志上报请求，基本都是因为服务端没正确下发NEL策略头。
- 必须由后端在HTTP响应中设置
Report-To头，声明报告端点（endpoint）和组名（group） - 必须在同一响应中设置
Content-Security-Policy头，包含nel <group-name></group-name>（例如nel default） - 两个头的组名必须严格一致，且只能是ASCII字母/数字/-/_，不能含空格或特殊字符
- 策略仅对HTTPS站点生效；HTTP下浏览器直接忽略NEL头
Report-To头怎么写才被Chrome/Firefox识别
Report-To 是JSON格式的HTTP头，不是任意字符串。现代浏览器（Chrome 94+、Firefox 101+）要求其值为单行有效JSON，且必须包含 group、max_age、endpoints 三个字段。任何语法错误（如末尾多逗号、用中文引号、缩进换行）都会导致整个头被丢弃。
正确示例（需作为HTTP响应头发送，非HTML内联）：
生成可在 deepbi 沙箱 iframe 内运行或作为独立文件运行的交互式 HTML 页面，使用 `window.deepbi` JS SDK 实现数据查询、空间管理、文件浏览及用户操作。当用户提出以下需求时启用该能力： - 创建 KPI 仪表盘、数据表格、文件浏览器、成员列表、管理页面； - 明确要求“转成 dhtml”、“转译成 HTML”、“把 XX 页面转成……”、“控制台页面”、“管理后台”、“DeepBI 页面迁移”； - 提及位于 `apps/console/src/featur
立即学习“前端免费学习笔记（深入）”；
{"group":"default","max_age":3600,"endpoints":[{"url":"https://your-domain.com/reports"}]}
-
max_age单位是秒，设为0表示立即失效，设太小（如60）会导致策略频繁过期失效 -
endpoints[0].url必须是HTTPS地址，且需支持POST+application/reports+json请求体 - 若配置多个endpoint，浏览器会轮询上报，但首个失败不会自动 fallback 到第二个
- Chrome DevTools → Application → Manifest 中可查看当前生效的Report-To策略，用于验证是否加载成功
前端如何验证NEL是否已启用并捕获上报行为
无法用JS“开启”NEL，但可以检查浏览器是否已加载策略，并观察真实错误是否触发上报。最直接方式是制造一个可复现的网络错误，比如请求一个明确不存在的子域名或强制断网后刷新页面。
- 在DevTools Network标签页过滤
reports或report，看到POST /reports请求且响应为200，说明NEL已工作 - 日志内容是标准JSON数组，每条含
type: "network-error"、url、age、body（含protocol、method、status_code等字段） - 注意：跨域资源（如CDN图片、第三方脚本）的错误默认不上报，除非该资源所在域也配置了匹配的NEL策略
- 本地开发时用
http://localhost测试NEL无效，必须用HTTPS + 真实域名（或自签证书+信任）
后端接收NEL日志时要注意什么
浏览器发送的NEL报告是批量JSON数组（不是单条），Content-Type为 application/reports+json，而非常见的 application/json。很多Web框架（如Express、Flask）默认不解析该类型，导致 req.body 为空。
- Express需显式添加中间件：
app.use('/reports', express.raw({ type: 'application/reports+json', limit: '10mb' })); - 收到原始Buffer后，需手动
JSON.parse(req.body.toString())，再遍历数组处理每条日志 - 每条日志的
body.url是触发错误的原始请求地址，可能含用户敏感参数，注意脱敏存储 - 上报频率受浏览器限流：同一错误类型在
max_age内最多上报一次，且每分钟总上报数有上限（Chrome约每分钟5条）
真正难的是让策略稳定生效——服务端头顺序、CDN缓存头覆盖、反向代理（如Nginx）截断长头、甚至负载均衡器重写CSP，都可能悄无声息地破坏NEL链路。上线前务必用curl -I确认原始响应头完整存在。
