大家好，我是 lazy，一名大二科班学生

适合 Java 后端初学者的 Redis 入门配置与排错教程

摘要

在 Spring Boot 后端项目中，Redis 经常用来做缓存、验证码、登录 token、热点数据存储等功能。很多初学者第一次连接 Redis 时，会遇到 Redis 服务没有启动、端口写错、密码配置错误、依赖缺失、RedisTemplate 注入失败、序列化后数据看起来乱码等问题。本文将从环境准备、依赖配置、application.yml 配置、测试接口编写和常见错误排查几个方面，总结 Spring Boot 项目连接 Redis 的完整入门流程。

一、前言

在学习 Java 后端开发时，很多同学会先接触 MySQL，再接触 Redis。MySQL 主要用于持久化存储数据，而 Redis 更常用于缓存和临时数据存储。比如登录验证码、短信验证码、用户 token、商品热点数据、访问次数统计等，都可以使用 Redis 来实现。

但是在 Spring Boot 项目中连接 Redis 时，新手经常会遇到一些问题：

• 项目启动时报 Unable to connect to Redis server

• Redis 端口 6379 连接失败

• Redis 设置了密码但项目没有配置密码

• pom.xml 依赖爆红，找不到 RedisTemplate

• 数据能存进去，但是在 Redis 中看起来像乱码

• Spring Boot 2.x 和 3.x 的配置前缀混用

• Windows 上不知道怎么启动 Redis 服务

这些问题看起来比较杂，但其实排查思路是固定的：先确认 Redis 服务是否正常，再确认 Spring Boot 配置是否正确，最后再检查代码和序列化方式。

二、Redis 在 Spring Boot 项目中一般用来做什么

Redis 是一个基于内存的数据存储工具，读写速度比较快，所以在后端项目中经常用来提升访问效率。Spring Data Redis 为 Spring 应用提供了访问 Redis 的统一方式，包括 RedisTemplate、StringRedisTemplate 等常用工具类。

• 缓存热点数据：比如商品详情、用户信息、分类列表等

• 保存验证码：比如图形验证码、短信验证码、邮箱验证码

• 保存登录状态：比如登录 token、用户临时会话信息

• 计数统计：比如访问次数、点赞数、限流计数

• 排行榜或简单队列：可以利用 Redis 的数据结构实现一些轻量功能

对于初学者来说，不建议一开始就写很复杂的缓存方案。可以先从最简单的字符串读写开始，先保证 Spring Boot 项目能正常连接 Redis。

三、准备环境：项目结构和 Redis 服务

一个基础的 Spring Boot + Redis 项目，通常会包含启动类、controller、application.yml 和 pom.xml。初学者要先确认项目结构完整，再去配置 Redis。

图1 Spring Boot 连接 Redis 的项目结构和配置位置

这里重点关注两个文件：pom.xml 用来添加 Redis 依赖，application.yml 用来配置 Redis 的地址、端口、密码和数据库编号。

四、Windows 下如何启动 Redis

Redis 官方主要面向 Linux 环境，Windows 本机开发时常见做法是使用 Docker Desktop 或 WSL 启动 Redis。对于新手来说，如果电脑已经安装 Docker，直接用 docker run 启动一个本地 Redis 会比较方便。

图2 Windows PowerShell 中使用 Docker 启动 Redis 示例

如果命令执行后能看到 PONG，说明 Redis 服务已经启动并且能够正常连接。默认端口一般是 6379，后面 Spring Boot 配置里也要写这个端口。

五、添加 Redis 依赖

Spring Boot 项目连接 Redis，首先需要在 pom.xml 中添加 Redis Starter 依赖。对于 Maven 项目，一般使用 spring-boot-starter-data-redis。

图3 在 pom.xml 中添加 Redis Starter 依赖

添加依赖后，记得在 IDEA 右侧 Maven 面板点击刷新按钮，让 Maven 重新加载依赖。如果 RedisTemplate 或 StringRedisTemplate 爆红，很多时候就是 Maven 依赖没有下载成功。

六、配置 application.yml

依赖添加完成后，需要在 application.yml 中配置 Redis 的连接信息。最常见的配置包括 host、port、database、password 和 timeout。

图4 application.yml 中配置 Redis 连接信息

如果 Redis 没有设置密码，password 可以先留空或不写。如果 Redis 设置了密码，必须把密码配置进去，否则运行时可能出现 NOAUTH Authentication required。

需要注意的是，Spring Boot 3.x 中常见配置前缀是 spring.data.redis；有些老项目可能使用 spring.redis。复制配置时一定要结合自己的 Spring Boot 版本，不要混着写。

七、编写一个简单的 Redis 测试接口

新手测试 Redis 是否连接成功，不需要一上来就写复杂业务。可以先写两个简单接口：一个把 key 和 value 存入 Redis，另一个根据 key 读取 value。

图5 使用 StringRedisTemplate 编写简单的 Redis 测试接口

这里使用的是 StringRedisTemplate。它更适合新手入门，因为 key 和 value 都按照字符串处理，数据在 Redis 中也更容易看懂。如果直接使用 RedisTemplate，可能会遇到序列化导致的数据不直观问题。

八、测试 Redis 是否连接成功

项目启动后，可以先访问 set 接口保存一个值，再访问 get 接口读取这个值。如果能正常取出，说明 Spring Boot 已经成功连接 Redis。

图6 通过浏览器或接口工具测试 Redis 读写结果

如果 set 接口返回保存成功，get 接口能拿到刚才保存的内容，说明配置和代码都基本没有问题。后续就可以把 Redis 用到验证码、token、缓存等业务场景中。

九、常见错误一：Unable to connect to Redis server

这是最常见的 Redis 连接错误。它一般表示 Spring Boot 项目启动了，但是连接不上 Redis 服务。

图7 Redis 没启动或端口错误时的常见控制台报错

常见原因包括 Redis 服务没有启动、端口号写错、Docker 容器没有运行、防火墙拦截、连接地址写错等。

• 先确认 Redis 是否启动成功

• 确认端口是否是 6379

• 如果使用 Docker，检查容器是否还在运行

• 确认 application.yml 中 host 和 port 是否写对

• Windows 上可以用 PowerShell 或 Docker Desktop 查看 Redis 状态

十、常见错误二：NOAUTH Authentication required

如果 Redis 设置了密码，但 Spring Boot 配置中没有填写密码，就可能出现 NOAUTH Authentication required。

图8 Redis 设置密码但项目未配置密码时的报错

解决方法是检查 Redis 是否设置了 requirepass，然后在 application.yml 中补上 password。还要注意密码中如果包含特殊字符，复制时不要多空格。

十一、常见错误三：依赖缺失或 RedisTemplate 注入失败

如果代码中 StringRedisTemplate 或 RedisTemplate 爆红，或者运行时提示找不到 Bean，首先要检查 pom.xml 中是否真的添加了 spring-boot-starter-data-redis。

• 检查 pom.xml 是否添加 Redis Starter

• 刷新 Maven 依赖

• 检查 IDEA 中 import 是否正常

• 确认没有把 dependency 写错位置

• 如果使用多模块项目，确认依赖加在当前启动模块中

初学者最容易犯的错误是：复制了 RedisController 代码，但是 pom.xml 没有加依赖，或者加了依赖但 Maven 没刷新。

十二、常见错误四：Spring Boot 版本配置前缀写错

有些同学从网上复制配置时，会发现同样是 Redis，有的文章写 spring.redis，有的写 spring.data.redis。这和 Spring Boot 版本有关。

图9 Spring Boot 2.x 和 3.x 中 Redis 配置前缀容易混用

如果你的项目是较新的 Spring Boot 3.x，建议优先使用 spring.data.redis 这种写法。如果是老师发的老项目或旧版本项目，可以按照项目原有配置风格来写。

十三、常见错误五：Redis 中的数据看起来像乱码

有时候代码能正常运行，数据也能存进 Redis，但是用 redis-cli 查看时发现 key 或 value 看起来像乱码。这通常不是 Redis 坏了，而是 RedisTemplate 默认序列化方式导致的。

图10 RedisTemplate 默认序列化导致数据看起来不直观

对于初学者来说，如果只是存字符串、验证码、token，建议优先使用 StringRedisTemplate。等熟悉以后，再学习如何配置 JSON 序列化。

十四、常见错误六：远程 Redis 连接失败

如果 Redis 部署在服务器上，而 Spring Boot 项目在本地运行，除了 host 和 port，还要考虑服务器防火墙、Redis 绑定地址、密码、云服务器安全组等问题。

• 确认服务器 6379 端口是否开放

• 确认 Redis 是否允许远程访问

• 确认服务器防火墙和安全组配置

• 确认密码是否正确

• 不要把没有密码的 Redis 直接暴露到公网

需要特别注意安全问题：Redis 不建议在没有密码和安全限制的情况下直接暴露到公网。学习阶段优先使用本地 Redis。

十五、推荐排查顺序

如果 Spring Boot 连接 Redis 失败，可以按照下面顺序排查。不要一上来就乱改代码，先确认服务，再确认配置，最后看代码。

图11 Spring Boot 连接 Redis 失败的推荐排查流程

十六、常见报错和解决方法对照表

报错或现象	常见原因	解决方法
Unable to connect to Redis server	Redis 没启动或端口错误	启动 Redis，检查 host 和 port
Connection refused	端口没有服务监听	检查 Docker/Redis 服务状态
NOAUTH Authentication required	Redis 有密码但项目没配置	在 application.yml 中配置 password
Cannot resolve symbol RedisTemplate	Maven 依赖没加载	添加 Redis Starter 并刷新 Maven
RedisTemplate 注入失败	依赖缺失或配置异常	检查 starter 和 Spring Boot 自动配置
Redis 中数据像乱码	序列化方式不直观	新手优先使用 StringRedisTemplate
连接远程 Redis 失败	防火墙、bind、安全组问题	检查服务器端口和 Redis 配置
配置不生效	Spring Boot 版本前缀混用	根据版本选择 spring.data.redis 或旧配置

十七、总结

Spring Boot 连接 Redis 并不复杂，核心步骤就是：启动 Redis 服务、添加 Redis 依赖、配置 application.yml、编写简单接口进行读写测试。

对于初学者来说，最重要的是先跑通最简单的 set 和 get，不要一开始就纠结复杂缓存方案。等能正常连接之后，再逐步学习过期时间、JSON 序列化、缓存注解、登录 token、验证码存储等内容。

遇到连接失败时，可以优先检查 Redis 是否启动、端口是否正确、密码是否匹配、Maven 依赖是否完整。只要按照本文的顺序排查，大部分 Spring Boot 连接 Redis 的问题都可以解决。