实战业务场景 amp; 报错现象2.1 业务场景后端生成 Excel 文件存放在服务器临时目录通过资源映射配置访问路径/excel/\*\*前端、APP 通过 URL 直接下载文件。2.2 报错信息{msg:认证失败无法访问系统资源,code:401}2.3 报错特征接口本身无代码报错后台无异常浏览器直接访问文件地址返回 401 未授权登录后携带 Token 可以正常访问未登录直接拦截三、底层原理为什么会被拦截3.1 SpringSecurity 默认拦截规则SpringSecurity 内置拦截链默认规则所有请求全部需要认证没有明确放行的路径一律拦截。执行优先级客户端发起请求文件/接口进入 SpringSecurity 拦截过滤器链匹配放行规则permitAll\(\)匹配成功直接放行无需认证匹配失败校验 Token、登录状态无权限直接抛出401 认证失败3.2 本次 Excel 文件拦截原因文件访问地址http://ip:port/excel/xxx\.xlsxSecurity 不会识别这是静态文件只会识别请求路径/excel/该路径未配置放行因此判定为需要登录认证最终返回 401。四、核心解决方案配置资源放行4.1 放行核心语法4.1.1 旧版 SecurityRuoyi 通用版本.antMatchers(/excel/**).permitAll()4.1.2 新版 Security 6.0.requestMatchers(/excel/**).permitAll()4.2 完整配置代码Ruoyi 项目通用Overrideprotected 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/去哪里找本地物理文件解决404Security放行配置告诉安全框架这个路径不用登录解决4015.2 配套静态资源映射代码Configurationpublic class WebConfig implements WebMvcConfigurer {Overridepublic void addResourceHandlers(ResourceHandlerRegistry registry) {// 将 /excel/** 映射到服务器相对路径upload/excel/registry.addResourceHandler(/excel/**).addResourceLocations(file:./upload/excel/);}}5.3 完整链路401404双问题解决请求/excel/test\.xlsxSecurity 拦截 → 匹配放行规则 → 直接放行无401Spring 资源处理器 → 匹配映射规则 → 读取本地文件无404返回文件流浏览器/APP 直接下载六、高频踩坑总结避坑重点6.1 坑1放行路径和映射路径不一致映射路径/file/\*\*放行路径写/excel/\*\*路径不统一依旧拦截。解决方案映射、放行、访问URL三者前缀必须完全一致。6.2 坑2新版Security使用旧语法Security6.0以上禁止使用antMatchers必须改用requestMatchers否则项目启动报错。6.3 坑3放行位置书写错误必须写在\.anyRequest\(\)\.authenticated\(\)前面写在后面放行失
SpringSecurity 静态资源放行深度详解（解决401认证失败、文件无法访问、URL拦截问题）
实战业务场景 amp; 报错现象2.1 业务场景后端生成 Excel 文件存放在服务器临时目录通过资源映射配置访问路径/excel/\*\*前端、APP 通过 URL 直接下载文件。2.2 报错信息{msg:认证失败无法访问系统资源,code:401}2.3 报错特征接口本身无代码报错后台无异常浏览器直接访问文件地址返回 401 未授权登录后携带 Token 可以正常访问未登录直接拦截三、底层原理为什么会被拦截3.1 SpringSecurity 默认拦截规则SpringSecurity 内置拦截链默认规则所有请求全部需要认证没有明确放行的路径一律拦截。执行优先级客户端发起请求文件/接口进入 SpringSecurity 拦截过滤器链匹配放行规则permitAll\(\)匹配成功直接放行无需认证匹配失败校验 Token、登录状态无权限直接抛出401 认证失败3.2 本次 Excel 文件拦截原因文件访问地址http://ip:port/excel/xxx\.xlsxSecurity 不会识别这是静态文件只会识别请求路径/excel/该路径未配置放行因此判定为需要登录认证最终返回 401。四、核心解决方案配置资源放行4.1 放行核心语法4.1.1 旧版 SecurityRuoyi 通用版本.antMatchers(/excel/**).permitAll()4.1.2 新版 Security 6.0.requestMatchers(/excel/**).permitAll()4.2 完整配置代码Ruoyi 项目通用Overrideprotected 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/去哪里找本地物理文件解决404Security放行配置告诉安全框架这个路径不用登录解决4015.2 配套静态资源映射代码Configurationpublic class WebConfig implements WebMvcConfigurer {Overridepublic void addResourceHandlers(ResourceHandlerRegistry registry) {// 将 /excel/** 映射到服务器相对路径upload/excel/registry.addResourceHandler(/excel/**).addResourceLocations(file:./upload/excel/);}}5.3 完整链路401404双问题解决请求/excel/test\.xlsxSecurity 拦截 → 匹配放行规则 → 直接放行无401Spring 资源处理器 → 匹配映射规则 → 读取本地文件无404返回文件流浏览器/APP 直接下载六、高频踩坑总结避坑重点6.1 坑1放行路径和映射路径不一致映射路径/file/\*\*放行路径写/excel/\*\*路径不统一依旧拦截。解决方案映射、放行、访问URL三者前缀必须完全一致。6.2 坑2新版Security使用旧语法Security6.0以上禁止使用antMatchers必须改用requestMatchers否则项目启动报错。6.3 坑3放行位置书写错误必须写在\.anyRequest\(\)\.authenticated\(\)前面写在后面放行失
