Spring Boot打包启动报错：resourceHandlerMapping Bean创建失败

问题现象 #

开发Spring Boot应用时，在IntelliJ中运行正常，但打包成artifact启动时抛出以下错误：

org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'resourceHandlerMapping' defined in class path resource [org/springframework/web/servlet/config/annotation/DelegatingWebMvcConfiguration.class]: Bean instantiation via factory method failed; nested exception is org.springframework.beans.BeanInstantiationException: Failed to instantiate [org.springframework.web.servlet.HandlerMapping]: Factory method 'resourceHandlerMapping' threw exception; nested exception is java.lang.IllegalStateException: No ServletContext set
    at org.springframework.beans.factory.support.ConstructorResolver.instantiate(ConstructorResolver.java:658)
    at org.springframework.beans.factory.support.ConstructorResolver.instantiateUsingFactoryMethod(ConstructorResolver.java:638)
    at org.springframework.beans.factory.support.AbstractAutowireCapableBeanFactory.instantiateUsingFactoryMethod(AbstractAutowireCapableBeanFactory.java:1352)
    at org.springframework.beans.factory.support.AbstractAutowireCapableBeanFactory.createBeanInstance(AbstractAutowireCapableBeanFactory.java:1195)
    at org.springframework.beans.factory.support.AbstractAutowireCapableBeanFactory.doCreateBean(AbstractAutowireCapableBeanFactory.java:582)
    at org.springframework.beans.factory.support.AbstractAutowireCapableBeanFactory.createBean(AbstractAutowireCapableBeanFactory.java:542)
    at org.springframework.beans.factory.support.AbstractBeanFactory.lambda$doGetBean$0(AbstractBeanFactory.java:335)
    at org.springframework.beans.factory.support.DefaultSingletonBeanRegistry.getSingleton(DefaultSingletonBeanRegistry.java:234)
    at org.springframework.beans.factory.support.AbstractBeanFactory.doGetBean(AbstractBeanFactory.java:333)
    at org.springframework.beans.factory.support.AbstractBeanFactory.getBean(AbstractBeanFactory.java:208)
    at org.springframework.beans.factory.support.DefaultListableBeanFactory.preInstantiateSingletons(DefaultListableBeanFactory.java:953)
    at org.springframework.context.support.AbstractApplicationContext.finishBeanFactoryInitialization(AbstractApplicationContext.java:918)
    at org.springframework.context.support.AbstractApplicationContext.refresh(AbstractApplicationContext.java:583)
    at org.springframework.boot.SpringApplication.refresh(SpringApplication.java:734)
    at org.springframework.boot.SpringApplication.refreshContext(SpringApplication.java:408)
    at org.springframework.boot.SpringApplication.run(SpringApplication.java:308)
    at org.springframework.boot.SpringApplication.run(SpringApplication.java:1306)
    at org.springframework.boot.SpringApplication.run(SpringApplication.java:1295)
    at com.backend.core.CoreApplication.main(CoreApplication.java:20)
Caused by: org.springframework.beans.BeanInstantiationException: Failed to instantiate [org.springframework.web.servlet.HandlerMapping]: Factory method 'resourceHandlerMapping' threw exception; nested exception is java.lang.IllegalStateException: No ServletContext set
    at org.springframework.beans.factory.support.SimpleInstantiationStrategy.instantiate(SimpleInstantiationStrategy.java:185)
    at org.springframework.beans.factory.support.ConstructorResolver.instantiate(ConstructorResolver.java:653)
    ... 18 common frames omitted
Caused by: java.lang.IllegalStateException: No ServletContext set
    at org.springframework.util.Assert.state(Assert.java:76)
    at org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport.resourceHandlerMapping(WebMvcConfigurationSupport.java:591)
    at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
    at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62)
    at java.base/jdk.internal.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
    at java.base/java.lang.reflect.Method.invoke(Method.java:566)
    at org.springframework.beans.factory.support.SimpleInstantiationStrategy.instantiate(SimpleInstantiationStrategy.java:154)
    ... 19 common frames omitted

环境与尝试操作 #

• 使用spring-boot-starter-web包（包含默认Tomcat servlet）
• 推测异常原因：继承WebMvcConfigurationSupport的Bean创建过早，早于ServletContext就绪
• 尝试修改/移除WebConfig.java、SecurityConfig.java和CoreApplication.java上的部分注解，无效
• 测试发现：在CoreApplication.java添加@EnableAutoConfiguration(exclude = { WebMvcAutoConfiguration.class })后，打包的jar可正常运行，但会丢失WebMvcAutoConfiguration的配置，导致应用无法接收HTTP请求

提问 #

1. 如何配置WebMvcAutoConfiguration让应用正常监听HTTP请求？
2. 如何让继承WebMvcConfigurationSupport的Bean在ServletContext就绪后再创建？

解决方案 #

方案1：替换WebMvcConfigurationSupport的继承方式 #

Spring Boot中，直接继承WebMvcConfigurationSupport会禁用WebMvcAutoConfiguration的自动配置，这是冲突的核心原因。推荐改用@Configuration + @WebMvcConfigurer的方式定制MVC配置：

@Configuration
public class WebConfig implements WebMvcConfigurer {
    // 重写需要定制的MVC方法，比如addResourceHandlers、addInterceptors等
}

这种方式既保留WebMvcAutoConfiguration的默认配置，又能实现自定义逻辑，避免Bean初始化时机冲突。

方案2：延迟Bean初始化（必须继承WebMvcConfigurationSupport时） #

如果因业务需求必须继承WebMvcConfigurationSupport，可通过以下方式延迟Bean初始化：

1. 在配置类上添加@Lazy注解：

@Configuration
@Lazy
public class WebConfig extends WebMvcConfigurationSupport {
    // 自定义配置逻辑
}

2. 或在启动类开启全局延迟初始化（注意：会影响首次请求性能，需权衡）：

@SpringBootApplication(lazyInitialization = true)
public class CoreApplication {
    public static void main(String[] args) {
        SpringApplication.run(CoreApplication.class, args);
    }
}

方案3：检查打包配置 #

确保使用Spring Boot官方打包插件，在pom.xml中确认配置：

<build>
    <plugins>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
            <version>${spring-boot.version}</version>
            <executions>
                <execution>
                    <goals>
                        <goal>repackage</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

用mvn clean package打包后，运行生成的*-spring-boot.jar即可，该包包含完整运行环境，能正确初始化ServletContext。

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