Spring MVC修改控制器映射后静态资源无法加载的问题排查

云上老周

2026-5-8

解决Spring MVC控制器路径变更后静态资源加载失败的问题

问题根源分析

你遇到的核心问题是静态资源引用的相对路径导致URL前缀错误：当控制器映射从/dashboard改成/org/dashboard后，JSP里的<c:url value="css/style.css"/>是相对当前请求路径的引用，生成的URL会自动带上/org前缀，变成/testproject/org/css/style.css，但你的静态资源实际存放在classpath:/static/css/下，自然匹配不到。

分步解决方案

1. 修正JSP的静态资源引用（最直接有效）

把JSP里的相对路径改成绝对路径（开头加斜杠/）：

<c:url value="/css/style.css"/>

这样生成的URL会基于server.servlet.contextPath，也就是/testproject/css/style.css，完全不受当前控制器的路径影响，和之前正常加载时的URL一致。

2. 正确配置WebMvcConfig静态资源映射

如果需要自定义静态资源的访问规则，编写一个WebMvcConfig配置类，避免和默认配置冲突：

@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        // 访问路径/css/** 映射到classpath下的static/css目录
        registry.addResourceHandler("/css/**")
                .addResourceLocations("classpath:/static/css/");
        // 同理配置其他静态资源目录
        registry.addResourceHandler("/js/**")
                .addResourceLocations("classpath:/static/js/");
        registry.addResourceHandler("/img/**")
                .addResourceLocations("classpath:/static/img/");
    }
}

这里解释下classpath的使用场景：

classpath:指向项目编译后的资源根目录，src/main/resources下的所有文件编译后都会被放到classpath根目录，所以classpath:/static/就对应你本地的src/main/resources/static/目录。
当你需要引用打包在JAR里的资源时，classpath路径是唯一可行的方式，因为文件不在磁盘路径上，而是在JAR包内部。

3. 理解不同静态资源配置的区别

Spring Boot默认静态资源映射：自动将classpath:/static/、classpath:/public/、classpath:/resources/、classpath:/META-INF/resources/这些目录映射到/**，也就是说直接通过contextPath+资源路径就能访问，比如/testproject/css/style.css对应classpath:/static/css/style.css。
自定义addResourceHandlers：适合更精细的资源管理，比如把/assets/**映射到classpath:/static/assets/，实现不同资源的独立访问路径。
spring.mvc.static-path-pattern：全局设置静态资源的访问前缀，比如设置spring.mvc.static-path-pattern=/resources/**，那所有静态资源必须通过/resources/xxx访问（比如/testproject/resources/css/style.css）。注意这个配置会覆盖默认的/**映射，所以要确保你的资源处理器路径或默认映射能匹配这个前缀。

关于简易项目配置后404的排查

你提到在简易项目里加资源处理器后出现404，大概率是配置冲突：

如果你设置了spring.mvc.static-path-pattern=/resources/**，但资源处理器里的addResourceHandler是/css/**，那访问/testproject/resources/css/test.css就会找不到，因为处理器没匹配这个路径。
解决方法：要么把addResourceHandler改成/resources/css/**，要么去掉spring.mvc.static-path-pattern配置，用默认的映射规则。

内容的提问来源于stack exchange，提问作者ankur singh