SpringBoot程序无法运行 报错Unable to start web server 嵌入式Tomcat启动失败

这个报错是SpringBoot启动Web容器时的外层包装异常，核心根因需要顺着异常栈向下找Caused by字段的具体错误信息，以下是最高频的触发场景和对应解决方法：

• 端口占用问题（占比最高）
  嵌入式Tomcat默认使用8080端口启动，如果该端口被其他进程（比如其他本地运行的服务、之前没正常关闭的SpringBoot进程）占用，会直接触发启动失败。
  排查命令：
  Windows环境执行：netstat -ano | findstr "8080"，拿到进程PID后可在任务管理器定位对应进程
  Linux/macOS环境执行：lsof -i:8080
  解决方法：要么结束占用端口的进程，要么修改SpringBoot配置文件更换服务端口，配置示例：

  # application.yml配置
  server:
    port: 8082 # 换成未被占用的端口
  

  properties格式配置直接加一行：server.port=8082
• Web组件配置/注册冲突
  自定义Servlet、Filter、Listener类时配置错误，会导致Tomcat Servlet上下文初始化失败：
  1. 检查自定义Web组件是否被重复注册：比如既通过@Bean手动注册了某个Filter，又给该Filter类加了@Component注解被Spring自动扫描注册
  2. 如果项目使用JSP视图，检查是否缺失Tomcat JSP解析依赖，Maven项目补全以下依赖即可：

  <dependency>
      <groupId>org.apache.tomcat.embed</groupId>
      <artifactId>tomcat-embed-jasper</artifactId>
      <scope>provided</scope>
  </dependency>
  

  3. 检查SpringBoot启动类上的注解是否误加了和Web容器冲突的配置，比如错误exclude了Tomcat相关的自动配置类。
• Tomcat工作目录异常
  嵌入式Tomcat启动时默认会在系统临时目录生成工作缓存文件，如果启动服务的用户对系统临时目录没有读写权限，或者临时目录被系统自动清理（部分Linux系统会定期清理/tmp下的长期未访问文件），也会导致启动失败。
  解决方法：
  1. 给启动用户分配系统临时目录（Linux默认路径/tmp，Windows默认路径C:\Users\当前用户名\AppData\Local\Temp）的读写权限
  2. 在配置中手动指定Tomcat工作目录，不依赖系统临时目录：

  server:
    tomcat:
      basedir: ./local-tomcat-dir # 自定义相对/绝对路径，确保目录存在且有权限
  

• 依赖版本冲突
  如果引入的第三方依赖中携带了和SpringBoot版本不匹配的Tomcat相关包（比如servlet-api、tomcat-embed-core等），会出现类找不到、方法签名不匹配的错误，导致Tomcat启动失败。
  排查方法：执行mvn dependency:tree（Maven项目）或gradle dependencies（Gradle项目）打印全量依赖树，排除掉非SpringBoot官方管理的、版本冲突的Tomcat相关依赖，统一使用SpringBoot父工程锁定的版本即可。

排查提示：如果以上场景都不符合，直接翻到异常日志最底部的Caused by段落，最内层的异常信息就是直接根因，比如数据库连接失败、配置文件格式错误这类非Tomcat本身的问题，也会被包装成Tomcat启动失败的外层异常抛出。

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