Spring Boot配置Redis的核心路径就三步：引入starter依赖、写好连接参数、注入RedisTemplate直接开用。这篇文章不整虚的，专门把配置过程中容易踩的坑、连接失败的排查思路、参数该怎么定,一次性讲透。
springboot配置redis常见问题：依赖和版本坑
主版本不同，依赖坐标就有讲究
Spring Boot 2.x时代，引入spring-boot-starter-data-redis后，配置前缀是spring.redis，到了Spring Boot 3.x，包名和配置前缀全变了，前缀改成spring.data.redis，很多老项目升级后照抄旧配置，Redis根本没连上，报错报得不明不白，行业共识认为，配置不生效的问题九成都是前缀写错了。
另一个容易卡住的点是JDK版本，Spring Boot 3.x要求JDK17起步，如果你的开发环境还在用JDK8，强行升级会直接编译失败，选依赖之前，先确认自家项目的JDK版本和Spring Boot主版本，再决定Redis配置方案,顺序反了容易白折腾。
starter自带的lettuce够用吗
默认starter内置Lettuce客户端，这玩意儿线程安全、支持异步，多数场景直接够用，如果项目老代码用的是Jedis，需要手动排除lettuce再加jedis依赖，操作路径不复杂，但版本号得跟Spring Boot的BOM对齐,别自己随便填。
高并发场景下，lettuce默认不开启连接池，需要显式配置，不配的话，每次请求都新建连接,连接开销直接拖垮吞吐。
springboot整合redis连接参数写什么才对
先给一套标准的application.yml配置，Spring Boot 3.x版本直接抄：
spring:
data:
redis:
host: 127.0.0.1
port: 6379
password:
database: 0
timeout: 3000ms
lettuce:
pool:
max-active: 16
max-idle: 8
min-idle: 1
核心配置项逐个说明
- host：本地开发填127.0.0.1，服务器部署填内网IP，别填公网IP绕一圈,延迟高还容易触发安全策略。
- port：默认6379,改了端口记得同步。
- password：没设密码留空就行，设了密码不填或者填错，连接报错信息里会写
NOAUTH或者WRONGPASS,一眼就能认出来。 - database：默认连0号库，多业务模块共用实例时，可以分库隔离，但别超过16个库（redis默认16个库）。
- timeout：读超时建议3000ms上下，设成10秒会长期占用线程,接口慢到怀疑人生。
- lettuce.pool：上面的参数是基础配置，max-active控制最大连接数，一般按
服务并发数/单连接能承载的请求数估算,16这个值适合中小项目起步。
本地开发和服务器部署的配置差异
| 配置项 | 本地开发 | 服务器部署 |
|---|---|---|
| host | 0.0.1 | 内网IP |
| 密码 | 通常不设 | 必须设置复杂密码 |
| 连接池大小 | 默认即可 | 按压测结果调整 |
| 地域选择 | 无感 | 云Redis选同地域可用区，延迟低一个量级 |
序列化器不配好，读写全变乱码
RedisTemplate默认用的是JdkSerializationRedisSerializer，存入Redis的数据会带一串\xAC\xED\x00\x05t前缀，别人看到数据一脸懵，最省心的配法是key用StringRedisSerializer，value用GenericJackson2JsonRedisSerializer，既能读得懂,又能存复杂对象。
springboot配置redis连接失败怎么排查
这个场景遇到的频率相当高，连接失败的原因翻来覆去就那几类,按顺序排查能省不少时间。
三步定位问题
- 第一步：查端口通不通，在应用服务器上执行
telnet 目标IP 6379，如果连接不通，检查防火墙或者云服务器安全组有没有放行6379端口，有相当一部分连接失败案例，问题根本不在Spring配置上,而是网络策略限制了访问。 - 第二步：查Redis服务状态，执行
redis-cli -h IP -p 6379 ping，返回PONG才说明服务正常，如果在这里就挂了，去查Redis配置文件里的bind字段是不是只绑定了127.0.0.1,那样外部IP根本连不进来。 - 第三步：查应用配置，确认Spring Boot的配置文件里host、port、password和Redis实际设置一致，注意Spring Boot 3.x别再用
spring.redis前缀，不生效的配置不会报错,只会让你排查半天。
几个典型的翻车现场
- 密码带了空格或特殊字符没转义,报错信息永远在说认证失败。
- Docker部署时Redis容器和Spring Boot容器不在同一个网络，或者host填了容器名但没配自定义网络,还在傻傻查代码。
- 云Redis实例开启了ACL白名单，应用IP不在白名单里,连接直接被拒。
- 连接池的max-active设得极小，高并发瞬间打满,后续请求全部报超时。
验证配置好没好，直接读写一次最实在
配完了别光看启动日志没报错就完事，写个接口跑一次读写,数据能存取成功才算真正通了。
用StringRedisTemplate快速验证
@Autowired
private StringRedisTemplate redisTemplate;
@GetMapping("/redis/test")
public String testRedis() {
redisTemplate.opsForValue().set("site:name", "springboot-redis-guide");
return redisTemplate.opsForValue().get("site:name");
}
启动项目访问这个接口，浏览器输出刚才存的值，就说明整个链路已经通了，如果返回null,扒一遍序列化配置或者检查有没有多实例指向了不同的Redis库。
RedisTemplate和StringRedisTemplate到底怎么选（对比长尾词）
- StringRedisTemplate：只看字符串，存取简单，不需要额外配序列化器，拿来做缓存值、验证码、分布式锁这类场景最合适。
- RedisTemplate：泛型定义自由，存对象默认会走JDK序列化，不配JSON序列化器的话，存进去的是二进制乱码,业务方取数据时容易踩坑。
两个模板底层是同一套连接工厂，区别只在序列化策略上，大多数项目中，RedisTemplate配好JSON序列化器是标准姿势，而StringRedisTemplate适合快速上手、临时调试或者存简单字符串。
Q&A：springboot配置redis常见问题
springboot配置redis需要先安装redis服务吗
需要，Spring Boot不内置Redis服务端，配置只是客户端连接参数，本地开发建议用Docker跑一个Redis容器，生产环境直接买云Redis或者自建集群,配置里填对地址就行。
springboot配置redis用spring.redis还是spring.data.redis前缀
Spring Boot 2.x用spring.redis，Spring Boot 3.x必须用spring.data.redis，版本升级后照搬旧配置，Redis连接不会生效，控制台通常也没有明显报错，但所有操作都会超时，升级时全局搜一遍配置前缀批量替换即可,这个操作路径是升级老项目时最常忽略的一步。