CSP内容安全策略实战：白名单、nonce与灰度上线

CSP 的全称是 Content Security Policy，中文一般叫内容安全策略，是浏览器原生提供的一套资源加载白名单机制。你在响应头里发一条策略过去，告诉浏览器这个页面允许从哪些地方取 JS、允许哪些地址发请求、允许谁把页面嵌进 iframe，浏览器就照着这条规则执行，凡是没被点名的来源一律拦截。它要解决的是一个很现实的问题：当页面上不可避免地出现了意料之外的脚本时，怎么把损失摁在一个可控的范围内。输入过滤、输出转义、模板自动编码这些手段，思路都是“别让脏东西进来”；而 CSP 的立足点完全不同，它假定脏东西已经在页面里了，那至少限制它不能干什么、不能把数据往哪儿送。这套机制适合所有需要对外提供网页的团队，不管是内容站点、后台管理系统，还是嵌在别人 App 里的 H5 页面；对刚接触前端安全的人，它也是一条最容易见效、最能看见实际拦截效果的抓手。

1. 先弄清楚 CSP 到底在防什么

1.1 从一次典型的脚本注入说起

假设某内容平台的文章详情页，编辑器允许作者粘贴带格式的 HTML，后端做了关键词过滤，但漏掉了某个不常见的标签属性。攻击者把一段脚本塞进文章正文，页面渲染时脚本直接执行，把当前用户的登录态凭据读出来，打包发到一台外部服务器上。整个过程用户没有任何感知，页面看起来完全正常。

这类问题的麻烦之处在于，出问题的位置非常分散：可能是编辑器、可能是评论组件、可能是某个第三方 SDK 动态插入的节点、也可能是老代码里残留的一段innerHTML。你很难保证全站每一个拼接点都干净。CSP 的价值就在这里——它不关心脏数据是从哪个缝里钻进来的，它只关心“这段脚本是不是我点过名的”。上面那个例子里，如果页面策略里script-src只允许自家域名和带 nonce 的脚本，那么攻击者注入的那段内联脚本就会被浏览器直接拒绝执行，控制台报一条违规记录，数据一个字节都发不出去。

我在实际项目里见过太多团队把精力全押在“过滤输入”上，结果一个运营活动页的富文本编辑器绕过了规则，全线失守。CSP 不是万能的，但它是那种“加了之后能立刻把攻击面砍掉一大块”的东西，性价比极高。

1.2 核心模型：白名单加浏览器强制执行

理解 CSP，抓住两个关键词就够了：白名单和浏览器强制执行。

白名单的意思是，默认全部拒绝，只放行你明确列出来的东西。这和传统的“黑名单过滤”思路正好相反。黑名单永远在追着攻击者跑，人家换个写法你就漏了；白名单则要求你先把自家页面到底依赖哪些外部资源梳理清楚，梳理完写进策略，剩下的全关掉。

浏览器强制执行的意思是，这条规则不是靠代码自觉遵守的，是浏览器内核在资源加载、脚本执行、表单提交这些环节上硬性拦截的。哪怕你的业务代码写了element.innerHTML = 用户输入，只要那段脚本不符合策略，它就不会执行。这一点非常关键——它把安全兜底从“业务开发者的事”变成了“平台层面的事”，一次配置，全站生效。

不过要提醒一句，白名单的边界是浏览器那一侧。如果攻击者不用脚本，而是用别的方式把数据带出去（比如构造一张指向外部域名的图片，把数据拼在 URL 参数里），那就得靠img-src、connect-src这类指令去封堵出口。CSP 的完整形态，是同时管“进来的资源”和“出去的请求”两头。

1.3 它填补的正是“代码写错”这个空档

安全防护最怕的就是“假设代码都是对的”。现实里代码一定会有写错的时候，尤其是在多人协作、历史包袱重、第三方组件多的项目里。CSP 的定位很明确：它是防御体系里的最后一道，专门负责接住那些“本该防住但没防住”的情况。

我把常见防护手段的分工整理成了一张表，方便对照理解各自的位置：

从表里能看出来，前面几项都是“点”上的防御，覆盖面取决于你有没有想到那个点；CSP 是“面”上的防御，它不依赖你想到什么，只依赖你把白名单写对。这也是为什么在成熟的安全体系里，CSP 通常被放在比较靠底的位置，和其他手段叠加使用，而不是互相替代。

2. 指令体系拆解：一条策略到底由什么组成

2.1 策略字符串的语法结构与指令族

一条 CSP 就是一个字符串，由若干条指令组成，指令之间用分号隔开，每条指令内部用空格分隔取值。写成这样：

Content-Security-Policy: default-src 'self'; script-src 'self' 'nonce-abc123'; object-src 'none'

拆开看就是三条指令：default-src兜底，script-src管脚本，object-src管插件类对象。每条指令后面的那些取值，统称源表达式，可以有多个，取“或”的关系——只要匹配上其中一个就放行。

指令大概可以分成几族，我按用途理一下：

• 资源加载族：default-src、script-src、style-src、img-src、font-src、media-src、connect-src、worker-src、manifest-src、child-src、frame-src、object-src。这一族管的是“页面能从哪儿取东西”。
• 文档行为族：base-uri、form-action、frame-ancestors、sandbox。这一族管的不是资源加载，而是文档本身的行为边界，比如 base 标签能指向哪、表单能提交到哪、谁能嵌我。
• 上报族：report-uri、report-to。违规记录往哪儿送。
• 杂项：upgrade-insecure-requests（把 http 请求自动升级成 https）、block-all-mixed-content（已被前者基本取代）。

这里有个非常容易踩的点：default-src不是万能的兜底。它管不到base-uri、form-action、frame-ancestors、sandbox、report-uri这几个。也就是说，你写了default-src 'self'，页面上照样能插一个<base href="https://别的域">把相对路径全指歪，也照样能让表单提交到外部地址。这几个必须单独写，别漏。

2.2 源表达式的写法与匹配逻辑

源表达式是写策略时最常打交道的部分，写错了要么误伤要么形同虚设。常见几类：

• 'none'：什么都不允许，注意它必须单独出现，不能和其他表达式并列，写成'none' https://a.com是无效的。
• 'self'：指同源，即协议、域名、端口三者全一致。
• 'unsafe-inline'：允许内联脚本、内联样式、内联事件处理器。这是最常被误用的一个，很多人图省事加上它，结果策略基本等于没写。
• 'unsafe-eval'：允许eval、new Function、setTimeout传字符串这类动态执行。
• 主机源：形如https://cdn.example.com、*.example.com、https://example.com:8080/path/。注意末尾的路径匹配是前缀匹配，https://a.com/api/能匹配https://a.com/api/x.js。
• 协议源：https:、data:、blob:、mediastream:。data:和blob:要谨慎，它们是脚本注入的常见跳板。
• nonce 与 hash：'nonce-随机串'、'sha256-摘要值'，后面单独讲。

有一个反直觉的规则必须记住：在支持 CSP3 的浏览器里，如果script-src同时包含 nonce 或 hash 和'unsafe-inline'，'unsafe-inline'会被直接忽略。这是规范里专门设计的，防止有人为了兼容老页面顺手加上'unsafe-inline'把 nonce 机制废掉。我刚接触时不理解这条，调试了半天以为浏览器有 bug，其实是我自己写错了。

还有一个：多条 CSP 策略同时存在时，取的是交集。比如你通过响应头下发一条，页面上又通过 meta 标签下发一条，两条会同时生效，各自都要满足才算通过。这既是保护（别人没法用 meta 把你的策略放宽），也是坑（排查时得把所有策略都捞出来看）。

2.3 几条容易被忽略但价值极高的指令

写了script-src就等于做完 CSP 了吗？远远不够。下面几条我建议不管什么项目都加上，成本低、收益高。

object-src 'none'。<object>、<embed>、<applet>这几个标签早年是挂马的重灾区，现在正规业务基本不用了。直接关掉，没有任何副作用。很多团队的起步策略就是default-src 'self'; object-src 'none'，先拿这两条上线。

base-uri 'none'或base-uri 'self'。攻击者如果能注入一个<base>标签，就能把页面上所有相对路径的请求全部劫持到自己的域名。这个攻击手法非常隐蔽，因为页面看起来一切正常，但脚本、样式全从外部加载了。业务里如果确实没用 base 标签，直接'none'。

form-action 'self'。限制表单能提交到哪儿。注入一段<form action="https://外部地址">自动提交，是很经典的数据外带手法。加上这条就堵住了。

frame-ancestors 'none'。这是给“谁能嵌我”设限，等价于X-Frame-Options的加强版，而且支持多域名白名单。注意它不能写在 meta 标签里，只能走响应头。

upgrade-insecure-requests。页面里历史遗留的 http 资源会自动升级成 https 请求，省得一个个改。不过要留意，如果那个资源本身不支持 https，升级后会直接加载失败，所以上线前得先把资源清单过一遍。

把这些指令和script-src放一起，一条相对完整的起步策略大概长这样：

Content-Security-Policy: default-src 'self'; script-src 'self' 'nonce-{每次请求生成}' 'strict-dynamic'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; connect-src 'self' https://api.example.com; font-src 'self'; object-src 'none'; base-uri 'none'; form-action 'self'; frame-ancestors 'self'; upgrade-insecure-requests; report-uri /csp-report

style-src里留了'unsafe-inline'，这是很多团队的妥协——CSS-in-JS 方案和大量历史内联样式，全改完成本太高，而且样式注入的危害等级远低于脚本注入，可以先放着。但script-src绝对不能这么干。

2.4 nonce、hash、strict-dynamic 的组合打法

现代前端框架基本都会在页面里输出内联脚本（比如 SSR 时的初始状态注入），纯靠域名白名单根本管不住。这时候就得上 nonce 或 hash。

nonce 的用法是：服务端每次渲染页面时生成一个随机串（要求密码学安全、不可预测、每次请求都换），把它写进 CSP 头的script-src 'nonce-这个串'，同时在每个合法的内联<script>标签上加nonce="这个串"属性。浏览器执行时比对，对得上就放行。攻击者注入的脚本没有这个属性（他也猜不到随机串），直接被拦。

这里有几个实操要点：nonce 必须是每次请求重新生成，不能是固定值或者长期缓存；不能通过任何方式泄漏到页面内容里（比如别把它写进 DOM 属性让脚本能读到）；用了 CDN 或页面缓存的话，注意缓存层别把不同请求的 nonce 混在一起。

hash 的用法是：算出内联脚本内容的摘要（sha256/384/512），写进策略'sha256-摘要'。内容一变摘要就变，安全性很高。缺点是内联脚本只要改一个字符就得重新算，构建流程里得加自动化，手写不现实。

'strict-dynamic'是新世界的关键。加上它之后，浏览器会忽略策略里的主机白名单、'self'和'unsafe-inline'，改为“信任传递”：只要一个脚本是通过带 nonce（或 hash）的脚本动态创建<script>标签插入的，那它也被信任，它再创建的脚本同样被信任。这完美契合了现代前端“入口脚本 + 动态加载分包”的模式——你只需要给入口脚本加 nonce，后面所有异步 chunk 都自动放行。

但'strict-dynamic'有个兼容性陷阱：老浏览器不认识它，会退回到主机白名单逻辑。所以标准写法是把新老两套都带上，新浏览器走 nonce + strict-dynamic，老浏览器走域名白名单：

script-src 'nonce-abc' 'strict-dynamic' 'unsafe-inline' https: 'self'

看着很乱对不对？但这就是官方推荐的过渡写法。支持 CSP3 的浏览器会忽略后面的'unsafe-inline'、https:、'self'，只认 nonce；老浏览器不认识'strict-dynamic'和 nonce，退回用域名白名单。等业务侧的老浏览器占比降到可以忽略，再把后面那几个删掉。

3. 从 Report-Only 到全量上线的落地流程

3.1 第一步：用 Report-Only 摸清家底

直接把强制策略推上线，大概率是页面白屏、样式全丢、接口全挂。正确姿势是先上Content-Security-Policy-Report-Only这个头。它只上报不拦截，浏览器遇到违规照样加载，只是往你指定的地址发一条 JSON 报告。

这个阶段的唯一目标就是摸清家底：把线上所有页面的违规来源全捞出来，看看总共涉及多少个外部域名、多少处内联脚本、多少处eval调用。报告长这样：

{ "csp-report": { "document-uri": "https://example.com/article/123", "violated-directive": "script-src-elem", "effective-directive": "script-src-elem", "blocked-uri": "inline", "source-file": "https://example.com/static/app.js", "line-number": 1024, "column-number": 8891 } }

几个字段的含义要搞清楚：blocked-uri是inline说明是内联脚本被拦，是eval说明有动态执行，是具体 URL 说明是外部域名；source-file告诉你这个违规是哪个 JS 文件里触发的，排查时非常有用；violated-directive和effective-directive有时不一致，因为实际生效的是从default-src继承来的。

收集周期我一般建议至少跑满两周，覆盖完整的业务周期——有些后台页面一周才有人用一次，有些活动页只在特定时间上线。收集期太短就急着收紧，很容易漏掉低频页面。

注意：Report-Only 阶段的策略要和最终准备上线的策略尽量一致，别这边随便写写那边认真配置，否则收集到的数据和实际效果对不上。

3.2 第二步：把违规来源分类处置

报告收集回来，几百上千条，看着头皮发麻，但归类之后其实就几种。我的处理顺序是这样的：

第一类，外部域名。把所有出现过的外部域名列出来，一个个问：这个域名是不是业务必需的？是不是可信的？能不能换成自建或者代理转发？我见过不少项目里躺着一堆早年接入、现在根本没人用的统计脚本和客服插件，早该下线了。能删的删，能代理的代理，剩下的写进白名单。这里的判断原则是：白名单里的每一个域名，都必须有人能说清楚它是干什么用的。

第二类，内联脚本。大部分来自 SSR 的初始状态注入、埋点初始化、框架自带的运行时片段。处置方式有三种：能挪到外部文件的挪出去；不能挪的走 nonce；构建产物里的固定片段走 hash。实践中通常是 nonce 和 hash 混用——服务端渲染的走 nonce，构建期生成的内联片段走 hash。

第三类，eval类。这个要单独拿出来说，因为它往往意味着代码里有不该有的东西。常见来源是老的模板引擎（比如某些版本的模板库用new Function编译）、某些打包工具的运行时、以及业务代码里偷懒写的setTimeout("字符串")。这类要么升级依赖到支持 CSP 的版本，要么改写法。实在改不动的（比如某个老的三方图表库），只能单独给那个页面放宽策略，或者接受功能受损。

第四类，data:和blob:。图片走data:很常见，可以给img-src放行；但如果出现在script-src里，一定要查清楚是谁在动态构造脚本，这往往是注入点的信号。

分类处置完之后，你会拿到一份精简过的域名清单和一份需要改造的代码列表。改造工作可以和策略上线并行推进，先上宽策略，再逐步收紧。

3.3 第三步：灰度上线与分批收紧

改造做得差不多了，就可以从 Report-Only 切到强制模式。但别一次性全量，按下面的节奏走比较稳：

先把强制策略下到内部测试环境，让测试同学和内部用户跑一轮完整回归。然后按流量比例灰度，5%、20%、50% 这样往上加，每一档观察至少一天，重点看前端错误监控里的资源加载失败率、以及业务上的转化数据有没有异常。最后再全量。

上线初期保留报告通道，但这时候的报告量应该已经很低了，剩下的每一条都值得人工看一眼。我一般的做法是把报告按source-file聚合，每天扫一遍新增的来源，发现新东西就立刻追查。

还有一个容易忽略的环节：给策略留一个紧急降级开关。CSP 是响应头，最理想的形态是放在网关或者反向代理上，这样出问题时改一行配置就能回滚，不用等前端发版。如果只能写在应用代码里，那至少做成配置项，别硬编码。

4. 常见坑与排查实录

4.1 上线后页面白屏或样式错乱

这是最高频的故障。表现是页面能打开但一片空白，或者布局完全崩掉，控制台刷出一堆Refused to load ... because it violates the following Content Security Policy directive。

排查顺序我一般这么走：

第一步，看报错里的directive是哪条。如果是style-src，多半是内联样式或者style属性被拦了；如果是font-src，字体图标全变方块；如果是script-src，那就是页面根本没跑起来。

第二步，注意一个细节：style属性（行内样式）也归属于style-src，而且它不受'unsafe-inline'的完整支持——从 CSP3 开始，style-src加'unsafe-inline'能放行<style>标签，但要让style="..."属性生效，某些场景下还需要'unsafe-hashes'。很多 UI 库大量用行内样式，这一块如果不放行，页面直接变形。

第三步，看source-file定位到具体文件行号。有些违规是第三方 SDK 动态插入的，从业务代码里完全看不出来，只能靠报告反查。

紧急处理办法：如果确认是误伤且影响面大，立刻回滚策略，别在线上边调边试。回滚之后再在测试环境慢慢收紧。

提示：style-src和script-src的策略可以分开推进，先把脚本管死，样式暂时放宽，风险等级差得远，别为了追求“一步到位”把业务搞挂。

4.2 内联事件与动态执行的顽固残留

onclick="..."、onerror="..."这类内联事件处理器，在script-src没有'unsafe-inline'的情况下会被全部拦掉。老项目里这类写法非常多，尤其是模板里拼出来的字符串，比如"<a href='#' onclick='doSomething(" + id + ")'>"。

彻底改法是换成addEventListener加事件委托。但如果量太大一时改不完，实在没办法可以用'unsafe-hashes'配合 hash 白名单，给具体每一个内联处理器算 hash 放行。不过这条路维护成本极高——任何一个内联处理器的代码改了，hash 就得重算，我不推荐在有一定规模的项目里用。

另一个顽固点是javascript:伪协议，比如某些老代码里<a href="javascript:void(0)">。这个也被script-src管着，同样会被拦。好在现代框架基本不用了，Vue 和 React 里写href="#"加preventDefault更常见。

eval类的排查稍微麻烦些，因为报错里blocked-uri只写eval，不告诉你具体是哪行。我的办法是在测试环境临时把'unsafe-eval'加上，然后用开发工具的断点或者给window.eval打补丁，把调用栈打出来，定位到具体依赖之后再决定是升级还是替换。

4.3 违规上报的噪音治理与端点设计

报告通道上线之后，你会收到大量重复、无效、甚至伪造的报告。治理这件事有几个实操要点。

去重和限流。浏览器对同一类违规在同一页面内的上报是有节流的，但多页面叠加起来量还是很大。服务端一定要做聚合，按document-uri的路径模式 +blocked-uri+violated-directive做归并计数，别一条条往数据库里塞。

别把上报端点做成新的攻击面。这个端点是对外开放的，任何人都能往里灌数据。几个基本要求：限制请求体大小（比如 8KB 以内）、只接受application/csp-report和application/reports+json、做频率限制、写入前做严格的字段白名单校验、上报内容不落原始 HTML。千万别把上报的 URL 直接渲染回某个管理后台，那就是自己给自己造了个存储型注入。

report-uri和report-to的关系。report-uri是老规范，兼容性好；report-to是新规范，依赖Report-To响应头配置端点组，能上报更多类型的报告（崩溃、网络错误等）。目前的稳妥做法是两个都写，浏览器优先用认识的。

注意多条策略时的上报行为。页面同时存在多条 CSP 时，report-uri只有第一条策略里的会生效（其他策略的报告会被忽略）。如果你既有网关下发的策略，又有应用下发的策略，得确认一下是哪条先到。

4.4 常见问题速查表

我把这几年前前后后踩过的坑整理成一张表，遇到问题可以先对着扫一眼：

5. 和其他防护手段怎么搭配使用

5.1 CSP 不替代转义，两者是纵深关系

有一种很危险的想法：既然 CSP 能拦住脚本执行，那输出转义就可以松一点了。这个思路必须打住。

原因在于，CSP 管的是“脚本能不能执行”，管不了“HTML 结构有没有被篡改”。攻击者就算不能执行脚本，依然可以注入一段伪造的登录表单、可以覆盖页面上的关键按钮、可以做界面伪装。这些都不触发 CSP 违规，但危害一点不小。而且 CSP 策略一旦有某个漏洞（比如某个页面漏配了、某个白名单域名上有可控的上传点），所有依赖它的防线会同时失效。

我的建议是把 CSP 当成纵深防御里的一层，而不是唯一一层。转义照做，参数化查询照写，HttpOnly 标记照加，CSP 是在这些之上再叠一层。真出事的时候，往往是多层同时拦住了才没造成实际损失。

5.2 和子资源完整性校验、Trusted Types 的配合

子资源完整性校验（SRI）解决的是“第三方 CDN 上的脚本被人换了”这个问题，通过在<script>标签上加integrity属性，浏览器比对内容摘要，对不上就拒绝加载。它和 CSP 是互补的：CSP 管“从哪个域名加载”，SRI 管“加载到的内容是不是我要的那份”。第三方域名在你的白名单里，但它自身被攻破的情况是真实存在的，SRI 就是为这种情况准备的。

Trusted Types是从另一个角度堵口子。CSP 管执行，SRI 管完整性，Trusted Types 管的是“危险赋值”。它把innerHTML、eval、document.write这些危险入口做了收敛，要求传入的必须是经过策略处理过的“可信类型”对象，普通字符串直接传会被拒绝。配合 CSP 里的require-trusted-types-for 'script'使用，能把 DOM 型注入的绝大部分入口堵死。

不过 Trusted Types 的改造成本不低，第三方库不一定兼容，通常是大型项目在 CSP 已经稳定跑起来之后的下一阶段目标。我一般建议的推进顺序是：先上基础 CSP（object-src、base-uri、frame-ancestors这些低风险指令），再上script-src的 nonce 化，稳定之后考虑 SRI，最后才评估 Trusted Types。

6. 我个人在实际操作中的几点体会

CSP 这东西最反直觉的地方在于，它不是一个“配好就完事”的东西，而是一个需要长期维护的活配置。业务每接一个新的第三方服务、每上一次新的营销活动、每换一个前端框架版本，都可能引入新的违规来源。如果没有一个固定的流程去审视这些变更，策略会慢慢被“临时放宽”侵蚀，最后变成一条满是'unsafe-inline'、https:、*的摆设。

我在项目里推这套东西时，会坚持做两件事：一是把 CSP 策略纳入代码评审，任何放宽白名单的改动都要说明理由；二是把违规上报的看板挂在团队的日常监控里，让新增的违规来源能被及时发现。这两条看起来是流程问题，实际上决定了策略半年后还能不能守住。

最后分享一个排查小技巧：如果你不确定某条指令到底该写什么，可以在浏览器开发者工具的“网络”面板里看文档响应的头，再配合控制台的违规提示逐条调整；Chrome 的“问题”面板里也会把 CSP 违规单独归类，比翻控制台日志高效得多。另外，很多框架和 SSR 方案都有现成的 nonce 注入能力，别自己从头造，先去翻一遍官方文档，通常能省掉一半的工作量。