CSP 内容安全策略实战：从白屏踩坑到灰度上线

1. 从一次页面白屏说起CSP 到底在管什么第一次被 CSP 绊倒是几年前接手一个老项目的时候。页面在本地跑得好好的部署到线上之后样式全丢、图标全裂、控制台一片红报错信息里反复出现Refused to load the stylesheet、Refused to execute inline script这类字样。当时第一反应是资源路径写错了查了半天 CDN、查了 Nginx 配置最后才发现是响应头里多了一条Content-Security-Policy。那一刻我才真正意识到这个平时容易被忽略的 HTTP 响应头其实是一道相当严格的资源准入闸门。Content Security Policy简称 CSP中文一般叫内容安全策略。它本质上是服务器通过 HTTP 响应头或者 HTML 里的 meta 标签告诉浏览器这个页面只允许加载哪些来源的脚本、样式、图片、字体、iframe 等等。浏览器拿到这份白名单之后就会严格执行凡是名单之外的资源一律拒绝加载或执行。它最核心的目标是防 XSS跨站脚本注入——即便攻击者成功往页面里塞了一段恶意脚本只要这段脚本的来源或形式不在白名单里浏览器就不会执行它。很多人对 CSP 有个误解觉得它是锦上添花的安全配置配不配都行。实际上在防御 XSS 这件事上CSP 是少数能在注入已经发生之后仍然兜底的机制。输入过滤、输出转义这些手段是在入口堵而 CSP 是在执行这一层堵。两者是不同维度的防线不能互相替代。这篇内容我会把 CSP 的指令体系、nonce 与 hash 的实战用法、report-only 的灰度策略、以及上线过程中那些让人抓狂的坑按我自己的踩坑顺序讲清楚。适合正在做前端安全加固、或者被 CSP 报错搞得一头雾水的同学参考。2. 指令体系拆解白名单是怎么一层层收紧的2.1 默认兜底指令 default-src 的一票否决逻辑CSP 的指令有几十个但真正决定整体松紧的是default-src。它的作用是给所有没有单独指定的资源类型提供一个兜底值。也就是说如果你只写了default-src self那么脚本、样式、图片、字体、连接请求等等全部默认只允许同源。这个设计非常关键因为它意味着你可以用一条指令快速收紧整个页面然后再针对个别类型放宽。我一般建议新手从default-src self起步而不是一上来就写一大堆具体指令。原因很简单先收紧再按报错逐个放开比先放开再收紧要安全得多。反过来如果你先写了default-src *那基本等于没配因为任何来源都被允许了。这里有个容易踩的坑default-src不会覆盖那些有自己默认行为的指令。比如base-uri、form-action、frame-ancestors这几个它们不受default-src影响需要单独配置。我见过不少人以为写了default-src self就万事大吉结果表单还是能被提交到外部地址就是因为漏了form-action。2.2 script-src 与 style-src内联代码才是真正的麻烦真正让 CSP 落地困难的几乎都是script-src和style-src。外链资源好办把域名加进白名单就行难的是内联脚本和内联样式。所谓内联就是直接写在 HTML 里的script.../script和style...或者style.../style。默认情况下只要你的 CSP 里没有unsafe-inline所有内联脚本和内联样式都会被拦截。这个限制非常有效因为大量 XSS 攻击就是靠注入一段内联脚本来实现的。但问题是很多老项目、很多前端框架、很多第三方统计代码都依赖内联脚本。于是就有了两条出路要么加unsafe-inline等于自废武功要么用nonce或hash精确放行。unsafe-inline这个词本身就带着警告意味。一旦加上CSP 对 XSS 的防御能力会大幅下降因为攻击者注入的内联脚本同样会被执行。所以我的原则是能不用就不用实在要用也要配合nonce一起让unsafe-inline在支持 nonce 的浏览器里自动失效。2.3 那些容易被忽略但很关键的指令除了脚本和样式还有几个指令值得单独拎出来说。connect-src控制的是 fetch、XHR、WebSocket 这类连接请求的目标。很多项目只配了script-src结果前端调接口的时候被拦了报错信息还不太直观排查起来很费劲。如果你的接口域名和页面不同源一定要记得加进connect-src。img-src控制图片加载。这个相对宽松但要注意data:协议。很多图标、占位图用的是 base64 内联如果不加data:这些图会全部裂掉。frame-ancestors控制的是谁可以把我的页面嵌进 iframe。它其实是用来替代老的X-Frame-Options头的而且功能更强支持多个来源。注意这个指令只在响应头里生效写在 meta 标签里是无效的。report-uri和report-to是上报指令用来接收违规报告。这个在灰度阶段极其重要后面会专门讲。下面这张表是我整理的高频指令对照方便快速查阅指令控制对象常见取值备注default-src所有资源的兜底self不覆盖 base-uri 等script-srcJS 脚本self nonce-xxx内联需 nonce/hashstyle-srcCSS 样式self unsafe-inline内联样式常见痛点img-src图片self data: https:注意 data: 协议connect-srcfetch/XHR/WSself https://api.xxx接口域名别漏frame-ancestors被嵌套none self仅响应头生效form-action表单提交self不受 default-src 管3. nonce 与 hash给内联代码开一扇精确的门3.1 nonce 的工作原理与每次请求都要变的铁律nonce 是 number used once 的缩写直译就是一次性随机数。它的用法是服务器在每次返回 HTML 时生成一个随机字符串把它同时写进 CSP 响应头和页面里的script标签。浏览器比对两者一致才执行。具体长这样Content-Security-Policy: script-src nonce-a1b2c3d4e5script noncea1b2c3d4e5 console.log(这段脚本会被执行); /script这里最关键的一点也是最多人踩的坑nonce 必须每次请求都重新生成绝对不能写死。我见过有团队图省事把 nonce 硬编码成一个固定值结果等于给攻击者留了一把万能钥匙——攻击者只要在自己的注入脚本上加上同样的 nonce就能绕过 CSP。nonce 的安全性完全建立在不可预测和一次性上一旦固定防御就形同虚设。生成 nonce 要用密码学安全的随机数长度建议至少 128 位。Node.js 里可以用crypto.randomBytes(16).toString(base64)其他语言也都有对应的安全随机接口。不要用Math.random()这种伪随机它的可预测性太强。3.2 hash 方案适合静态内联脚本的另一种选择如果内联脚本的内容是固定的、不常变的用 hash 会比 nonce 更省事。hash 的原理是把内联脚本的内容做一次哈希支持 sha256、sha384、sha512把哈希值写进 CSP浏览器计算页面里脚本的哈希匹配才执行。Content-Security-Policy: script-src sha256-xxxxxxxxxxxxxxxxxxxxxxxxxxxhash 的好处是不需要服务器动态生成适合静态页面或者构建时就能确定内容的场景。坏处也很明显脚本内容只要改一个字哈希就变了必须重新计算并更新 CSP。所以它更适合那些万年不变的初始化脚本。实际项目中nonce 和 hash 经常混用。比如主体用 nonce个别固定的内联脚本用 hash。两者可以同时出现在script-src里浏览器会分别校验。3.3 用 nonce 之后为什么 unsafe-inline 会自动失效这是一个很多人不知道的细节但非常重要。当script-src里同时存在nonce-xxx和unsafe-inline时支持 nonce 的现代浏览器会忽略unsafe-inline。这个设计的初衷是让老浏览器不支持 nonce还能用unsafe-inline兜底而新浏览器则享受 nonce 的严格保护。这个特性带来一个很实用的灰度技巧你可以先同时写上unsafe-inline和 nonce让页面先跑起来然后逐步给内联脚本加上 nonce。等所有内联脚本都带上 nonce 之后再把unsafe-inline删掉。整个过程页面不会白屏平滑过渡。不过要注意这个自动失效只对script-src和style-src里的unsafe-inline生效而且前提是浏览器确实支持 nonce。所以它是个过渡手段不是长期方案。4. 灰度上线report-only 是 CSP 落地最靠谱的姿势4.1 直接上强制策略大概率会翻车我强烈不建议任何项目一上来就用强制模式也就是直接写Content-Security-Policy头。原因很现实你永远不知道自己页面里到底加载了多少来源的资源。第三方统计、客服插件、地图 SDK、字体服务、埋点脚本……这些东西往往是不同时期、不同人加进去的没人能完整列出来。直接上强制策略结果就是页面各种功能悄悄失效而且有些失效不报错只是不工作排查成本极高。正确的做法是先上Content-Security-Policy-Report-Only。这个头的作用是策略照常校验但只上报违规不真正拦截。页面功能完全不受影响你却能收到一份完整的违规清单知道哪些资源会被拦。Content-Security-Policy-Report-Only: default-src self; report-uri /csp-report4.2 违规报告长什么样怎么收集浏览器在检测到违规时会向report-uri指定的地址 POST 一段 JSON。内容大致包括被拦截的资源地址blocked-uri、违反的指令violated-directive、当前页面地址document-uri等。{ csp-report: { document-uri: https://example.com/page, violated-directive: script-src, blocked-uri: https://cdn.third.com/track.js, original-policy: default-src self } }收集端我一般用一个简单的接口把报告落库然后按blocked-uri和violated-directive聚合。这样一眼就能看出哪些域名被拦得最多、哪些指令最容易触发。这些高频域名就是你要加进白名单的候选。这里有个实操心得报告量可能非常大尤其是页面多、流量大的站点。一定要做聚合和采样不然日志会被冲爆。另外report-uri已经被标记为废弃新标准是report-to但report-to的配置更复杂需要配合Report-To头定义端点组。目前实践中两者可以同时写兼容性最好。4.3 从 report-only 到强制模式的推进节奏我的推进节奏一般是这样的先跑一到两周 report-only把报告里的域名分类整理。然后按确定要放行和需要改造两类处理。确定要放行的比如公司自己的 CDN、必要的第三方服务直接加白名单需要改造的比如内联脚本安排加 nonce。等报告里的违规数量降到很低、且剩下的都是已知可接受的情况时再切换到强制模式。切换也不要一次性全量可以先按流量比例灰度比如先放 5% 的流量用强制策略观察一段时间没问题再逐步放大。这个思路和发布新功能是一样的稳字当头。5. 上线后那些让人抓狂的报错与排查链路5.1 样式全丢style-src 与内联样式的恩怨CSP 上线后最常见的现象就是样式丢失。原因通常是style-src没配好或者页面里有大量内联style属性。很多 UI 框架、组件库会在运行时动态往元素上写style这些都属于内联样式会被style-src拦截。排查链路是这样的先看控制台有没有Refused to apply inline style的报错。如果有确认是style-src缺了unsafe-inline还是缺了 nonce。如果是框架动态写入的nonce 往往不好加因为不是服务端渲染的这时候要么给style-src加unsafe-inline样式注入的风险相对脚本低一些要么改造框架的样式注入方式。我的经验是style-src的unsafe-inline可以适当放宽因为纯 CSS 的 XSS 风险远小于 JS。但script-src的unsafe-inline一定要尽量避免。这个取舍要基于实际风险评估不能一刀切。5.2 接口调不通connect-src 漏配的隐蔽性connect-src漏配导致的报错特别隐蔽因为前端代码里 fetch 失败可能被 try-catch 吞掉或者只表现为数据加载失败看不出是 CSP 拦的。控制台里会有Refused to connect to xxx的报错但如果你没往 CSP 方向想很容易误判成网络问题或后端问题。我踩过一次前端调一个第三方地图的接口一直超时。查了半小时网络最后发现是connect-src没放行那个域名。从那以后我排查接口不通类问题时会习惯性先看一眼控制台有没有 CSP 报错。5.3 第三方脚本的连锁反应第三方脚本是 CSP 落地最大的变数。一个统计脚本它自己可能还会去加载别的资源、发别的请求、甚至动态创建 iframe。你放行了主脚本的域名不代表它依赖的所有资源都放行了。结果就是主脚本能加载但它内部的功能悄悄失效。处理这类问题的办法是在 report-only 阶段重点观察第三方脚本相关的违规报告。把某个第三方脚本触发的所有blocked-uri都收集起来一次性放行。同时要评估这个第三方是否值得信任——如果它加载的资源来源特别杂可能要考虑换一个更规范的替代品。下面这张表是我总结的常见报错与对应排查方向控制台报错关键词涉及指令排查方向Refused to execute inline scriptscript-src加 nonce 或 hashRefused to apply inline stylestyle-src加 unsafe-inline 或 nonceRefused to load the stylesheetstyle-src放行 CSS 域名Refused to connect toconnect-src放行接口域名Refused to frameframe-src放行 iframe 来源Refused to load the imageimg-src放行图片域名或 data:6. 几个容易被忽视的细节与长期维护建议6.1 meta 标签与响应头的差异CSP 可以写在 HTML 的meta http-equivContent-Security-Policy里也可以写在 HTTP 响应头里。两者大部分情况下等价但有几个关键差异frame-ancestors、report-uri、sandbox这几个指令只能在响应头里生效写在 meta 里会被忽略。另外 meta 标签的解析时机比响应头晚理论上存在一个极短的无保护窗口。所以生产环境我建议优先用响应头meta 只作为兜底或静态页面的补充。6.2 别把 CSP 当成唯一防线CSP 很强但它不是万能的。它防不住服务端漏洞、防不住 CSRF、也防不住那些合法来源被攻陷后注入的脚本。所以它必须和输入校验、输出转义、HttpOnly Cookie、CSRF Token 这些手段配合使用。把 CSP 当成纵深防御里的一层而不是全部。另外CSP 对老版本浏览器的支持有限有些指令在旧浏览器里会被忽略。如果你的用户群体里有大量老浏览器要做好降级预案别指望 CSP 在所有环境下都生效。6.3 把 CSP 纳入构建与监控流程CSP 策略不是配一次就完事的。前端迭代快今天加个第三方 SDK明天换个 CDN都可能让策略失效。我的做法是把 CSP 策略文件纳入版本管理和代码一起走 review。同时在 CI 里加一个检查如果新增了外部资源引用提醒开发者同步更新 CSP。监控方面即使切换到强制模式也建议保留 report 上报强制模式下同样可以上报违规。这样一旦有新的资源被拦你能第一时间从报告里发现而不是等用户反馈页面坏了。6.4 一个关于 nonce 缓存的坑最后分享一个很隐蔽的坑如果你的页面被 CDN 或反向代理缓存了而 nonce 是每次请求动态生成的那么缓存下来的 HTML 里的 nonce 和后续请求响应头里的 nonce 就对不上了导致脚本全部被拦。这个问题的根源是动态 nonce和页面缓存天然冲突。解决办法有几个一是对带 nonce 的页面禁用缓存二是让缓存层感知 nonce把 nonce 作为缓存键的一部分但这样缓存命中率会很低三是改用 hash 方案因为 hash 不依赖每次请求变化。具体选哪个要看你的架构但一定要在上线前想清楚不然会踩得很惨。CSP 这东西配置本身不难难的是摸清一个存量项目里到底有多少隐藏的资源依赖。我的建议永远是先 report-only 跑起来让数据说话再一步步收紧。急不得也省不得。