【Springboot】解决 o.s.web.servlet.PageNotFound：No mapping for * 与静态资源 404 的 WebMvcConfigurer 配置

发布时间：2026/9/27 12:02:55来源：尧图网络

1. 一个让人抓狂的 404HTML 能开CSS/JS 全挂如果你正在维护一个从老项目迁移过来的 Spring Boot 工程很可能遇到过这种诡异现象浏览器里访问index.html一切正常页面骨架能出来但样式全丢、图标不显示、控制台一堆 404后端日志里反复刷着o.s.web.servlet.PageNotFound : No mapping for GET /plugins/mdui/css/mdui.min.css。更迷惑的是你翻遍application.yml静态资源路径没动过src/main/resources/static目录下文件明明躺着可就是访问不到。这个问题的核心检索词就是Spring Boot 静态资源 404、PageNotFound No mapping for、WebMvcConfigurationSupport与WebMvcConfigurer的取舍。它适合谁适合正在做老项目升级、接手别人代码、或者自己写了个Configuration类之后突然发现静态资源全挂的开发者。我试过在一个迁移项目里排查了整整一个下午最后发现罪魁祸首是一个继承自WebMvcConfigurationSupport的日期格式化配置类——它把 Spring Boot 的 MVC 自动配置整个顶掉了。这篇文章会带你走完完整链路先讲清楚为什么会 404再给出可复制的WebMvcConfigurer配置骨架然后用curl和日志验证修复效果最后把常见坑一个个列出来。中途我也会说明怎么用 TaoToken 统一 Key 和 API 通道把 AI 辅助排查工具接进来减少来回切换账号的麻烦。2. 根因定位WebMvcConfigurationSupport 为什么会让静态资源失效2.1 两种配置方式的行为差异Spring Boot 对 Spring MVC 做了大量自动配置比如静态资源映射、消息转换器、视图解析器、拦截器等。这些自动配置生效的前提是容器里没有一个WebMvcConfigurationSupport类型的 Bean。一旦你写了一个类继承WebMvcConfigurationSupportSpring Boot 的WebMvcAutoConfiguration就会因为条件注解不满足而整体退避默认的静态资源处理链随之消失。而WebMvcConfigurer是一个接口它只是扩展默认配置不会触发自动配置退避。你实现它等于在原有默认行为上追加自己的规则静态资源映射依然保留。对比项WebMvcConfigurationSupportWebMvcConfigurer作用完全接管 Spring MVC 配置在默认配置上做扩展对自动配置的影响导致 MVC 自动配置整体失效不影响自动配置继续生效静态资源处理必须手动配置所有路径默认路径保留只需追加视图解析器需手动配置自动配置扩展拦截器需手动注册自动配置扩展推荐场景需要彻底自定义 MVC 行为绝大多数业务扩展场景2.2 老项目里最典型的触发代码很多老项目会写一个日期格式化配置类早期教程里常见这种写法Configuration public class DateTimeConfig extends WebMvcConfigurationSupport { private static final Logger logger LoggerFactory.getLogger(DateTimeConfig.class); Bean public FormattingConversionService mvcConversionService() { logger.info(mvcConversionService 执行了); DefaultFormattingConversionService conversionService new DefaultFormattingConversionService(false); DateTimeFormatterRegistrar dateTimeRegistrar new DateTimeFormatterRegistrar(); dateTimeRegistrar.setDateFormatter(DateTimeFormatter.ofPattern(yyyy-MM-dd)); dateTimeRegistrar.setDateTimeFormatter(DateTimeFormatter.ofPattern(yyyy-MM-dd HH:mm:ss)); dateTimeRegistrar.registerFormatters(conversionService); DateFormatterRegistrar dateRegistrar new DateFormatterRegistrar(); dateRegistrar.setFormatter(new DateFormatter(yyyy-MM-dd)); dateRegistrar.registerFormatters(conversionService); return conversionService; } }这段代码本身逻辑没问题问题出在extends WebMvcConfigurationSupport。它一出现classpath:/static/、classpath:/public/、classpath:/resources/、classpath:/META-INF/resources/这些默认静态资源位置全部不再自动映射于是/plugins/mdui/css/mdui.min.css这类请求就落到了DispatcherServlet上找不到对应 handler抛出PageNotFound。注意WebMvcConfigurerAdapter在 Spring 5 之后已被标记为Deprecated新代码不要再继承它直接实现WebMvcConfigurer接口即可。3. 可复制配置用 WebMvcConfigurer 重写并保留静态资源3.1 改造日期格式化配置类把原来的继承关系换成实现接口方法签名从Bean改成addFormatters重写Configuration public class DateTimeConfig implements WebMvcConfigurer { private static final Logger logger LoggerFactory.getLogger(DateTimeConfig.class); Override public void addFormatters(FormatterRegistry registry) { logger.info(DateTimeConfig: 注册自定义日期时间格式化器); DateTimeFormatterRegistrar dateTimeRegistrar new DateTimeFormatterRegistrar(); dateTimeRegistrar.setDateFormatter(DateTimeFormatter.ofPattern(yyyy-MM-dd)); dateTimeRegistrar.setDateTimeFormatter(DateTimeFormatter.ofPattern(yyyy-MM-dd HH:mm:ss)); dateTimeRegistrar.registerFormatters(registry); DateFormatterRegistrar dateRegistrar new DateFormatterRegistrar(); dateRegistrar.setFormatter(new DateFormatter(yyyy-MM-dd)); dateRegistrar.registerFormatters(registry); } }这样日期格式化能力保留同时 Spring Boot 的静态资源自动配置不受影响。3.2 追加自定义静态资源映射如果你的静态资源不在默认目录比如放在classpath:/static/plugins/下需要额外映射/plugins/**可以单独写一个配置类Configuration public class WebResourceConfig implements WebMvcConfigurer { Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler(/plugins/**) .addResourceLocations(classpath:/static/plugins/) .setCachePeriod(0); } }setCachePeriod(0)在开发阶段很有用避免浏览器缓存旧文件导致你以为没生效。生产环境可以改成3600或交给 Nginx 处理。3.3 开启静态资源调试日志在application.yml里加上logging: level: org.springframework.web: DEBUG org.springframework.web.servlet.resource: DEBUG启动后访问静态资源正常应该看到类似日志DEBUG o.s.w.s.r.ResourceHttpRequestHandler - Resource found: class path resource [static/plugins/mdui/css/mdui.min.css]如果看到的是No mapping for GET说明映射链还是没生效回到第 2 节检查是否还有别的类继承了WebMvcConfigurationSupport。4. 验证请求用 curl 和 jar 包内容确认修复4.1 先确认资源真的打进了 jar很多时候 404 不是配置问题而是资源根本没被 Maven 打包进去。用下面命令检查jar -tvf target/*.jar | grep mdui.min.css正确输出应该类似BOOT-INF/classes/static/plugins/mdui/css/mdui.min.css如果这里没有输出说明pom.xml的resources配置或build插件把静态目录排除了先修打包再谈映射。4.2 用 curl 验证静态资源启动应用后执行curl -v http://localhost:8080/plugins/mdui/css/mdui.min.css预期响应头HTTP/1.1 200 Content-Type: text/css Content-Length: 12345如果返回404再看响应体里有没有No mapping for GET字样有的话就是映射问题如果返回200但内容为空检查addResourceLocations路径末尾的斜杠——classpath:/static/plugins/结尾必须带/否则会拼错路径。4.3 验证接口映射是否也正常静态资源修好后顺手确认业务接口没被影响curl -v http://localhost:8080/api/user/1预期返回 JSON 数据。如果接口也 404说明你的WebMvcConfigurer实现里可能覆盖了configurePathMatch或addInterceptors导致路径匹配异常逐个方法排查。4.4 用 TaoToken 统一通道接入 AI 排查工具排查这类问题时我习惯把日志片段和配置代码丢给 AI 工具做交叉分析。但多个工具各自要 Key、各自要配 Base URL切换起来很烦。TaoToken 提供统一的 API 通道把模型对话、编码辅助等能力收敛到一个 Key 上。接入方式很简单在需要配置 Base URL 的地方填https://taotoken.net/api然后在对应工具的配置里填入你在控制台生成的 Key。控制台地址是https://taotoken.net/consoleKey 管理在https://taotoken.net/api-keys。如果你用的是 Claude Code 这类编码 Agent可以参考https://taotoken.net/ClaudeCodeAnthropic的接入说明想先验证模型是否通直接打开https://taotoken.net/models对话测试即可。长期做编码和 Agent 任务的话Coding Plan 页面https://taotoken.net/coding-plan有更细的配置说明。提示TaoToken 只是统一 Key 和 API 通道不替代你的编辑器或 IDE排查逻辑还是得自己走一遍。5. 本篇常见错排查清单5.1 还有别的类继承了 WebMvcConfigurationSupport这是最常见的漏网之鱼。全局搜索grep -rn extends WebMvcConfigurationSupport src/main/java只要还有一个静态资源就继续 404。全部改成implements WebMvcConfigurer。5.2 addResourceLocations 路径末尾漏斜杠// 错误写法会导致路径拼接异常 .addResourceLocations(classpath:/static/plugins) // 正确写法 .addResourceLocations(classpath:/static/plugins/)5.3 拦截器把静态资源也拦了如果你注册了拦截器且addPathPatterns(/**)静态资源请求也会被拦截。需要在excludePathPatterns里排除registry.addInterceptor(new AuthInterceptor()) .addPathPatterns(/**) .excludePathPatterns(/static/**, /plugins/**, /css/**, /js/**);5.4 Spring Security 默认拦截静态资源引入 Spring Security 后默认所有请求都要认证静态资源也会被拦。需要在配置里放行http.authorizeRequests() .antMatchers(/plugins/**, /css/**, /js/**, /images/**).permitAll() .anyRequest().authenticated();5.5 打包时资源被过滤检查pom.xml的resources配置确保src/main/resources下的静态文件没有被excludes排除。默认 Spring Boot Starter Parent 已经处理好但老项目手动配置过就容易出问题。5.6 用了 EnableWebMvc 注解EnableWebMvc同样会导入DelegatingWebMvcConfiguration它继承自WebMvcConfigurationSupport效果和直接继承一样——自动配置全失效。检查启动类或配置类上有没有这个注解有的话删掉。6. 把 AI 排查接进你的工作流静态资源 404 这类问题本质是配置优先级和自动配置退避机制在作怪。记住一条铁律在 Spring Boot 里做 MVC 扩展永远优先实现WebMvcConfigurer不要继承WebMvcConfigurationSupport也不要加EnableWebMvc。只有当你确实需要彻底接管 MVC 行为、放弃所有自动配置时才考虑后者。排查流程可以固化成三步先用jar -tvf确认资源打进了包再用curl -v确认 HTTP 状态码和响应头最后开 DEBUG 日志看ResourceHttpRequestHandler有没有找到资源。三步走完问题基本定位。如果你在多个 AI 工具之间切换做代码分析可以用 TaoToken 把 Key 和 API 通道统一起来减少配置成本。接入文档在https://taotoken.net/doc模型验证在https://taotoken.net/models编码 Agent 场景看https://taotoken.net/coding-plan。把精力留给真正的排查逻辑而不是反复填 Key。

网站建设高端定制企业官网