Spring Boot v3.3.4静态资源无法访问，求助排查方法

将原有Spring应用迁移到Spring Boot 3.3.4后，src/main/resources/static目录下的静态资源（html、css、js、png等）无法被正常访问。访问/index.html时，日志提示无对应请求映射。

日志片段 #

[DEBUG] 2024-11-02 14:16:57.789 [https-jsse-nio-8443-exec-1]  c.f.a.u.CustomRequestLoggingFilter - Before request [GET /index.html, headers=[host:"localhost:8443", connection:"keep-alive", pragma:"no-cache", cache-control:"no-cache", sec-ch-ua:""Google Chrome";v="129", "Not=A?Brand";v="8", "Chromium";v="129"", sec-ch-ua-mobile:"?0", sec-ch-ua-platform:""Windows"", upgrade-insecure-requests:"1", user-agent:"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/129.0.0.0 Safari/537.36", accept:"text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.7", sec-fetch-site:"none", sec-fetch-mode:"navigate", sec-fetch-user:"?1", sec-fetch-dest:"document", accept-encoding:"gzip, deflate, br, zstd", accept-language:"en-US,en;q=0.9", cookie:"Idea-2ba4f510=04bef4d7-875e-4491-bdd6-da8a4b98ccba; JSESSIONID=465E301E3CAD061A3DA5584DE01C1C59"]]
[WARN ] 2024-11-02 14:16:57.791 [https-jsse-nio-8443-exec-1]  o.s.w.s.PageNotFound - No mapping for GET /index.html
[WARN ] 2024-11-02 14:16:57.791 [https-jsse-nio-8443-exec-1]  o.s.w.s.PageNotFound - No endpoint GET /index.html.
[DEBUG] 2024-11-02 14:16:57.792 [https-jsse-nio-8443-exec-1]  c.f.a.u.CustomRequestLoggingFilter - After request [GET /index.html, headers=[host:"localhost:8443", connection:"keep-alive", pragma:"no-cache", cache-control:"no-cache", sec-ch-ua:""Google Chrome";v="129", "Not=A?Brand";v="8", "Chromium";v="129"", sec-ch-ua-mobile:"?0", sec-ch-ua-platform:""Windows"", upgrade-insecure-requests:"1", user-agent:"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/129.0.0.0 Safari/537.36", accept:"text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.7", sec-fetch-site:"none", sec-fetch-mode:"navigate", sec-fetch-user:"?1", sec-fetch-dest:"document", accept-encoding:"gzip, deflate, br, zstd", accept-language:"en-US,en;q=0.9", cookie:"Idea-2ba4f510=04bef4d7-875e-4491-bdd6-da8a4b98ccba; JSESSIONID=465E301E3CAD061A3DA5584DE01C1C59"]]

当前配置代码 #

WebConfig.java #

@Configuration
@EnableWebMvc
public class WebConfig implements WebMvcConfigurer {

    @Override
    public void configureViewResolvers(ViewResolverRegistry registry) {
        registry.groovy().cache(true);
    }

    @Override
    public void extendMessageConverters(List<HttpMessageConverter<?>> converters) {
        converters.add( new JsonConverter() );
        converters.add( new FileMessageConverter() );
        converters.add( new BufferedImageHttpMessageConverter());
    }

    @Bean
    public FilterRegistrationBean<SpringBootUrlRewriteFilter> urlRewriteFilter(@Value(SpringBootUrlRewriteFilter.CONFIG_LOCATION) Resource config) {
        FilterRegistrationBean<SpringBootUrlRewriteFilter> registration = new FilterRegistrationBean<>();
        registration.setFilter(new SpringBootUrlRewriteFilter(config));
        registration.addUrlPatterns("/*");
        registration.setName("urlRewriteFilter");
        registration.setOrder(SecurityProperties.DEFAULT_FILTER_ORDER-5);
        registration.setDispatcherTypes(DispatcherType.FORWARD,DispatcherType.REQUEST);
        return registration;
    }

    @Bean
    public AngularViewTemplateProcessor createAngularViewTemplateProcessor() {
        return new AngularViewTemplateProcessor();
    }
}

AppConfig.java #

@Configuration
@ComponentScan(basePackages = "com.fuseanalytics")
@PropertySources(value = {
        @PropertySource(value={"classpath:application.properties"}),
        @PropertySource(value = {"classpath:server.${spring.profiles.active:dev}.properties"}),
        @PropertySource(value={"file:${server.data.home}/credentials/credentials.properties"}),
        @PropertySource(value={"classpath:wro.${spring.profiles.active:dev}.properties"})
})
public class AppConfig {

    @Bean
    public BCryptPasswordEncoder getBcryptPasswordEncoder() {
        return new BCryptPasswordEncoder();
    }
}

排查思路与解决方法 #

核心问题定位 #

WebConfig类上的@EnableWebMvc注解是关键诱因。该注解会禁用Spring Boot的WebMvcAutoConfiguration自动配置类，而其中包含了静态资源映射（如classpath:/static/映射到/路径）的默认配置，导致静态资源无法被自动识别。

解决步骤 #

1. 移除@EnableWebMvc注解：保留WebConfig实现WebMvcConfigurer接口即可。Spring Boot会自动启用WebMvc基础配置，同时你的自定义配置（视图解析器、消息转换器等）会被合并生效。
2. 验证静态资源映射：启动应用后，通过调试日志或断点检查ResourceHandlerRegistry是否包含classpath:/static/**的映射规则。
3. 检查UrlRewriteFilter规则：确保该过滤器没有拦截静态资源请求，可在规则中添加放行静态资源的配置（如允许/css/**、/js/**、/index.html等路径直接通过）。
4. 确认资源目录结构：确保静态资源确实放在src/main/resources/static下，且打包后这些文件存在于classpath中（可查看target/classes/static目录）。

额外调试技巧 #

• 启用WebMvc调试日志：在application.properties中添加logging.level.org.springframework.web.servlet=DEBUG，查看请求处理流程中是否尝试查找静态资源。
• 检查Security配置：如果项目中有Spring Security配置，需确保静态资源路径被放行（如通过permitAll()方法允许访问/static/**、/index.html等）。

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