springboot静态资源(static)无法访问问题404及解决过程

SpringBoot 静态资源(static)无法访问问题404

在SpringBoot项目开发中，静态资源（比如图片、CSS、JS文件）突然返回404，是个挺让人头疼的问题。尤其是当你已经确认文件路径没错，但浏览器就是死活加载不出来的时候。别急，这通常不是文件丢了，而是配置或拦截环节出了岔子。下面，咱们就按排查的优先级，把几个最常见的“坑”给捋一遍。

第一站：检查拦截器配置

如果你的项目里用到了自定义的拦截器（Interceptor），那它很可能是第一个“嫌疑人”。拦截器默认会拦截所有请求，如果不做特殊处理，静态资源的请求路径也会被它拦下来。

怎么排查？打开你的拦截器实现类，重点看preHandle方法。一个常见的、也是推荐的做法是，在方法开头判断一下当前请求的处理器（handler）类型。如果不是映射到具体控制器方法的（即不是HandlerMethod），就放行。这通常就是放行静态资源请求的关键逻辑。

@Override
public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
 	// 关键在这里：如果不是映射到方法直接通过,防止静态资源被拦截
 	if (!(handler instanceof HandlerMethod)) {
       return true;
 	}
  	// ... 你的其他拦截逻辑
}

看看你的代码里，有没有这行“守卫”。如果没有，加上它，问题可能就解决了。

第二站：审视WebMvc配置

如果拦截器没问题，下一个要检查的就是Spring MVC的配置类。这里指的是你继承了WebMvcConfigurerAdapter（Spring Boot 2.x之前）或实现了WebMvcConfigurer接口（Spring Boot 2.x）的类。

特别注意：如果你在配置类上使用了@EnableWebMvc注解，事情就变得不一样了。这个注解会全面接管Spring Boot的默认MVC配置，其中就包括静态资源的映射规则。一旦用了它，你就必须手动指定静态资源的位置，否则原本放在classpath:/static/等目录下的资源就“失效”了。

补救方法是，在配置类中重写addResourceHandlers方法，把标准的资源路径给加回去：

@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
    // 手动添加静态资源映射规则
    registry.addResourceHandler("/**")
            .addResourceLocations("classpath:/META-INF/resources/")
            .addResourceLocations("classpath:/resources/")
            .addResourceLocations("classpath:/static/")
            .addResourceLocations("classpath:/public/");
    // 如果继承了WebMvcConfigurerAdapter，记得调用父类方法
    super.addResourceHandlers(registry);
}

第三站：检查Ma ven构建配置

如果前面两步都确认无误，静态资源还是404，那不妨把目光投向项目的构建过程。特别是pom.xml文件中的配置。

有时候，为了资源过滤或其他构建需求，我们会在标签里自定义资源目录。如果配置不当，可能会导致src/main/resources下的static文件夹在打包时没有被正确复制到输出目录（比如target/classes）。

检查你的pom.xml，确保配置覆盖了静态资源目录：

    
       src/main/webapp
     
     
       src/main/resources
       true
     

这个配置确保了src/main/resources（及其子目录static）下的文件会被处理并包含进最终的包中。

最后一道关卡：权限框架

如果你的项目集成了Shiro、Spring Security这类权限安全框架，那么问题很可能出在它们的过滤规则上。这些框架拥有更高的请求拦截优先级，会先于Spring MVC自身的拦截器执行。

你需要检查Shiro的ShiroFilterFactoryBean中配置的过滤链（filterChainDefinitionMap），或者Spring Security的配置类（继承WebSecurityConfigurerAdapter）中通过HttpSecurity配置的授权规则。确保其中对静态资源的请求路径（如/static/**, /css/**, /js/**等）设置了匿名访问或直接放行。

总结

遇到SpringBoot静态资源404，别慌，按照这个顺序一步步来：

1. 查拦截器：看是否放行了非HandlerMethod的请求。
2. 查MVC配置：看是否误用@EnableWebMvc或漏配了资源处理器。
3. 查构建配置：看pom.xml中资源目录配置是否完整。
4. 查权限框架：看Shiro或Spring Security的过滤规则是否拦截了静态资源。

绝大多数情况下，问题都出在这四步中的某一步。理清思路，逐个排查，你的静态资源很快就能重见天日。