report-uri实战指南从配置到CSP策略落地全流程

先看效果，再看代码

上周上线一个新项目，上线第二天就发现 CSP 报告里一堆 script-src 违规记录——但页面明明没报错，用户也完全没感知。我打开 report-uri 后台一看，全是 eval() 和内联 script 被拦掉的报告，来源是某个第三方统计 SDK 的兼容性 fallback 逻辑。

这事儿让我意识到：report-uri 不是配完 header 就完事的，它真正在帮你“看见”那些你根本没意识到正在发生的违规行为。而且，它不是报警器，是显微镜。

下面是我目前在用的几套实战配置，亲测有效，直接抄就能跑通。

最简可行版：一行 header + 一个接收端

先上最基础但足够用的配置（Nginx）：

add_header Content-Security-Policy "default-src 'self'; script-src 'self' https:; report-uri https://jztheme.com/csp-report";

注意：这里用的是 report-uri（CSP v2），不是 report-to（v3）。别急着升级，很多老浏览器（比如 iOS 14.5 之前的 Safari）压根不支持 report-to，我踩过坑，切过去后漏报率翻倍。

接收端用 PHP 写了个极简脚本（部署在 https://jztheme.com/csp-report）：

<?php
if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
    http_response_code(405);
    exit;
}

$content = file_get_contents('php://input');
if (empty($content)) {
    http_response_code(400);
    exit;
}

// 防止乱码和注入，只存 JSON 原文
file_put_contents('/var/log/csp-reports/' . date('Y-m-d') . '.log', $content . "n", FILE_APPEND | LOCK_EX);

http_response_code(204);

这个脚本不解析、不校验、不转发，就 raw 存盘。为什么？因为早期我加了 JSON 解析+入库+邮件通知，结果某天 CSP 报告暴增（页面被爬虫大量触发 inline script 检查），直接把 MySQL 连接池打爆了。现在改成纯文件写入，稳如老狗。

这个场景最好用：区分开发/测试/生产环境

我们有三套环境，但不想每套都搭一套 report-uri 接收服务。我的做法是：用同一个 endpoint，靠 Report-To 的 group 名或请求头里的 X-Env 区分。

不过更轻量的做法是——在 header 里动态拼 report-uri 地址：

<!-- 在 HTML head 中动态注入（Vue/React 项目常用） -->
<meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self' 'unsafe-inline'; report-uri /csp-report?env=prod">

然后后端路由根据 query 参数分流日志路径。或者更干脆点，在 Nginx 里做判断：

set $report_uri "/csp-report";
if ($host ~ "^staging.") {
    set $report_uri "/csp-report?env=staging";
}
if ($host ~ "^dev.") {
    set $report_uri "/csp-report?env=dev";
}
add_header Content-Security-Policy "default-src 'self'; report-uri $report_uri";

亲测有效，不用改任何业务代码，运维同学也能看懂。

踩坑提醒：这三点一定注意

• CORS 问题不是你想的那样：很多人以为 report-uri 是 POST 请求，所以得配 CORS。错！report-uri 是浏览器自发行为，不走 fetch/XHR，不受 CORS 策略限制。但如果你在接收端返回了 Access-Control-Allow-Origin: *，反而会干扰某些旧版 Edge 的处理逻辑——我亲眼见过它导致报告静默丢弃。建议：接收端不要返回任何 CORS 头。
• report-uri 不能带 query 参数？其实可以，但要小心：比如你写成 report-uri https://jztheme.com/csp-report?token=abc，浏览器会原样发送。但有些 CDN（比如 Cloudflare）默认 strip query，或者 WAF 规则拦截带 token 的请求。我折腾了半天发现是 WAF 把所有含 = 的 POST 请求给干掉了。解决方案：用 path 代替 query，比如 /csp-report/prod。
• 日志爆炸时怎么限流？别自己写队列：某次活动页上线后，report-uri 一小时收了 8 万条报告（全是某安卓 WebView 的 bug 导致的重复上报）。我原本想加 Redis 计数限流，后来发现——直接用 Nginx 的 limit_req 就够了：

limit_req_zone $binary_remote_addr zone=csp_report:10m rate=10r/s;

location = /csp-report {
    limit_req zone=csp_report burst=20 nodelay;
    fastcgi_pass php-fpm;
    # ... 其他配置
}

10r/s 对单个 IP 来说绰绰有余，既防刷又不误伤真实用户。

进阶技巧：把 report-uri 和 sourcemap 关联起来

光知道“某行某列执行了 eval”没用，得定位到具体哪段源码。我们在构建时把 sourcemap 上传到私有 S3，并在 report-uri 收到报告后，自动匹配 source、line、column，反查原始文件名和代码片段。

关键不是技术多炫，而是加了一层 mapping 表：

{
  "https://cdn.example.com/app.min.js": "src/index.ts",
  "https://cdn.example.com/vendor.min.js": "node_modules/react/index.js"
}

收到报告后查表 + 下载 sourcemap + 解析，整个过程控制在 200ms 内。不是必须，但排查线上 CSP 误报时真的省两小时。

最后说句实在话

report-uri 不是银弹，它不会帮你自动修复 XSS，也不会让老板觉得你“安全做得好”。但它会让你第一次真正看清——你的页面到底在哪些地方偷偷调用了 unsafe-eval，哪些 CDN 域名被用户本地插件篡改了，甚至哪些安卓 WebView 版本存在 CSP 实现 bug。

我们线上所有项目现在都开着 report-uri，但只对错误级别 >= medium 的报告发企业微信提醒。低频、偶发、明显是爬虫/插件触发的报告，就让它静静躺在日志里。安全不是越严越好，是越清楚越好。

以上是我踩坑后的总结，希望对你有帮助。这个技巧的拓展用法还有很多，后续会继续分享这类博客，比如如何用 report-uri 反向追踪第三方 SDK 的资源加载行为、怎么结合 Prometheus 做 CSP 违规趋势监控——这些都不是理论，都是我在上线前一周刚落地的东西。