正确配置 CSP 不会破坏 PWA 可安装性

内容安全策略（CSP）是一个安全层，通过定义哪些内容源是安全的来加载，从而防止跨站脚本（XSS）和注入攻击。某些 PWA 开发者担心 CSP 标头可能会阻止 service worker 注册或安装提示，但如果正确配置，CSP 不会破坏 PWA 可安装性。

关键在于理解 CSP 控制什么以及它不控制什么。CSP 管理着从何处可以加载资源，但它不会直接阻止浏览器功能，如 PWA 安装提示或 service worker 生命周期操作——这些由权限和应用清单验证控制。

CSP 实际上限制 PWA 的哪些内容

CSP 影响这些与 PWA 相关的操作：

• 脚本加载——允许哪些来源在你的应用中运行 JavaScript
• Service worker 导入——service worker 代码中的 importScripts() 调用
• Worker-src 指令——允许哪些来源生成工作进程
• Frame 和 connect 源——你的应用可以从何处获取数据或嵌入 iframe
• 内联脚本和事件处理器——是否允许 onclick 或类似 eval() 的代码

CSP 不影响：

• PWA 安装提示资格（基于清单验证和 HTTPS）
• Service worker 注册本身（你可以在相应的来源注册 SW 文件）
• Service worker 生命周期事件（install、activate、fetch）
• 后台同步或推送通知权限
• 从你的源加载清单文件

如果你的 PWA 无法显示安装提示，CSP 几乎绝不是罪魁祸首——首先检查你的清单、service worker 注册时机和 HTTPS 设置。

CSP 和 service worker 如何协同工作

Service worker 与 CSP 有特殊关系：

1. Service worker 运行在工作进程上下文中，具有自己的 CSP 评估
2. Service worker 文件本身必须从你的源加载（或同源）
3. 通过 importScripts() 导入的脚本必须满足 CSP 的 worker-src 或 script-src 指令
4. 受控页面的 CSP适用于页面资源，但不一定适用于 service worker 的执行

一个常见的误解是 CSP 阻止 service worker 注册。实际上，CSP 阻止的是service worker 可以加载什么，而不是它是否可以注册。

PWA 可安装性的最小 CSP

以下是适用于 PWA 且不会破坏可安装性的基线 CSP：

Content-Security-Policy:
  default-src 'self';
  script-src 'self' 'unsafe-inline';
  worker-src 'self';
  connect-src 'self' https://your-api.com;
  frame-src 'self';
  img-src 'self' data: https:;

这样做的原因：

• 'self' 允许你的应用的源
• worker-src 'self' 允许来自你的源的 service workers
• script-src 'self' 'unsafe-inline' 允许内联脚本（许多框架需要此功能）
• connect-src 允许你在预期的地方进行 API 调用
• 没有过度限制的 script-src 或 worker-src 会阻止你的 SW 文件

你可以随着时间收紧此策略，但首先从足够宽松的策略开始，不要阻止已知资源。

破坏 PWA 的常见 CSP 错误

这些 CSP 模式会导致 PWA 或 service worker 故障：

1. 阻止你自己的源：

Content-Security-Policy: script-src https://cdn.example.com 'unsafe-inline';

失败原因：你的应用源不在 script-src 中，因此主应用脚本加载失败。

修复：添加 'self' 或你的特定源。

1. 混淆 script-src 与 worker-src：

Content-Security-Policy: script-src 'self'; worker-src 'none';

失败原因：worker-src: 'none' 阻止 service worker 导入和执行。

修复：使用 worker-src 'self' 或省略 worker-src（默认为 script-src）。

1. 阻止 service workers 中的 importScripts()：

Content-Security-Policy: worker-src 'self' https://trusted-libs.com;

但 service worker 执行：

importScripts('https://untrusted-lib.com/sw-lib.js');

失败原因：导入源不在 worker-src 中。

修复：向 worker-src 添加 https://untrusted-lib.com 或将脚本移动到你的源。

1. 混合本地开发与生产 CSP：

在 http://localhost:3000 上运行开发服务器
CSP 标头：default-src 'self'; // 阻止混合 localhost/https

开发期间失败原因：localhost:3000 请求被针对 https://yourapp.com 的 CSP 阻止。

修复：在开发中，要么禁用 CSP，要么在你的开发构建中使用允许的 http://localhost:*。

CSP 和 service worker 调试检查清单

使用此检查清单排查与 CSP 相关的 PWA 问题：

• [ ] 在 DevTools → Application → Headers 或 Response headers 中检查当前 CSP
• [ ] 在 Console → Violations 选项卡中查找 CSP 违规
• [ ] 验证 service worker 文件在 Service Worker 选项卡中成功加载
• [ ] 检查 importScripts() 调用是否因 CSP 错误失败
• [ ] 禁用 CSP 进行测试以确认 CSP 是问题所在
• [ ] 检查应用中的内联脚本是否需要 unsafe-inline
• [ ] 验证 default-src 不会阻塞 'self'（必须允许你自己的源）
• [ ] 确认 worker-src 允许你的 SW 源（通常是 'self'）
• [ ] 检查外部字体/图标 CDN是否需要 font-src 或 img-src 豁免
• [ ] 在已安装 PWA 模式下测试——CSP 在独立窗口中的行为可能不同

框架特定的 CSP 模式

不同的 PWA 框架有 CSP 要求：

React (Create React App):

Content-Security-Policy:
  default-src 'self';
  script-src 'self' 'unsafe-inline' 'unsafe-eval';
  style-src 'self' 'unsafe-inline';
  connect-src 'self';

React 通常需要 unsafe-inline 用于开发时热重载和内联样式。

Vue.js (Vite/CRA):

Content-Security-Policy:
  default-src 'self';
  script-src 'self' 'unsafe-inline';
  style-src 'self' 'unsafe-inline';
  worker-src 'self';

Vue 模板编译为内联脚本，因此在开发期间通常需要 unsafe-inline。

Next.js App Router:

Content-Security-Policy:
  default-src 'self';
  script-src 'self' 'unsafe-eval' 'wasm-unsafe-eval';
  style-src 'self' 'unsafe-inline';
  worker-src 'self';

Next.js 使用 WebAssembly 和动态导入，它们需要特定的 CSP 指令。

静态站点生成器 (Hugo、Jekyll):

Content-Security-Policy:
  default-src 'self';
  script-src 'self';
  style-src 'self';
  worker-src 'self';

静态站点可以使用最严格的 CSP，因为没有运行时框架。

CSP 迁移策略

如果你向现有 PWA 添加 CSP：

1. 从 Content-Security-Policy-Report-Only 开始，在不阻止任何内容的情况下查看违规
2. 监控违规 1-2 周以了解应用的资源使用情况
3. 根据违规报告将所需源添加到 CSP 指令
4. 通过删除过于宽松的指令（如 unsafe-inline）逐步收紧 CSP
5. 每次更改后测试以确保 PWA 仍正常工作且正确安装
6. 一旦违规稳定下来，从 Report-Only 切换到强制执行

切勿直接从无 CSP 切换到锁定策略——你会破坏自己的应用。

CSP 和混合内容

PWA 可安装性的 HTTPS 要求有时会与遗留 CSP 模式冲突：

问题：CSP 标头阻止 http:// 资源，但你的应用从非 HTTPS URL 加载字体或图像。

结果：浏览器阻止资源，可能会破坏应用渲染或安装提示。

修复：

• 将所有资源迁移到 HTTPS
• 如果必须加载 HTTP 资源，请使用协议相关 URL（//example.com/resource）
• 临时向 CSP 添加特定的 HTTP 源，但规划 HTTPS 迁移
• 检查 DevTools 控制台中的混合内容警告

注意：PWA 安装提示需要 HTTPS 源，因此 HTTPS PWA 中的 HTTP 资源本身就可疑。

CSP 报告和监控

对于生产 PWA，启用 CSP 违规报告：

Content-Security-Policy-Report-Only:
  default-src 'self';
  script-src 'self' 'unsafe-inline';
  worker-src 'self';
  report-uri /csp-violations;
  report-to csp-endpoint;

设置一个 Report-To 端点来收集违规：

// 在你的 service worker 或应用中
self.addEventListener('report', (event) => {
  if (event.type === 'cspViolation') {
    // 记录或发送到你的分析
    console.log('CSP Violation:', event.violation);
  }
});

这有助于你在 CSP 破坏 PWA 功能之前捕获 CSP 回归。

旧版浏览器降级

旧版浏览器对 CSP 的支持不完整：

• 旧版 Edge (EdgeHTML)： 有限的 CSP 1 支持
• IE 11： 不支持 CSP
• 旧版 Safari： 缺少某些 CSP 3 指令

如果你的 PWA 面向旧版浏览器：

1. 在假设某些指令有效之前进行 CSP 功能检测
2. 使用 meta CSP 标记以实现最大兼容性（可能会忽略不完整的指令语法）
3. 避免最新的 CSP 功能（如 script-src-elem、script-src-attr），除非你检查浏览器支持
4. 如果 CSP 破坏应用功能，请提供优雅降级

对于现代 PWA，你可以安全地假设 CSP 2+ 支持，但请在目标浏览器上测试。

PWA 实用角度

从可安装性和安全性角度来看：

• 正确配置后，CSP 在不破坏安装提示的情况下增加安全性
• 安全性和可安装性不是权衡——两者都需要用户信任
• 用户会在浏览器控制台中注意到安全警告，即使他们不阅读
• IT 安全审核通常需要 CSP 才能获得企业 PWA 批准
• PWA 的应用商店审核员（如果适用）可能会检查安全标头

具有良好配置的 CSP 的 PWA 更有可能通过安全审查，在企业管理的设备上可靠运行，并且避免浏览器安全更新导致的意外中断。

下一步建议

如果你正在构建新的 PWA：

1. 在初始开发期间添加 CSP，而不是事后才考虑
2. 最初使用 Report-Only 模式，同时弄清楚所需的源
3. 记录任何所需的 CSP 豁免用于外部服务
4. 在已安装 PWA 模式下测试——CSP 的行为可能与浏览器标签页不同

如果你向现有 PWA 添加 CSP：

1. 从 Report-Only CSP 开始，在不阻止的情况下收集违规
2. 迁移资源或更新 CSP 以修复合法违规
3. 从 unsafe-inline 逐步迁移到更严格的 script-src 策略
4. 部署后监控生产 CSP 违规以查找回归

CSP 不会破坏 PWA——当你理解它控制什么以及如何为应用需求配置它时，它会使 PWA 更安全。