深入解析 report-to 头部在前端错误监控中的实战应用

我的写法，亲测靠谱

搞前端这些年，CSP（Content Security Policy）报告这事儿我踩过不少坑。早期光配个 report-uri，后来发现它被废弃了，得换成 report-to。但光换名字可不行，配置不对等于白搭。我折腾了好几个项目，最后总结出一套还算稳定的写法，分享出来，省得你再走弯路。

首先，report-to 是配合 Reporting-Endpoints 响应头一起用的。很多人以为只在 CSP 里加个 report-to 就行，其实漏了关键一步：服务端必须返回对应的 Reporting-Endpoints 头。否则浏览器根本不知道往哪发报告。

我现在的标准配置是这样的：

Content-Security-Policy: default-src 'self'; report-to csp-endpoint;
Reporting-Endpoints: csp-endpoint="https://jztheme.com/api/csp-report"

注意两点：一是 report-to 的值（这里是 csp-endpoint）必须和 Reporting-Endpoints 里定义的名称完全一致；二是这个 endpoint URL 必须是 HTTPS，而且不能是内网地址，浏览器会直接拒绝发送。

另外，别忘了设置 CORS。虽然 CSP 报告是浏览器自动发的，但如果你的报告接收接口没处理 OPTIONS 请求，或者没允许跨域（虽然通常不需要显式允许，但有些服务器中间件会拦），报告可能就静默失败了。我之前在一个 Nginx + PHP 项目里卡了两天，最后发现是 PHP 框架自动返回了 405，因为没处理 OPTIONS。加上下面这段才搞定：

if ($_SERVER['REQUEST_METHOD'] === 'OPTIONS') {
    http_response_code(204);
    exit;
}

这几种错误写法，别再踩坑了

我在 review 代码时经常看到下面这些“经典”错误，列出来给你避雷：

• 只写 report-to，不设 Reporting-Endpoints：浏览器控制台会报错说找不到 endpoint，但页面功能正常，很容易被忽略。等你真想看报告时，发现一条都没有。
• endpoint 名称大小写不一致：比如 CSP 里写 report-to CSP-Endpoint，但 Reporting-Endpoints 里是 csp-endpoint=...。浏览器是严格匹配的，这种写法直接失效。
• 用相对路径或 HTTP 地址：像 report-to="/csp" 或者 http://localhost:3000/report。前者根本不符合规范，后者在 HTTPS 页面下会被浏览器拦截。我见过有人本地开发时用 HTTP 调通了，上线后死活收不到报告，查了半天才发现是协议问题。
• 把 report-to 和 report-uri 混用：虽然规范说如果同时存在，优先用 report-to，但有些老浏览器（比如某些安卓 WebView）可能只认 report-uri。如果你还要兼容旧环境，建议两个都配，但确保指向同一个接收端，避免数据分散。

还有个隐藏坑：**不要在开发环境开启 report-to**。为什么？因为开发时各种 eval、inline script、localhost 资源会疯狂触发 CSP 违规，你的报告接口可能瞬间被刷爆。我有一次本地跑 dev server，忘了关 CSP report，结果测试接口被打了几千次，数据库直接卡死。现在我的构建脚本会自动判断环境，只在 prod 注入 report 配置。

实际项目中的坑

除了配置问题，落地时还有几个细节要注意。

首先是报告频率。浏览器不会每违规一次就发一次报告，它会做采样和去重。比如同一页面重复加载同一个违规资源，可能只报一次。所以别指望靠 report-to 做实时监控，它更适合做趋势分析。我之前想用它做“实时告警”，结果发现延迟高、漏报多，最后还是加了前端手动埋点作为补充。

其次是数据格式。CSP 报告的 body 是 JSON，但 content-type 是 application/csp-report，不是常见的 application/json。有些后端框架（比如 Express）默认不解析这种类型，需要手动加 middleware。我用的 Koa 就得这么处理：

app.use(async (ctx, next) => {
  if (ctx.request.type === 'application/csp-report') {
    ctx.request.body = JSON.parse(ctx.request.rawBody);
  }
  await next();
});

不然 ctx.request.body 会是空的，你收不到任何数据。

再就是日志存储和分析。别直接把报告存数据库就完事。我建议至少加两个字段：来源页面 URL（从 report 的 document-uri 拿）、用户代理（User-Agent）。这样才知道是哪个页面、哪种设备出的问题。有次我们发现某个安卓机型大量报错，定位后发现是厂商定制 ROM 修改了 WebView 行为，导致 inline script 被误判——没有 UA 字段根本没法排查。

最后提一嘴：report-to 不止用于 CSP。它还能配合其他安全策略，比如 Permissions-Policy（原 Feature-Policy）的违规报告。不过目前浏览器支持度还不高，我试过但没敢上生产。如果你项目要求不高，可以玩玩，但别依赖它。

核心代码就这几行

为了方便你直接抄，我把完整的前后端示例贴出来。Nginx 配置：

add_header Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline'; report-to csp-endpoint;";
add_header Reporting-Endpoints 'csp-endpoint="https://jztheme.com/api/csp-report"';

Node.js 接收端（Express）：

const express = require('express');
const app = express();

// 解析 CSP report
app.use(express.json({ type: 'application/csp-report' }));

app.post('/api/csp-report', (req, res) => {
  const report = req.body;
  console.log('CSP Violation:', report);
  // 这里存数据库或发日志系统
  res.status(204).end(); // 必须返回 204 或 2xx
});

注意：返回状态码必须是 2xx，最好是 204。如果返回 4xx/5xx，浏览器可能会重试，甚至指数退避，导致你的服务被压垮。

结尾叨叨

以上是我这几年用 report-to 踩坑后的总结。说实话，这套机制还不够成熟，浏览器实现也有差异，但总比没有强。至少能帮你发现那些“我以为没问题”的 CSP 配置漏洞。

目前我的方案还留了个小尾巴：移动端 WebView 的 report 支持不太稳定，有些老版本根本不发。所以关键业务还得靠手动上报兜底。但这套配置在桌面端和现代移动浏览器上已经够用了。

以上是我个人对 report-to 的完整讲解，有更优的实现方式欢迎评论区交流。这个技巧的拓展用法还有很多，后续会继续分享这类博客。