Reporting API 是声明式上报通道，仅自动上报浏览器内核级事件（如 CSP 违规、证书错误），不自动捕获 JS 错误；JS 错误需通过 reportError() 主动触发，且仅 Chromium 114+ 支持。
Reporting API 是什么，它真能自动上报浏览器错误？
Reporting API 不是错误捕获机制，它本身不监听 error 或 unhandledrejection 事件，也不会“自动”上报 JS 错误。它只是一个**声明式上报通道**：你得先配置好后端接收端点，再通过 Report-To HTTP 响应头或 report-to 属性告诉浏览器“出错了往哪儿发”，但具体哪些错误走这条通道、怎么触发上报，仍需手动配合其他机制。
常见误解是以为加个 Report-To 头就万事大吉——实际 Chrome 只对特定内置报告类型（如 deprecation、intervention、crash）默认启用 Reporting API 上报；JS 运行时错误（script error）默认不走这条路。
如何让 JS 错误通过 Reporting API 上报？
必须主动调用 reportError()，且仅限 Chromium 114+（2023 年中以后版本）。这是目前唯一能让自定义 JS 错误进入 Reporting API 管道的标准化方式。
- 需在
window.onerror或window.addEventListener('error')中捕获错误后，构造ErrorEvent或Error实例传入reportError() -
reportError()接收一个Error对象，不能传字符串或普通对象，否则静默失败 - 上报内容会被浏览器封装为
default类型报告，最终发送到你在Report-To头里指定的 endpoint - 注意跨域限制：目标 endpoint 必须与页面同源，或明确允许 CORS（
Access-Control-Allow-Origin: *），否则上报被拦截且无提示
window.addEventListener('error', (e) => {
if (e.error && 'reportError' in window) {
// 必须传 Error 实例，e.error 是标准 Error 对象
window.reportError(e.error);
}
});
Report-To 头怎么配才生效？
Report-To 是 HTTP 响应头，不是 HTML meta 标签，也不能用 JS 动态设置。必须由服务器在返回 HTML 时带上，格式严格：
立即学习“前端免费学习笔记（深入）”；
- 值必须是合法 JSON 字符串，且顶层是数组（即使只配一个 endpoint）
-
group名称要和后续Content-Security-Policy中的report-to指令一致（如果用了 CSP 触发上报） -
max_age单位是秒，设太小会导致频繁重协商；建议至少3600（1 小时） - Chrome 当前要求 endpoint 必须是 HTTPS，且响应状态码为 2xx，否则整个 Reporting API 功能降级为禁用
示例响应头：
Report-To: {"group":"default","max_age":3600,"endpoints":[{"url":"https://a.example.com/r"}]}
若同时使用 CSP 控制资源加载错误上报，还需配：
Content-Security-Policy: default-src 'self'; report-to default
为什么本地开发时完全看不到 Reporting API 请求？
Reporting API 在 file:// 协议或 localhost（非 HTTPS）下基本不可用。Chrome 从 93 版本起强制要求 Reporting API 的 endpoint 和页面都必须是 HTTPS（localhost 是例外，但仅限部分报告类型），且：
- 本地启 HTTP 服务（如
http://localhost:8080）时，Report-To头会被忽略，控制台出现警告：The Report-To header was ignored because the origin is not secure - 即使强行用 HTTPS 本地服务，也需信任自签名证书，否则上报请求因 TLS 握手失败而消失
- Firefox 和 Safari 完全不支持 Reporting API，别指望兼容
- 上报是异步批处理的，不是实时发出：浏览器会攒几条报告，延迟数秒到几十秒再发，调试时容易误判为没触发
真正验证是否工作，得部署到 HTTPS 环境，用浏览器开发者工具的 Network 面板过滤 r 或 report，看是否有 POST 到你 endpoint 的请求，响应体应为空（204）或简单确认。
