Spring Boot 3.x CSP 配置导致前端资源加载失败问题及解决

在 Spring Boot 3.x 中，可以通过 Spring Security 的 HeadersConfigurer 轻松添加 CSP 头部：

@Configuration
@EnableWebSecurity
public class SecurityConfig {
    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http.headers(headers -> headers
            .contentSecurityPolicy(csp -> csp
                .policyDirectives("default-src 'self'; script-src 'self'; style-src 'self';")));
        return http.build();
    }
}

也可通过 application.properties 配置：

spring.security.headers.content-security-policy=default-src 'self'; script-src 'self'; style-src 'self';

2.3 常见的配置失误

• 未包含第三方域名：使用了 CDN 上的库（如 jQuery、Bootstrap），但未在 script-src 或 style-src 中添加其域名。
• 禁止内联脚本/样式：默认策略通常禁止内联代码，但项目中可能包含 <script> 标签内的代码或 style 属性。需要添加 'unsafe-inline'（不推荐）或使用 nonce/hash。
• 禁止 eval()：某些 JavaScript 库（如 Vue 的模板编译器）依赖于 eval() 或 Function 构造函数，而 CSP 默认禁止 'unsafe-eval'。
• 资源类型混淆：字体文件可能被 default-src 限制，但未在 font-src 中显式允许。
• 多策略叠加冲突：应用服务器（如 Tomcat）、反向代理（如 Nginx）和 Spring Security 同时设置 CSP 头部，导致策略叠加后更严格。

3. 解决方案：从诊断到修复的完整步骤

3.1 步骤一：查看浏览器控制台错误

打开浏览器开发者工具（F12），查看 Console 面板中的 CSP 违规提示。错误信息会明确指出被阻止的资源类型、策略指令以及违规的资源 URL。例如：

Refused to load the script 'https://code.jquery.com/jquery-3.6.0.js' because it violates the following Content Security Policy directive: "script-src 'self'".

这表示 script-src 缺少 https://code.jquery.com。

3.2 步骤二：整理资源来源清单

根据错误信息，列出所有被阻止的外部域名、内联脚本片段、eval 使用情况等。包括：

• 第三方脚本：如 CDN、分析工具、广告 SDK。
• 第三方样式：如字体库、UI 框架。
• 内联脚本/样式：页面中直接写的 <script> 块或 style 属性。
• 动态代码：如 eval、new Function。
• WebSocket/API 地址：如果前端通过 Ajax 访问后端 API，需确保 API 域名在 connect-src 中。

3.3 步骤三：调整 CSP 策略

3.3.1 允许外部域名

为每个外部来源添加对应的指令。例如：

script-src 'self' https://code.jquery.com https://stackpath.bootstrapcdn.com; style-src 'self' https://fonts.googleapis.com https://use.fontawesome.com; font-src 'self' https://fonts.gstatic.com; img-src 'self' data: https://*.cloudfront.net;

3.3.2 处理内联脚本和样式

最佳实践是使用 nonce（随机数） 或 hash（哈希值） 来允许特定的内联代码，而不是全局开放 'unsafe-inline'。

hash 方式：计算内联脚本的哈希值（SHA-256/384/512），并在 CSP 中声明。例如：

script-src 'sha256-abc123...';

哈希值需与内联代码完全匹配，一旦代码变动，需同步更新 CSP。

nonce 方式：服务器为每个请求生成唯一的随机数，并在 CSP 头部中通过 script-src 'nonce-{随机值}' 声明。同时，内联 <script> 标签需添加 nonce="{随机值}" 属性。Spring Security 支持自动注入 nonce 到请求中。配置示例：

http.headers(headers -> headers
    .contentSecurityPolicy(csp -> csp
        .policyDirectives("script-src 'self' 'nonce-{random}';")));

但这种方式需要模板引擎（如 Thymeleaf）配合，自动将 nonce 应用到脚本标签。Thymeleaf 在 Spring Security 6.x 中会自动处理 @cspNonce。

如果非必须，建议避免使用内联脚本，将所有 JavaScript 移到外部文件中。

3.3.3 处理 eval()

如果应用依赖 eval()（如 Vue CLI 的 development 模式、某些模板引擎），需要在 script-src 中添加 'unsafe-eval'。但在生产环境中，应尽可能消除 eval 使用，或选择无需 eval 的框架版本。

3.3.4 处理 API 连接

对于前端发起的 XHR 请求，需确保后端 API 域名在 connect-src 中。如果前后端同域，'self' 已足够；若跨域，则需明确域名：

connect-src 'self' https://api.example.com;

3.4 步骤四：使用报告模式（Report-Only）测试

在正式生效前，可先启用 CSP 报告模式，仅收集违规报告而不实际拦截资源。这有助于在不影响用户的情况下验证策略的正确性。

配置方式：

http.headers(headers -> headers
    .contentSecurityPolicy(csp -> csp
        .policyDirectives("default-src 'self'; script-src 'self'; report-uri /csp-report;")
        .reportOnly())); // 启用报告模式

同时需要提供一个端点接收 JSON 格式的报告（POST 请求）。Spring Boot 中可简单实现一个 Controller 接收并记录日志。

3.5 步骤五：检查多策略冲突

确保没有多个 CSP 头部同时发送。可使用浏览器的网络面板查看响应头，若出现多个 Content-Security-Policy 头部，浏览器通常采用最严格的并集。排查 Nginx、Apache 或应用服务器的配置，确保只有一处设置。

3.6 步骤六：使用预设的安全标头库

对于复杂的 CSP，可考虑使用专门的库如 spring-security-csp 或手动构建动态策略。

4. 完整示例：Spring Boot 3.x 中配置 CSP 并处理内联脚本

4.1 依赖

确保包含 spring-boot-starter-security 和 spring-boot-starter-thymeleaf（若使用 Thymeleaf）。

4.2 安全配置

@Configuration
@EnableWebSecurity
public class SecurityConfig {
    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http.authorizeHttpRequests(auth -> auth.anyRequest().permitAll()) // 示例中开放所有请求
            .headers(headers -> headers
                .contentSecurityPolicy(csp -> csp
                    .policyDirectives("default-src 'self'; " +
                        "script-src 'self' 'nonce-{random}' https://code.jquery.com; " +
                        "style-src 'self' 'nonce-{random}' https://fonts.googleapis.com; " +
                        "font-src 'self' https://fonts.gstatic.com; " +
                        "img-src 'self' data:; " +
                        "connect-src 'self'; " +
                        "frame-ancestors 'none';")));
        return http.build();
    }
}

注意：'nonce-{random}' 是 Spring Security 的特殊标记，实际会被替换为每个请求生成的随机值，并绑定到当前请求的 HttpServletRequest 属性中。

4.3 Thymeleaf 模板中使用 nonce

在 Thymeleaf 页面中，使用 @cspNonce 表达式为内联脚本和样式添加 nonce 属性：

<script th:attr="nonce=${@cspNonce}" type="text/javascript">
// 内联脚本内容
console.log('This inline script is allowed by CSP nonce');
</script>
<style th:attr="nonce=${@cspNonce}">
/* 内联样式内容 */
body { background-color: #f0f0f0; }
</style>

对于外部脚本，不需要添加 nonce，只需域名允许即可。

4.4 处理报告端点（可选）

@RestController
public class CspReportController {
    @PostMapping("/csp-report")
    public void receiveReport(@RequestBody String report) {
        // 记录报告，如写入日志
        log.warn("CSP violation: {}", report);
    }
}

然后在 CSP 指令中添加 report-uri /csp-report;（注意报告模式需启用 reportOnly()）。

5. 最佳实践总结

• 最小权限原则：只允许必要的来源，避免使用 * 或 'unsafe-inline'。
• 优先使用 nonce：对于不可避免的内联代码，使用 nonce 机制代替 'unsafe-inline'。
• 生产环境禁用 eval：检查并重构依赖 eval 的代码，或仅在开发环境允许 'unsafe-eval'。
• 定期审查：随着项目发展，定期检查 CSP 报告，及时添加新的可信来源或移除不再使用的来源。
• 结合 CSP 报告：配置报告 URI，监控违规行为，快速响应策略问题。
• 测试充分：在预发环境模拟真实用户场景，确保所有资源都能正常加载。

6. 结语

CSP 是 Web 应用安全的重要防线，但其严格性也可能成为前端功能的障碍。通过系统性的诊断、合理的策略调整以及 Spring Boot 3.x 提供的灵活配置能力，开发者可以在不影响用户体验的前提下，构建出既安全又兼容的 CSP 策略。当遇到资源加载失败时，请遵循本文的步骤：从浏览器控制台入手，梳理资源清单，调整指令，使用 nonce 或报告模式验证，最终实现安全与功能的平衡。