Spring Boot启动失败：No qualifying bean of type ServletWebServerFactory解析与解决

前阵子群里一个小伙伴甩了一张截图过来IDEA 控制台里一大片红色报错顶部写着 APPLICATION FAILED TO START往下翻是 No qualifying bean of type org.springframework.boot.web.server.ServletWebServerFactory defined。他项目能编译代码看着也没问题就是起不来。这个错误我在 Spring Boot 项目里遇到过好几次网上搜出来的答案五花八门有的让你加依赖有的让你删缓存有的让你改启动类看得人更懵。今天干脆把这个问题从头到尾捋一遍把报错背后的原理、排查路径和几个经典型的解决方式都写清楚下次再碰到就能照着一步步查不用再一头扎进搜索引擎里碰运气。先说清楚这个报错是干什么的。ServletWebServerFactory 是 Spring Boot 嵌入式容器Tomcat、Jetty、Undertow的工厂接口Spring Boot 能够自动启动容器、监听端口全靠它。如果你的应用本身是个 Web 项目但 Spring 容器里找不到这个工厂类应用自然就启动不了。换句话说这个报错的核心不是业务代码写错了而是 Spring Boot 的自动配置没有把 Web 容器这一套装配起来。至于为什么没装配下面慢慢拆。适合被这个问题折磨的人刚把 Spring Boot 项目从别人仓库 clone 下来、在 IDEA 里一跑就挂的初学者从非 Web 工程改造成 Web 工程时踩坑的同学以及版本升级后莫名其妙起不来的老手。场景不同触发的原因也不完全一样但排查思路是通用的。1. 先看清楚错误现场1.1 报错长什么样IDEA 控制台里最典型的一段是这样的*************************** APPLICATION FAILED TO START *************************** Description: Parameter 0 of method errorPageCustomizer in org.springframework.boot.web.servlet.error.ErrorMvcAutoConfiguration required a single bean, but 0 were found: - No qualifying bean of type org.springframework.boot.web.server.ServletWebServerFactory defined: expected single matching bean but found 0 Action: Consider revisiting the entries above or defining a bean of type org.springframework.boot.web.server.ServletWebServerFactory in your configuration.注意看最后一行主角就是 ServletWebServerFactory。这个单词本身很长很多同学第一眼看到就直接去搜“missing ServletWebServerFactory”其实报错原文里还有一行关键信息required a single bean, but 0 were found。这里的 0 were found 说明 Spring 容器在启动自动配置类 ErrorMvcAutoConfiguration 时需要注入一个 ServletWebServerFactory 类型的 Bean结果容器里一个都没有。这里有个细节容易被忽略报错出现的位置是 ErrorMvcAutoConfiguration也就是错误页面的自动配置。这个类本身是用来处理 HTTP 错误页面的但它依赖 Web 容器工厂如果你连容器都没装配起来这个自动配置类就会卡住整个 Spring 容器的初始化流程也就中断了。还有一类变体报错出现在 Spring Boot 2.4 之后的版本里报错方法名可能不是 errorPageCustomizer而是 TomcatWebServerFactoryCustomizer 或者 ServletWebServerFactoryConfiguration但核心的 No qualifying bean of type ... ServletWebServerFactory 是跑不掉的。只要你看到这一句问题方向就锁定了。1.2 missing ServletWebServerFactory到底在说什么要理解这个报错得先知道 Spring Boot 是怎么把 Web 容器创建出来的。Spring Boot 的设计思路是“约定优于配置”只要你把 spring-boot-starter-web 这个依赖加进 classpath自动配置类 ServletWebServerFactoryAutoConfiguration 就会根据 classpath 上的具体容器实现帮你创建一个对应的工厂 Bean。这个工厂接口在 Spring Boot 2.x 里是 org.springframework.boot.web.server.ServletWebServerFactory实现类主要有三个实现类对应依赖说明TomcatServletWebServerFactoryspring-boot-starter-tomcat默认容器最常用JettyServletWebServerFactoryspring-boot-starter-jetty替换 Tomcat 时使用UndertowServletWebServerFactoryspring-boot-starter-undertow替换 Tomcat 时使用当你调用 SpringApplication.run() 时Spring Boot 会先判断应用类型classpath 里有 javax.servlet.Servlet 和 org.springframework.web.context.ConfigurableWebApplicationContext就判定为 Servlet Web 应用有 org.springframework.web.reactive.DispatcherHandler就是 WebFlux 响应式应用都没有就是普通 non-web 应用。判断出来是 Servlet Web 应用之后Spring Boot 才会去创建 ServletWebServerFactory Bean接着启动内嵌容器监听端口。所以“missing ServletWebServerFactory”这句话背后的含义是Spring Boot 在启动时面对的是非 Web 上下文根本没有走创建 Web 容器的分支但某些自动配置又需要 Web 容器工厂两边一冲突就炸了。用生活化的类比你把车钥匙插进去了也拧到了启动挡但仪表盘显示发动机没转——因为某个传感器压根没接上车辆系统自己都不知道你是在开车还是在原地听广播。Spring Boot 也一样代码看着像是要跑一个 Web 服务但容器判定你不是 Web 环境自然不会去创建端口监听后续依赖 Web 的自动配置自然找不到工厂。2. 动手排查按这四步走基本能定位遇到这种报错别急着删代码重写。按照下面四个方向依次排查百分之八九十能定位到根因。2.1 第一步检查 pom.xml 或 build.gradle 里的依赖这是最高频的原因没有之一。打开项目里的 pom.xml找 dependencies 区域看有没有下面这段dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency注意没有版本号是因为父工程已经统一管理了Spring Boot 项目里一般都会继承 spring-boot-starter-parent。我见过很多同学因为没继承父工程手动加了一堆版本号结果依赖冲突得一塌糊涂报错一个接一个。如果 pom.xml 里根本没有 spring-boot-starter-web只有 spring-boot-starter注意少了 -web 这两个字母那你的项目就不是一个 Web 工程Spring Boot 自然不会装配内嵌容器。这个时候如果 main 方法里还用了 SpringApplication.run()启动时虽然不会因为没有 Web 依赖而立刻报这个错实际上会正常按 non-web 启动但只要你引入了 spring-boot-starter-actuator 或者其他间接依赖了 Web 自动配置的库报错就会冒出来。还有种情况是依赖写的是 spring-boot-starter-webflux也就是 WebFlux 响应式工程。这种工程依赖的是 ReactiveWebServerFactory而不是 ServletWebServerFactory。如果你的代码里或者某个自动配置组件里硬要 Servlet 容器也会出现类似的报错。所以要看清楚到底是 starter-web 还是 starter-webflux两者不能混着乱用除非有特殊需求要同时支持那也得做额外配置一般不建议新手这么干。Gradle 项目看 build.gradledependencies { implementation org.springframework.boot:spring-boot-starter-web }补充一个判断技巧打开 IDEA 左侧的 Project 面板展开 External Libraries搜索 tomcat-embed-core 或 spring-boot-starter-tomcat。如果搜不到说明 Web 容器的核心实现类不在 classpath 里这本身就是一条有力的线索。2.2 第二步检查启动类上的注解和上下文类型pom.xml 里依赖没问题那就要看启动类和 SpringApplication 的配置了。有些项目为了特殊需求会在启动类上这么写SpringBootApplication(exclude {ServletWebServerFactoryAutoConfiguration.class})或者是SpringBootApplication(excludeName {org.springframework.boot.autoconfigure.web.servlet.ServletWebServerFactoryAutoConfiguration})不管是哪一种都相当于手动把 Web 容器自动配置掐掉了。这种情况常见于某些老项目改造或者有人想强行禁用 Tomcat 换别的容器结果忘了补配置。排查方法很简单看启动类上的 SpringBootApplication 注解有没有 exclude 或 excludeName 属性把相关的排除全部去掉就好。还有一种情况不在注解里在启动代码里public static void main(String[] args) { SpringApplication app new SpringApplication(Application.class); app.setWebApplicationType(WebApplicationType.NONE); app.run(args); }或者用了 SpringApplicationBuildernew SpringApplicationBuilder(Application.class) .web(WebApplicationType.NONE) .run(args);这两段代码都是告诉 Spring Boot不要启动 Web 容器。实际操作中很多同学是从别人的代码里复制过来的自己也不知道这一行的含义等到项目要从工具类改成 Web 服务时这行残留代码就成了拦路虎。建议全局搜索 WebApplicationType.NONE看看代码里有没有这种强制指定搜到就要重点审查。2.3 第三步检查配置文件里有没有隐藏的开关Spring Boot 提供了 spring.main.web-application-type 配置项可以直接在 application.properties 或 application.yml 里指定 Web 应用类型spring.main.web-application-typenone如果配置文件里有这一行Spring Boot 同样会强制按非 Web 方式启动后面即使有 starter-web也装配不了 ServletWebServerFactory。这行配置怎么来的呢有些老教程为了不启动 Tomcat 而“只跑 Spring 容器的业务逻辑”会在配置里加这一行还有些项目是拆服务的时候把公共模块的配置带过来了。总之全局搜索一下 web-application-type看到就删掉或者改成 servlet。注意这里有个版本差异Spring Boot 2.0 之前用的是 spring.main.web-environmentfalse旧项目迁移到 2.x 时这一项会被忽略或者行为不一致需要顺手改成新的配置项。如果是从非常老的版本升上来的还得验证一下配置是否真的生效有时候改了 application.properties 但实际加载的是 application.yml两个文件同时存在时优先级和合并逻辑也会让人迷糊所以检查的时候两个文件都要看。2.4 第四步检查多模块工程和依赖排除如果你的项目是 Maven 多模块结构比如一个 parent 下挂了好几个 module那就得注意依赖在模块间的传递关系了。举个例子公共模块 common 是一个纯工具模块里面没有放 spring-boot-starter-web业务模块 service 依赖了 common并且自己在 pom 里也没有显式加 starter-web。这时候你在 service 模块里写了一个 SpringBootApplication 启动类启动时 Spring Boot 能扫描到的 classpath 里没有 Web 容器相关类同样会报 ServletWebServerFactory 缺失。还有一种隐蔽情况某个 module 里把 spring-boot-starter-web 用 exclusion 排除了比如dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId exclusions exclusion groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-tomcat/artifactId /exclusion /exclusions /dependency排除 spring-boot-starter-tomcat 的目的是替换成 Jetty 或 Undertow这是合法的。但如果你排除了 starter-web 本身或者排除了 web 相关的核心自动配置类那就会引发问题。Maven 的依赖树可以用这个命令看mvn dependency:tree -Dincludesorg.springframework.boot在 IDEA 右侧的 Maven 面板里也能看到依赖树Dependencies 节点下面一层层展开。重点看 spring-boot-starter-web 有没有真的传递进来以及 tomcat 相关的依赖有没有被 exclude 掉。3. 解决方案按场景对症下药排查完了接下来就是对症处理。我按场景把解决方案列出来大家根据自己的原因对号入座。3.1 场景一缺 web 启动器依赖这是最简单也最常见的一种处理方式就是补依赖。Maven 项目在 pom.xml 的 dependencies 里加上dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependencyGradle 项目在 build.gradle 里加dependencies { implementation org.springframework.boot:spring-boot-starter-web }加完依赖之后记得在 IDEA 右侧 Maven 面板点一下刷新按钮一个圆形箭头的图标让 IDEA 重新加载依赖。很多同学改了 pom.xml 之后没有刷新IDEA 的 classpath 还是旧的然后回来问“为什么加了依赖还是报错”这个问题在后面的避坑环节会专门展开。如果加依赖之前项目连 spring-boot-starter-parent 都没有那建议先统一继承父工程让版本号由父工程管理不然你需要自己给 starter-web 指定 version 属性版本不对又会导致一堆连锁问题。常见的做法是在 pom.xml 的 parent 节点里配置parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version2.7.18/version relativePath/ /parent这样写之后所有 spring-boot 开头的 starter 依赖都不用手动写版本号了版本对齐问题也顺带解决。3.2 场景二启动方式不对如果依赖没问题是启动代码里强制指定了 WebApplicationType.NONE改法很简单public static void main(String[] args) { SpringApplication.run(Application.class, args); }直接用最普通的 SpringApplication.run 就行让 Spring Boot 自动推断 Web 环境。如果你确实需要对 Web 应用类型做精细控制比如明确指定是 Servlet 类型可以这么写public static void main(String[] args) { SpringApplication app new SpringApplication(Application.class); app.setWebApplicationType(WebApplicationType.SERVLET); app.run(args); }或者是new SpringApplicationBuilder(Application.class) .web(WebApplicationType.SERVLET) .run(args);这样写的好处是强制按 Servlet 容器方式启动即使 classpath 里存在 WebFlux 相关类也不会被干扰。坏处是如果 classpath 里真的没有容器实现类那报错会变成别的比如 ClassNotFoundException属于把错误类型从“缺工厂 Bean”变成了“缺实现类”定位思路反过来。配置文件里如果有 spring.main.web-application-typenone删掉或改成 servletspring.main.web-application-typeservlet这里再补充一个点Spring Boot 2.x 里WebApplicationType.SERVLET 对应的实际是 Servlet 方式的 Web 应用WebApplicationType.REACTIVE 对应 WebFluxNONE 就是完全非 Web。如果业务上既不是 Web 也不是响应式确实想要 NONE那就要注意不要引入任何依赖 Web 容器的自动配置类否则一样会炸。总之这个配置项是用来表达意图的你的意图是“跑一个 Web 服务”那就别写 NONE。3.3 场景三测试类里手动指定了不匹配的环境还有一种容易忽略的场景项目能正常启动但一跑某个 SpringBootTest 测试类就报 ServletWebServerFactory 缺失。看一下测试类上的注解SpringBootTest(webEnvironment SpringBootTest.WebEnvironment.NONE)WebEnvironment.NONE 表示这个测试不启动 Web 容器只加载 Spring 上下文。如果你的测试代码里又去调用那些依赖 Web 容器的 Bean比如注入了一个 ServletContext 相关的东西就会出现缺 Bean 的报错。解决方法是把 webEnvironment 改成 MOCK默认值或 RANDOM_PORTSpringBootTest(webEnvironment SpringBootTest.WebEnvironment.RANDOM_PORT)MOCK 表示加载 WebApplicationContext但不启动真实的 Servlet 容器适合测试 Controller 层时用 MockMvcRANDOM_PORT 表示启动真实容器分配一个随机端口适合做集成测试。如果只是测试 Service 层的纯逻辑用 NONE 也没问题但前提是你的测试代码里没有引用任何 Web 容器相关的 Bean。这里有个经验之谈遇到“启动类能跑起来测试类跑不起来”的报错先看测试类的 webEnvironment十有八九是这里设置错了。4. 避坑指南与常见迷惑点4.1 端口冲突被误诊为 missing ServletWebServerFactory网上有大量帖子把“端口被占用”和“ServletWebServerFactory 缺失”混为一谈因为报错的展示位置都是 APPLICATION FAILED TO START 那个大红块。实际上端口冲突的报错长这样*************************** APPLICATION FAILED TO START *************************** Description: Web server failed to start. Port 8080 was already in use.这个报错跟 missing ServletWebServerFactory 完全是两码事。端口冲突说明容器工厂已经创建了只是绑定端口时发现 8080 被别的进程占了。处理方式要么换端口要么找出来占端口的进程杀掉要么同时跑多个实例时用随机端口。注意区分这两类错误的报错文本前者有 already in use 字样后者有 No qualifying bean 字样。我在实际项目里见过最离谱的一次是有人把端口改成了 8080 之后另一个服务也占用了 8080然后错误信息里出现了 port 8080 was already in use他硬是去改了 ServletWebServerFactory 相关的配置折腾了一天最后发现只是端口占用。所以第一件事永远是读完整报错不要只看关键词。4.2 Spring Boot 2.x 与 3.x 的包名差异这个报错在不同 Spring Boot 版本里的表现还不完全一样。Spring Boot 2.x 里的 ServletWebServerFactory 在 org.springframework.boot.web.server 包下Spring Boot 3.x 里移动到了 org.springframework.boot.web.servlet 包下同时 Servlet 相关 API 也从 javax.servlet 变成了 jakarta.servlet。如果你升级了 Spring Boot 版本报错信息里的类全限定名会不一样。比如 2.x 的报错是No qualifying bean of type org.springframework.boot.web.server.ServletWebServerFactory3.x 的报错可能是No qualifying bean of type org.springframework.boot.web.servlet.ServletWebServerFactory类名一样包路径变了。排查思路不变但如果你搜解决方案一定要选对版本匹配的内容否则照着 Spring Boot 2.x 的答案去改 Spring Boot 3.x 项目很多地方对不上。比如 Spring Boot 3.x 里改 Web 应用类型的配置项依然是 spring.main.web-application-typeservlet这个配置项本身没有变但背后的类型判定逻辑换成了 jakarta 规范。另外Spring Boot 3.0 开始要求 Java 17如果你的 JDK 版本不对可能还没到容器装配这个环节就先在类加载阶段崩了。4.3 IDEA 缓存和 Maven 依赖同步问题IDEA 里有一个很常见但很多人没意识到的问题pom.xml 改了之后IDE 的依赖索引没刷新运行环境还是旧的 classpath。症状就是明明加了 spring-boot-starter-web重新运行还是报一样的错。解决办法分几步在 IDEA 右侧 Maven 面板里点刷新按钮让它重新解析依赖。如果刷新还不行执行 mvn clean 然后重新运行。再不行File - Invalidate Caches... 清理缓存勾选 Clear file system cache and Local History重启 IDEA。还有一个容易忽略的点如果你用的是 Spring Initializr 生成的项目在 IDEA 里第一次打开时右下角会提示“Unlinked Maven Project”要点击加载否则 IDEA 根本不知道你的依赖。很多初学者会直接忽略这个弹窗然后各种报错。mvn clean compile这个命令在命令行里执行一下看能不能通过编译。如果命令行可以IDEA 不行基本就是 IDE 层面的缓存问题如果命令行也不行说明是代码或依赖层面的问题跟 IDEA 没关系。这一步能帮你快速区分问题归属省得在 IDEA 设置里折腾半天。4.4 各种报错变体速查表为了方便大家对照我把这个报错在几种常见场景下的表现整理成一张速查表场景报错关键内容直接原因缺 spring-boot-starter-webNo qualifying bean of type ... ServletWebServerFactory容器工厂自动配置因 classpath 缺类被跳过配置了 web-application-typenoneSpringApplication 以非 Web 类型启动上下文类型不是 WebApplicationContext启动类 exclude 了自动配置同上自动配置被手动关闭测试类 webEnvironmentNONE测试上下文缺 Bean测试环境不是 Web 上下文WebFlux 项目误用 Servlet 组件提示 ServletWebServerFactory 而不是 Reactive 工厂依赖类型不匹配这张表不是说要背下来而是帮你在看到报错时能快速对号入座。核心判断依据就两个一是 classpath 里有没有容器实现类二是 Spring 容器有没有按 Web 类型启动。这两个依据搞清楚了报错怎么变都能应对。5. 实战排查中的几条经验5.1 先读完整日志再搜关键词这个错误出现在“No qualifying bean”这个关键句上但前面往往会有更多上下文。比如说报错信息里如果出现了 WebServerApplicationContext 或者 ServletWebServerApplicationContext 相关内容说明上下文已经按 Web 类型加载了只是因为某种原因缺了容器实现类如果上下文类型是 AnnotationConfigApplicationContext说明整个上下文压根就是非 Web 的。这两种情况排查方向完全不同。我见过有人看到报错信息里带着 WebServer 几个字母就断定是 Web 环境问题折腾半天也没解决其实日志往下多翻几行就能看到当前上下文类型的描述直接指明了方向。日志这种东西读得越完整试错成本越低。5.2 善用依赖树和自动配置报告如果项目是从网上 clone 的或者经历过多个人维护排除依赖的做法可能非常随意。直接在 IDEA 的 Maven 面板里右键 - Show Diagrams 看依赖图找找有没有红色的冲突标记或者干脆用 mvn dependency:tree 把依赖树完整导出来CtrlF 搜一下 spring-boot-starter-web 和 spring-boot-starter-tomcat看看它们在不在、有没有被 exclude。这一招能帮你快速定位依赖层面的问题。另外排查这类问题的时候可以在启动参数里加上 --debugjava -jar your-app.jar --debugIDEA 里也可以在 Run/Debug Configurations 的 Program arguments 里填 --debug。这个参数会打印自动配置的报告比如 Positive matches 和 Negative matches 里关于 ServletWebServerFactoryAutoConfiguration 的匹配情况。如果自动配置类没有出现在 Positive matches 里说明它因为条件不满足而被跳过这时候报错原因就一目了然了。5.3 版本升级和依赖锁定我自己的项目从 Spring Boot 2.3 升到 2.7 时遇到过自动配置行为变化导致的报错跟这个 ServletWebServerFactory 缺失如出一辙。升级后不只是编译通过就完事启动一次、跑一个冒烟测试很多自动配置类的坑才能暴露出来。Spring Boot 的自动配置在不同 minor 版本之间都可能改行为依赖版本锁定要谨慎。如果项目里用到了 spring-boot-dependencies BOM 来管理版本别把不同大版本的依赖混在一起。比如你用了 Spring Boot 2.7 的 BOM又强行引入了 3.2 版本的某个 starter那自动配置类可能来自不同的包结构运行期就会出各种奇奇怪怪的问题。版本统一这件事在 Spring Boot 生态里怎么强调都不过分。5.4 一个临时验证的笨办法实在不确定容器工厂是否装配成功可以在启动类里临时加一段输出SpringBootApplication public class Application { public static void main(String[] args) { ConfigurableApplicationContext ctx SpringApplication.run(Application.class, args); System.out.println(WebServerFactory count: ctx.getBeansOfType(ServletWebServerFactory.class).size()); } }启动之后控制台会输出容器工厂 Bean 的数量0 就说明确实没装配问题就在自动配置被跳过大于 0 说明容器工厂已经存在报错来源可能另有他处。当然这个代码是临时加的定位完要记得删掉。我个人在实际操作中的体会是这类“missing ServletWebServerFactory”的报错绝大多数情况下都不是什么高深的问题翻来覆去就是依赖缺失、上下文类型不对、自动配置被排除这几种。真正耗时间的反而不是修复而是被网上各种新旧混杂的答案带偏方向。只要把 Spring Boot 判断应用类型的那套规则记在心里第一步先看依赖第二步看启动类和配置项多看几行日志问题基本都能在十分钟内定位。希望这篇整理能帮你少走点弯路下次 IDEA 控制台再飘红时心里能有个底。