SpringBoot项目整合Elasticsearch启动失败的常见错误总结

最新推荐文章于 2025-11-22 22:40:07 发布

原创最新推荐文章于 2025-11-22 22:40:07 发布 · 8.7k 阅读

12 ·

CC 4.0 BY-SA版权

文章标签：

#spring boot #elasticsearch #spring cloud

Spring全家桶同时被 2 个专栏收录

40 篇文章

订阅专栏

elasticsearch高手

25 篇文章

订阅专栏

❃博主首页： 「程序员1970」，同名公众号「程序员1970」
☠博主专栏： <mysql高手> <elasticsearch高手> <源码解读> <java核心> <面试攻关>

文章目录

一、Bean定义冲突

1. MyBatis与Elasticsearch Repository扫描路径冲突

报错内容：

org.springframework.context.annotation.ConflictingBeanDefinitionException: 
Annotation-specified bean name 'articlesRepository' for bean class [com.dragon.springboot3vue3.mapper.ArticlesRepository] conflicts with existing, non-compatible bean definition of same name and class [org.springframework.data.elasticsearch.repository.support.ElasticsearchRepositoryFactoryBean]

原因：

@MapperScan (MyBatis注解) 和 @EnableElasticsearchRepositories (Spring Data注解) 扫描了相同的包路径

解决方案：

分离包路径（推荐）：

@SpringBootApplication
@MapperScan("com.example.mapper") // MyBatis Mapper
@EnableElasticsearchRepositories("com.example.es.repository") // ES Repository
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

或移除注解，让Spring Boot自动扫描：

@SpringBootApplication
// 注释掉以下两行
// @MapperScan("com.example.mapper")
// @EnableElasticsearchRepositories("com.example.es.repository")
public class Application {
    // ...
}

二、依赖配置问题

1. 缺少必要依赖或依赖版本不匹配

报错内容：

NoSuchBeanDefinitionException: No bean named 'elasticsearchTemplate' available

原因：

未正确引入Spring Data Elasticsearch依赖
依赖版本与Spring Boot不兼容

解决方案：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-elasticsearch</artifactId>
    <!-- 排除可能导致冲突的 Netty 依赖 -->
    <exclusions>
        <exclusion>
            <groupId>io.netty</groupId>
            <artifactId>netty-all</artifactId>
        </exclusion>
    </exclusions>
</dependency>

三、Elasticsearch服务连接问题

1. Elasticsearch服务未启动或地址配置错误

报错内容：

org.elasticsearch.client.ResponseException: method [GET], host [http://localhost:9200], URI [/_cluster/health/], status line [HTTP/1.1 404 Not Found]
Not Found

原因：

Elasticsearch服务未启动
配置的地址与实际Elasticsearch地址不匹配（如配置了localhost但实际在其他主机）

解决方案：

spring:
  elasticsearch:
    rest:
      uris: http://your-elasticsearch-server:9200 # 替换为实际地址

四、版本兼容性问题

1. Spring Boot与Elasticsearch版本不兼容

报错内容：

Factory method 'highLevelClient' threw exception
org.springframework.beans.BeanInstantiationException: Failed to instantiate [org.elasticsearch.client.RestHighLevelClient]: 
Factory method 'highLevelClient' threw exception

原因：

Spring Boot版本与Elasticsearch客户端版本不兼容
依赖冲突（如Spring Boot 2.0.3默认依赖Elasticsearch 5.6.10，但项目中使用了7.5.2版本）

解决方案：

确保Spring Boot与Elasticsearch版本兼容
显式排除默认版本并指定正确版本：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-elasticsearch</artifactId>
    <exclusions>
        <exclusion>
            <groupId>org.elasticsearch.client</groupId>
            <artifactId>elasticsearch-rest-high-level-client</artifactId>
        </exclusion>
    </exclusions>
</dependency>
<dependency>
    <groupId>org.elasticsearch.client</groupId>
    <artifactId>elasticsearch-rest-high-level-client</artifactId>
    <version>7.5.2</version>
</dependency>

五、Elasticsearch健康检查问题

1. Actuator健康检查失败

报错内容：

ElasticsearchHealthCheck failed

原因：

Spring Boot Actuator默认使用http://localhost:9200进行健康检查
Elasticsearch部署在非localhost地址

解决方案：

关闭Elasticsearch健康检查（推荐）：

management:
  health:
    elasticsearch:
      enabled: false

配置正确的Elasticsearch地址：

spring:
  elasticsearch:
    rest:
      uris: http://your-elasticsearch-server:9200

六、Netty与Spring Data Elasticsearch冲突

1. Netty与Spring Data Elasticsearch的冲突

报错内容：

availableProcessors is already set to [8], rejecting [8]

原因：

Spring Data Elasticsearch与Webflux组件（基于Netty）发生冲突

解决方案：

@Configuration
public class EsConfig {
    @PostConstruct
    void init() {
        System.setProperty("es.set.netty.runtime.available.processors", "false");
    }
}

七、配置文件格式错误

1. 配置文件格式错误（YAML缩进问题）

报错内容：

Caused by: org.springframework.beans.factory.BeanCreationException: 
Error creating bean with name 'elasticsearchRestClient' defined in class path resource 
[org/springframework/boot/autoconfigure/data/elasticsearch/ElasticsearchRestClientAutoConfiguration.class]: 
Cannot create a ElasticsearchRestClient for the given configuration.

原因：

YAML文件缩进不正确或拼写错误

解决方案：
确保配置正确：

spring:
  elasticsearch:
    rest:
      uris: http://localhost:9200

八、其他常见问题

1. 字段映射冲突

报错内容：

ElasticsearchStatusException: MapperParsingException[failed to parse]

原因：

实体类字段类型与ES索引中已有字段类型不一致

解决方案：

删除旧索引（或重建）后重新启动应用
或通过_reindex API迁移数据

2. 查询结果为空

报错内容：

No documents found for query

原因：

分词器不匹配（如中文未使用IK分词器）
查询条件错误

解决方案：

通过Kibana检查索引映射：GET your_index/_mapping
确认分词器配置
打印生成的DSL查询语句验证条件

总结

确保Elasticsearch服务已启动：使用curl http://localhost:9200验证
正确配置连接地址：在application.yml中设置spring.elasticsearch.rest.uris
处理依赖冲突：排除Netty依赖，确保版本兼容
分离包路径：避免MyBatis和Elasticsearch Repository扫描冲突
关闭健康检查：如果不需要，设置management.health.elasticsearch.enabled=false
处理Netty冲突：添加EsConfig配置类
检查配置格式：确保YAML缩进正确，无拼写错误

关注公众号获取更多技术干货 !