Reporting API 错误仪表板 - CSP/拦截报告收集

核心术语解释

以下是 Reporting API 错误仪表板涉及的核心术语与概念。理解这些术语有助于你更好地配置和使用报告端点。

Reporting API

由 W3C 标准化的浏览器报告机制，允许网站通过配置端点地址接收浏览器自动生成的各类报告。 当前主要有两个版本：v1 使用 report-uri 指令，v2 使用 report-to 指令配合 Reporting-Endpoints 响应头。 Reporting API 是前端安全监控和质量保障的重要基础设施。

CSP（内容安全策略）

Content Security Policy，一种由浏览器执行的安全层，用于检测和缓解某些类型的攻击，包括跨站脚本（XSS）和 数据注入攻击。CSP 通过声明允许加载的资源来源来限制页面可以使用的内容，违规行为会通过 Reporting API 发送报告。

report-uri

CSP v1 版本中的报告指令，指定浏览器在检测到 CSP 违规时应将报告发送到的 URL。该指令已被逐步弃用， 推荐迁移到 v2 版本的 report-to 指令。report-uri 接收的报告格式为 application/csp-report。

report-to

CSP v2 版本中的报告指令，配合 Reporting-Endpoints 响应头使用。相比 report-uri，report-to 提供了更灵活的 端点配置方式，支持为不同类型的报告指定不同的接收端点，并且使用更简洁的 JSON 报告格式（application/reports+json）。

Report-Only 模式

使用 Content-Security-Policy-Report-Only 头声明的 CSP 策略。在此模式下，浏览器检测到违规时会发送报告， 但不会阻止资源加载。这是在正式部署 CSP 前进行测试和数据收集的安全方式。

document-uri

CSP 违规报告中的核心字段，表示发生违规行为的页面 URL。该字段帮助开发者定位具体是哪个页面触发了 CSP 违规， 是排查问题的首要线索。

violated-directive

表示被违反的具体 CSP 指令，例如 script-src 'self' 或 style-src cdn.example.com。该字段指明了哪个安全策略 被触发，开发者据此可以调整对应的 CSP 白名单。

blocked-uri

被 CSP 阻止的资源 URL。当浏览器尝试加载该资源但被 CSP 策略拦截时，会将该 URL 记录在报告中。通过分析 blocked-uri 可以了解哪些第三方资源需要加入白名单或替换为合规来源。

source-file

触发违规行为的源文件路径，通常用于标识是哪个 JavaScript 文件或内联脚本导致了 CSP 违规。对于动态加载的 内容，source-file 可以帮助追溯问题的根源。

浏览器干预报告

当浏览器主动干预某些行为（如阻止弹窗、拦截不安全的表单提交等）时生成的报告。干预报告不属于 CSP 违规， 而是浏览器安全机制的主动防护行为，开发者可以通过分析此类报告了解用户交互中被浏览器拦截的操作。

网络错误报告

浏览器在加载资源过程中发生网络层面错误时生成的报告，例如 DNS 解析失败、连接超时、SSL 证书错误等。 此类报告有助于开发者监控第三方资源的可用性和稳定性。

Reporting-Endpoints

HTTP 响应头，用于声明 Reporting API v2 的端点列表。每个端点可以指定不同的 URL 和用途（如 csp、deprecation、 interventions），浏览器根据报告类型自动选择对应的端点进行投递。