如何解决Spring Boot集成Redis后出现的非法参数异常_排查Jedis与Lettuce的版本冲突-Redis-PHP中文网

这是jedis和lettuce同时加载导致的redisconnectionfactory类型冲突，引发illegalargumentexception或beancreationexception，常见于shiro-redis与spring-boot-starter-data-redis混合使用且未排除lettuce-core的场景。

如何解决spring boot集成redis后出现的非法参数异常_排查jedis与lettuce的版本冲突

直接结论：这不是参数写错了，而是Jedis和Lettuce在项目中被同时加载，导致RedisConnectionFactory类型不一致、方法签名错位，最终在运行时抛出IllegalArgumentException或BeanCreationException——常见于混合引入shiro-redis、spring-boot-starter-data-redis又手动加了jedis依赖的场景。

为什么`IllegalArgumentException`总在`RedisAutoConfiguration`里爆出来

Spring Boot 2.x+ 默认启用 Lettuce，但如果你显式引入了 jedis（比如为了适配老版 shiro-redis），而没排除 lettuce-core，就会触发以下链式问题：

Spring 容器尝试创建 RedisConnectionFactory bean 时，发现两个候选实现：LettuceConnectionFactory 和 JedisConnectionFactory
自动配置类 RedisAutoConfiguration 会按条件装配，但若两者都存在且未指定优先级，可能选错实现类，导致后续 RedisTemplate 初始化时传入错误类型的 factory
典型报错片段：java.lang.IllegalArgumentException: RedisConnectionFactory must not be null 或更隐蔽的 Failed to instantiate [org.springframework.data.redis.core.RedisTemplate]，根源其实是构造器接收了不兼容的 factory 实例

如何确认是 Jedis 和 Lettuce 同时存在

执行 mvn dependency:tree -Dincludes=io.lettuce:lettuce-core,redis.clients:jedis，检查输出中是否同时出现两者的路径。重点看：

Spring Boot Actuator Analyzer

分析Spring Boot Actuator端点的安全性、健康检查、指标暴露及生产配置——审计信息、健康状态和自定义端点。

下载

是否存在 io.lettuce:lettuce-core（哪怕只是被其他 starter 传递引入）
是否存在 redis.clients:jedis（尤其注意是否来自 shiro-redis、redis-spring-boot-starter 等非官方包）
是否在 application.yml 中写了 spring.redis.jedis 配置项，但实际运行时却加载了 Lettuce 连接工厂（此时配置无效，还会埋下超时隐患）

彻底排除冲突的三步操作

不靠“试错式排除”，用确定性方式收口：

在 spring-boot-starter-data-redis 依赖中，**必须显式 <exclusion></exclusion> 掉 io.lettuce:lettuce-core**，哪怕你没手动加它——因为 Spring Boot parent 默认带了
**只引入一个客户端实现**：如果要用 Jedis，就只加 redis.clients:jedis；如果要用 Lettuce，就确保项目里没有任何 jedis 相关依赖（包括 shiro-redis 这种老包）
检查配置项前缀是否匹配所选客户端：
– 用 Jedis 时，配置必须以 spring.redis.jedis. 开头（如 spring.redis.jedis.pool.max-active）
– 用 Lettuce 时，配置必须以 spring.redis.lettuce. 开头（如 spring.redis.lettuce.pool.max-active）
混用会导致连接池参数被忽略，间接引发超时或空连接异常

最容易被忽略的兼容性雷区

版本不是“能跑就行”，而是“对得上号”：

spring-boot-starter-data-redis 2.7.x 对应 spring-data-redis 2.7.x + lettuce-core 6.1.x 或 jedis 4.1.x；强行塞 jedis 3.9.0 会因方法签名变更（如 JedisPoolConfig.setMaxWaitMillis() → setMaxWait(Duration)）触发 NoSuchMethodError，表面像参数错，实为二进制不兼容
Spring Boot 3.x（Jakarta EE）下，jedis 需要至少 4.4.0+ 才支持 Jakarta 命名空间，否则在初始化时抛 NoClassDefFoundError: javax/net/ssl/SSLContext 类似错误
云环境（如阿里云沙箱、腾讯云 TKE）中，Lettuce 的 Netty 线程模型有时与平台网络栈不兼容，表现为偶发 RedisCommandTimeoutException，此时切 Jedis 是有效绕过手段，但必须同步清理所有 lettuce 残留（包括 io.netty 版本冲突）