Spring WebFlux启动报错：LocaleContextResolver类未找到问题求助

问题背景 #

基于Spring Boot 3.0.2搭建的响应式WebFlux项目，启动时抛出IllegalStateException，提示无法自省org.springframework.web.reactive.config.DelegatingWebFluxConfiguration类，根源是ClassNotFoundException: org.springframework.web.server.i18n.LocaleContextResolver，且项目未配置任何国际化相关内容。

排查方向与解决方案 #

1. 检查依赖版本冲突（最常见原因） #

Spring Boot 3.0.x绑定的Spring Framework版本是6.0.x，LocaleContextResolver属于spring-web核心依赖。如果项目中混入了Spring 5.x的spring-web或spring-webflux依赖，就会出现类找不到的问题。

• 排查命令：

  # Maven项目查看依赖树
  mvn dependency:tree
  # Gradle项目查看依赖树
  ./gradlew dependencies
  

• 修复方式：
  • Maven：通过<dependencyManagement>强制统一Spring Web相关依赖版本为6.0.x（对应Spring Boot 3.0.2的适配版本）：

    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.springframework</groupId>
                <artifactId>spring-web</artifactId>
                <version>6.0.4</version>
            </dependency>
            <dependency>
                <groupId>org.springframework</groupId>
                <artifactId>spring-webflux</artifactId>
                <version>6.0.4</version>
            </dependency>
        </dependencies>
    </dependencyManagement>
    

  • Gradle：使用resolutionStrategy强制指定依赖版本：

    configurations.all {
        resolutionStrategy {
            force 'org.springframework:spring-web:6.0.4'
            force 'org.springframework:spring-webflux:6.0.4'
        }
    }
    

2. 确认依赖完整性与正确性 #

• 确保项目只引入spring-boot-starter-webflux，不要同时引入spring-boot-starter-web（会触发Servlet栈与Reactive栈的冲突）：

  <!-- 正确的WebFlux Starter依赖 -->
  <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-webflux</artifactId>
  </dependency>
  

• 检查是否有依赖被意外排除，比如在Maven中使用<exclusions>移除了spring-web核心依赖。

3. 检查自定义配置类 #

如果有自定义的WebFlux配置类：

• 确认继承的是org.springframework.web.reactive.config.WebFluxConfigurationSupport而非过时的类
• 避免引入旧版本的Spring Web相关包（比如org.springframework.web.servlet下的类，属于Servlet栈内容）

4. 清理本地依赖并重新构建 #

删除本地仓库中可能存在的损坏或冲突依赖，然后重新构建：

# Maven
mvn clean install -U
# Gradle
./gradlew clean build --refresh-dependencies

验证 #

完成上述操作后，再次启动项目，若ClassNotFoundException不再出现，说明问题已解决。

内容的提问来源于stack exchange，提问作者S.R.D