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

<dependency>
    <groupId>org.apache.rocketmq</groupId>
    <artifactId>rocketmq-spring-boot-starter</artifactId>
    <version>2.0.4</version>
    <!-- 排除冲突的依赖 -->
    <exclusions>
        <exclusion>
            <groupId>com.google.guava</groupId>
            <artifactId>guava</artifactId>
        </exclusion>
    </exclusions>
</dependency>

四、自动装配配置缺失

1. RocketMQTemplate 无法自动注入

报错内容：

Field rocketMQTemplate in com.sks.crm.service.RocketMQProducerService required a bean of type 'org.apache.rocketmq.spring.core.RocketMQTemplate' that could not be found.

原因： SpringBoot 3.0+ 已废弃 spring.factories 自动装配机制。

解决方案： 在 resources 下创建 META-INF 文件夹，然后在 META-INF 下创建 org.springframework.boot.autoconfigure.AutoConfiguration.imports 文件，并添加：

org.apache.rocketmq.spring.autoconfigure.RocketMQAutoConfiguration

五、RocketMQ 服务配置问题

1. NameServer 地址配置错误

报错内容：

org.apache.rocketmq.client.exception.MQClientException: No route info of topic: test-topic, please make sure you have created the topic first.

原因： RocketMQ 配置的 NameServer 地址不正确。

解决方案： 检查配置文件中 rocketmq.name-server 是否正确，确保 NameServer 已启动且可访问。

2. 磁盘空间不足

报错内容：

org.apache.rocketmq.client.exception.MQBrokerException: CODE: 14 DESC: service not available now. It may be caused by one of the following reasons: the broker's disk is full [CL:0.92 CQ:0.92 INDEX:0.92], messages are put to the slave, message store has been shut down, etc. BROKER:169.254.87.77:10911

原因： RocketMQ Broker 所在服务器磁盘空间不足。

解决方案：

1. 清理磁盘空间
2. 修改 runbroker.cmd 文件，增加：

set "JAVA_OPT=%JAVA_OPT% -server -Xms512m -Xmx512m -Xmn128m -Drocketmq.broker.diskSpaceWarningLevelRatio=0.99"

六、消费者组配置问题

1. 消费者组已存在

报错内容：

Caused by: org.apache.rocketmq.client.exception.MQClientException: The consumer group[my-consumer] has been created before, specify another name please

原因： 同一个消费者组名已在 RocketMQ 中创建，重复使用。

解决方案： 确保每个消费者组名是唯一的，不要重复使用。

七、配置文件格式问题

1. 配置文件格式错误

报错内容：

Caused by: org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'rocketMQTemplate' defined in class path resource [org/apache/rocketmq/spring/autoconfigure/RocketMQAutoConfiguration.class]: Instantiation of bean failed; nested exception is org.springframework.beans.BeanInstantiationException: Failed to instantiate [org.apache.rocketmq.spring.core.RocketMQTemplate]: Constructor threw exception; nested exception is java.lang.IllegalArgumentException: rocketmq.name-server is required.

原因： 配置文件中缺少必要的 RocketMQ 配置项。

解决方案： 确保配置文件包含必要的 RocketMQ 配置：

rocketmq:
  name-server: 127.0.0.1:9876
  producer:
    group: my-group
  consumer:
    group: my-consumer

八、ACL 认证配置问题

1. ACL 认证配置缺失

报错内容：

org.apache.rocketmq.client.exception.MQClientException: Access denied, the topic 'test-topic' is not allowed to be accessed by the client

原因： RocketMQ 开启 ACL 认证，但客户端未配置 AccessKey 和 SecretKey。

解决方案： 在配置文件中添加：

rocketmq:
  producer:
    access-key: AK
    secret-key: SK

或在消费者注解中指定：

@RocketMQMessageListener(topic = "test-topic", consumerGroup = "my-consumer", accessKey = "AK", secretKey = "SK")