Redis 在 Spring Boot 项目里几乎是缓存与会话存储的首选，但同一份配置在不同 Spring Boot 版本下表现可能完全不一样：有的版本能直接连上，有的版本启动就报连接工厂缺失，有的版本出现 NOAUTH 认证错误。比较常见的分水岭是 Spring Boot 1.x、2.x、3.x 三个阶段的自动装配策略变化。下面先把不同版本下的配置前缀和默认客户端差异讲清楚。
配置前缀与默认客户端的变化
Spring Boot 1.x 时代，Redis 的自动配置非常直白，使用 spring.redis.host、spring.redis.port、spring.redis.password 就能完成基础连接。当时默认底层客户端是 Jedis，连接池配置集中在 spring.redis.pool 节点下，例如 spring.redis.pool.max-active、spring.redis.pool.max-idle。这种方式对刚接触缓存的开发者比较友好，因为参数名和 Jedis 本身的连接池概念一一对应。
从 Spring Boot 2.x 开始，官方将默认 Redis 客户端从 Jedis 切换为 Lettuce，原因是 Lettuce 基于 Netty，天然适合异步和响应式场景，并且线程安全表现更好。这个切换带来两个配置层面的变化：一是连接池不再只有一个通用 pool 节点，而是分成了 spring.redis.lettuce.pool 与 spring.redis.jedis.pool 两套；二是不少版本仍然兼容 spring.redis.* 前缀，但后期版本逐渐出现 spring.data.redis.* 与旧前缀混用的情况。实际开发中，2.x 中期的项目使用 spring.redis.host 通常能正常工作，但如果项目依赖了较新的 Spring Data Redis，建议提前了解 spring.data.redis 前缀，避免升级时属性被忽略。
到 Spring Boot 3.x 之后，spring.data.redis.* 已经成为标准前缀，spring.redis.* 在多数自动装配场景下不再生效。如果你的项目从 2.x 升级过来，只改动版本号而不调整 YAML 或 properties 文件，就很容易出现连接不上本地默认端口、密码未生效等奇怪问题。一个典型错误是配置了 spring.redis.password，但 3.x 根本不会读取该键，最终 Redis 服务端要求认证时抛出 NOAUTH Authentication required。因此版本升级时，第一步应该是检查配置前缀是否已经全部迁移。
连接池与依赖的版本差异
连接池配置是另一个容易踩坑的地方。Spring Boot 1.x 中只要引入 spring-boot-starter-data-redis，Jedis 连接池基本可以直接使用，因为 Jedis 自带连接池能力。但到了 2.x 和 3.x，默认客户端换成 Lettuce 后，连接池需要额外依赖 org.apache.commons:commons-pool2 才能生效。很多项目升级后启动会看到 ClassNotFoundException: org.apache.commons.pool2.impl.GenericObjectPoolConfig，原因就是缺少这个依赖。Maven 用户可以添加如下依赖：
<dependency>
<groupId>org.apache.commons</groupId>
<artifactId>commons-pool2</artifactId>
</dependency>
如果使用 Gradle，可以写为 implementation 'org.apache.commons:commons-pool2'。添加依赖后，连接池参数才能真正控制 Lettuce 的 GenericObjectPool 行为。需要特别注意的是，连接池参数在不同版本中的默认值也会变化。旧版 Jedis 的 max-active 默认值是 8，max-idle 默认值是 8，而 Lettuce 连接池默认不会无限等待，可能在高并发下更快抛出无法获取连接的异常。建议在 2.x、3.x 中显式配置：
spring:
data:
redis:
host: 127.0.0.1
port: 6379
password: yourpassword
timeout: 3000ms
lettuce:
pool:
max-active: 16
max-idle: 8
min-idle: 2
max-wait: 2000ms
这里使用了 spring.data.redis 前缀，适合 Spring Boot 3.x。如果你的项目还在 2.x 并继续使用 spring.redis，只需把 data 层去掉即可。还有一个容易忽略的点是 timeout 和连接池的 max-wait 含义不同：前者是 Redis 命令执行的超时时间，后者是获取连接时最多等待多久。线上偶发 Cannot get Jedis connection 或 Cannot get Lettuce connection 时，先区分是命令执行慢还是连接池已耗尽，不要盲目加大 timeout。
序列化与 RedisTemplate 的兼容配置
不同版本下 RedisTemplate 的默认序列化方式没有本质变化，仍然使用 JDK 序列化，导致存储到 Redis 里的 key 和 value 常常是一串转义字符。要在控制台或别的语言中查看数据，就必须改序列化。常见做法是使用 StringRedisTemplate，或者自定义 RedisTemplate<String, Object> 并设置 Jackson 序列化器。下面是一个在 Spring Boot 2.x 和 3.x 都能用的配置类：
@Configuration
public class RedisConfig {
@Bean
public RedisTemplate<String, Object> redisTemplate(RedisConnectionFactory factory) {
RedisTemplate<String, Object> template = new RedisTemplate<>();
template.setConnectionFactory(factory);
GenericJackson2JsonRedisSerializer serializer = new GenericJackson2JsonRedisSerializer();
StringRedisSerializer stringSerializer = new StringRedisSerializer();
template.setKeySerializer(stringSerializer);
template.setHashKeySerializer(stringSerializer);
template.setValueSerializer(serializer);
template.setHashValueSerializer(serializer);
template.afterPropertiesSet();
return template;
}
}
在 3.x 下，这个配置仍然有效，但需要确认 Jackson 依赖存在。Spring Boot 3.x 通常已经通过 spring-boot-starter-web 或 spring-boot-starter-json 引入 Jackson，如果项目没有这些依赖，GenericJackson2JsonRedisSerializer 会报类型找不到。另外，如果使用了 Spring Session 或缓存注解 @Cacheable，还需要分别配置 RedisCacheManager 和 Session 的序列化策略，避免业务对象反序列化成 LinkedHashMap 后出现类型转换异常。
从 Spring Boot 2.x 起，响应式编程也成为一个重要场景。使用 Lettuce 时，可以注入 ReactiveRedisTemplate，它的序列化配置方式与阻塞式模板类似，但需要注意参数类型是 ReactiveRedisConnectionFactory。如果项目同时启用了响应式 Web 和传统 MVC，连接工厂会自动选择 Lettuce，不需要额外切换。对于 Jedis 用户，响应式支持并不完善，因此 3.x 项目建议保持默认 Lettuce，避免为了熟悉 Jedis 而引入功能限制。
常见报错与使用注意事项
不同版本切换时最常见的问题是 NOAUTH Authentication required。这通常不是密码错误，而是密码配置项压根没有被读取。检查时先确认当前 Spring Boot 版本对应的前缀，再看是否把密码写在 spring.redis.password 而应用读取的是 spring.data.redis.password。另一个高频报错是连接超时：RedisConnectionFailureException: Unable to connect to Redis。出现这种错误时，先检查 host 和 port 是否被其他配置覆盖，再检查云服务器安全组或 Redis 配置中的 bind 设置。本地 Windows 环境使用 Redis 时，如果地址写成 localhost，可能解析到 IPv6 的 ::1，而 Redis 只监听 IPv4 的 127.0.0.1，这时会报连接异常。直接写 127.0.0.1 可以绕开这个解析差异。
集群和哨兵配置也要注意版本格式。Spring Boot 1.x 中通常用 spring.redis.sentinel.nodes 配置哨兵列表，2.x、3.x 中则迁移到 spring.data.redis.sentinel.master 和 spring.data.redis.sentinel.nodes。集群模式除了 cluster.nodes 外，默认还会开启拓扑刷新和重定向，部分版本需要手动关闭或调整。多数据源场景下不要只依赖自动配置，建议自己声明 RedisConnectionFactory 和 RedisTemplate 的 Bean，并为每个 Bean 指定不同名称，避免因主从、缓存、Session 共用一套连接导致相互影响。
最后是版本升级时的验证思路。先把 application 配置文件中的 Redis 相关项全部迁移到当前版本的前缀，再启动应用查看是否有 RedisConnectionFactory 自动装配成功；然后写一个简单的 CommandLineRunner 执行 ping 命令，确认连接和认证正常；最后写入一个带序列化的对象，再从控制台读出来，验证 key 和 value 是否按预期存储。这样分三步排查，能把大部分版本差异引起的问题快速定位。
总体来看，Spring Boot 不同版本下的 Redis 配置差异主要集中在前缀迁移、默认客户端切换、连接池依赖和序列化兼容四个方面。只要在升级时优先检查这些点，并显式配置连接池和 RedisTemplate，基本可以避免多数连接异常和数据不可读问题。
Spring BootRedis配置版本差异修改时间：2026-10-03 21:52:02