Spring Boot框架对静态资源有默认的加载和映射规则，当项目中的CSS、JavaScript、图片等静态资源无法正常访问时，需要先了解默认规则再逐步排查问题。
Spring Boot静态资源默认规则
Spring Boot默认会从以下四个类路径下的目录加载静态资源，优先级从高到低依次为：
- classpath:/META-INF/resources/
- classpath:/resources/
- classpath:/static/
- classpath:/public/
默认情况下，静态资源的访问路径不需要添加上述目录前缀，比如将test.jpg放在classpath:/static/目录下，直接通过http://localhost:8080/test.jpg即可访问。
常见无法访问的原因及解决方案
1. 静态资源存放路径错误
如果静态资源没有放在上述四个默认目录下，框架无法自动加载。解决方案是将资源移动到默认目录，或者自定义资源映射规则。
2. 自定义WebMvc配置覆盖了默认规则
当开发者自定义了WebMvcConfigurer配置且没有调用super方法，或者使用了@EnableWebMvc注解，会导致默认静态资源映射失效。正确配置示例如下：
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
@Configuration
public class WebConfig implements WebMvcConfigurer {
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
// 保留默认静态资源映射，再添加自定义映射
registry.addResourceHandler("/**")
.addResourceLocations("classpath:/META-INF/resources/", "classpath:/resources/", "classpath:/static/", "classpath:/public/");
// 自定义静态资源映射，将/upload/**路径映射到磁盘的D:/upload/目录
registry.addResourceHandler("/upload/**")
.addResourceLocations("file:D:/upload/");
}
}
3. 访问路径书写错误
访问静态资源时如果添加了存放目录的前缀，会导致404。比如资源放在static目录下，访问时写成http://localhost:8080/static/test.jpg就无法访问，正确路径是http://localhost:8080/test.jpg。
4. 拦截器拦截了静态资源请求
如果自定义了拦截器且没有排除静态资源路径，会导致静态资源请求被拦截。需要在拦截器配置中排除静态资源路径：
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
import com.example.demo.interceptor.MyInterceptor;
@Configuration
public class InterceptorConfig implements WebMvcConfigurer {
@Override
public void addInterceptors(InterceptorRegistry registry) {
registry.addInterceptor(new MyInterceptor())
.addPathPatterns("/**")
// 排除静态资源路径和常见静态资源后缀
.excludePathPatterns("/static/**", "/css/**", "/js/**", "/img/**", "/**/*.css", "/**/*.js", "/**/*.png", "/**/*.jpg");
}
}
5. 项目上下文路径配置影响
如果在配置文件中设置了server.servlet.context-path，访问静态资源需要加上上下文路径。比如配置server.servlet.context-path=/demo，那么访问static目录下的test.jpg需要请求http://localhost:8080/demo/test.jpg。
自定义静态资源映射的正确方式
如果需要将静态资源存放在非默认目录，或者映射到外部磁盘路径，可以通过实现WebMvcConfigurer接口的addResourceHandlers方法完成配置，示例代码如下：
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
@Configuration
public class CustomResourceConfig implements WebMvcConfigurer {
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
// 映射自定义类路径目录，将/custom/**路径映射到classpath:/custom/目录
registry.addResourceHandler("/custom/**")
.addResourceLocations("classpath:/custom/");
// 映射外部磁盘目录，将/files/**路径映射到D:/files/目录
registry.addResourceHandler("/files/**")
.addResourceLocations("file:D:/files/");
}
}
配置完成后，放在classpath:/custom/目录下的demo.txt可以通过http://localhost:8080/custom/demo.txt访问，放在D:/files/目录下的data.txt可以通过http://localhost:8080/files/data.txt访问。
快速排查步骤
当遇到静态资源无法访问的问题时，可以按照以下步骤快速排查：
- 检查静态资源是否放在默认的四个类路径目录下，或者是否在自定义映射规则中配置了对应路径。
- 检查访问路径是否正确，是否多了目录前缀，是否遗漏了上下文路径。
- 检查是否自定义了WebMvc配置，是否保留了默认静态资源映射规则。
- 检查是否配置了拦截器，是否排除了静态资源相关的请求路径。
- 查看项目启动日志，确认静态资源加载路径是否正确，是否有路径不存在的报错信息。
Spring_Boot静态资源资源映射WebMvcConfigurerResourceHandlerRegistry修改时间：2026-06-11 23:03:43