SpringSecurity 静态资源放行深度详解（解决401认证失败、文件无法访问、URL拦截问题）

SpringSecurity 静态资源放行深度详解（解决401认证失败、文件无法访问、URL拦截问题）

一、前言

在 SpringBoot 项目中，只要引入 SpringSecurity 安全框架，所有接口、资源默认都会被拦截，必须携带 Token、登录认证后才能访问。

实际开发中，经常存在无需登录即可访问的资源：

• 临时生成的 Excel、PDF、图片等下载文件

• 登录接口、验证码接口

• 静态资源：html、js、css、图片

• 第三方回调、心跳检测接口

本文以 Excel 文件下载被拦截 401为实战案例，抽象通用放行逻辑，搞懂底层原理，以后遇到任何资源拦截问题，均可直接套用方案解决。

二、实战业务场景 & 报错现象

2.1 业务场景

后端生成 Excel 文件存放在服务器临时目录，通过资源映射配置访问路径：/excel/\*\*，前端、APP 通过 URL 直接下载文件。

2.2 报错信息

{"msg":"认证失败，无法访问系统资源","code":401}

2.3 报错特征

• 接口本身无代码报错，后台无异常

• 浏览器直接访问文件地址，返回 401 未授权

• 登录后携带 Token 可以正常访问，未登录直接拦截

三、底层原理：为什么会被拦截？

3.1 SpringSecurity 默认拦截规则

SpringSecurity 内置拦截链，默认规则：

所有请求，全部需要认证；没有明确放行的路径，一律拦截。

执行优先级：

1. 客户端发起请求（文件/接口）

2. 进入 SpringSecurity 拦截过滤器链

3. 匹配放行规则（permitAll\(\)）

4. 匹配成功：直接放行，无需认证

5. 匹配失败：校验 Token、登录状态，无权限直接抛出 401 认证失败

3.2 本次 Excel 文件拦截原因

文件访问地址：http://ip:port/excel/xxx\.xlsx

Security 不会识别这是静态文件，只会识别请求路径 /excel/，该路径未配置放行，因此判定为需要登录认证，最终返回 401。

四、核心解决方案：配置资源放行

4.1 放行核心语法

4.1.1 旧版 Security（Ruoyi 通用版本）

.antMatchers("/excel/**").permitAll()

4.1.2 新版 Security 6.0+

.requestMatchers("/excel/**").permitAll()

4.2 完整配置代码（Ruoyi 项目通用）

@Override
protected void configure(HttpSecurity http) throws Exception {
    http
        .authorizeRequests()
        // 放行登录、验证码接口
        .antMatchers("/login","/captcha/**").permitAll()
        // 放行Excel下载静态资源（核心代码）
        .antMatchers("/excel/**").permitAll()
        // 其余所有请求必须认证
        .anyRequest().authenticated();
}

4.3 语法详解

语法	作用说明
/excel/\*\*	匹配规则：以 /excel/ 开头的所有子路径，包含所有Excel文件
permitAll\(\)	永久放行，无需登录、无需Token、无需权限

五、关联知识点：静态资源映射 + 放行联动

很多新手只配置放行，依旧无法访问文件，原因是：缺少静态资源映射，二者必须搭配使用。

5.1 两者区别

• 静态资源映射（WebConfig） ：告诉 Spring，访问 /excel/ 去哪里找本地物理文件（解决404）

• Security放行配置：告诉安全框架，这个路径不用登录（解决401）

5.2 配套静态资源映射代码

@Configuration
public class WebConfig implements WebMvcConfigurer {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        // 将 /excel/** 映射到服务器相对路径upload/excel/
        registry.addResourceHandler("/excel/**")
                .addResourceLocations("file:./upload/excel/");
    }
}

5.3 完整链路（401+404双问题解决）

1. 请求：/excel/test\.xlsx

2. Security 拦截 → 匹配放行规则 → 直接放行（无401）

3. Spring 资源处理器 → 匹配映射规则 → 读取本地文件（无404）

4. 返回文件流，浏览器/APP 直接下载

六、高频踩坑总结（避坑重点）

6.1 坑1：放行路径和映射路径不一致

映射路径：/file/\*\*，放行路径写：/excel/\*\*，路径不统一，依旧拦截。

解决方案：映射、放行、访问URL三者前缀必须完全一致。

6.2 坑2：新版Security使用旧语法

Security6.0以上禁止使用 antMatchers，必须改用 requestMatchers，否则项目启动报错。

6.3 坑3：放行位置书写错误

必须写在 \.anyRequest\(\)\.authenticated\(\)前面，写在后面放行失效。

6.4 坑4：带Token访问放行资源

放行资源本身无需认证，若携带过期Token，部分版本会判定认证失败，建议APP下载文件不携带Token。

七、通用模板：以后直接复制套用

7.1 通用静态资源放行模板（旧版Security/Ruoyi）

// 无需认证放行路径
.antMatchers(
        "/login",
        "/captcha/**",
        "/excel/**",    // Excel文件下载
        "/image/**",    // 图片访问
        "/file/**"      // 通用文件
).permitAll()

7.2 通用静态资源映射模板

registry.addResourceHandler("/自定义前缀/**")
        .addResourceLocations("file:./本地相对路径/");

八、总结

遇到 静态文件、公开接口、无需登录资源 被SpringSecurity拦截报401，固定解决步骤：

1. 确定访问路径前缀（如 /excel/）

2. 在Security配置中添加放行规则 xxx\.permitAll\(\)

3. 若为本地文件，补充静态资源映射，绑定物理路径

4. 保证：访问路径=映射路径=放行路径三者一致

该逻辑适配：Excel、PDF、图片、公开接口、回调地址，是企业级 SpringBoot 项目必备基础知识点，一次弄懂，永久复用。