必须先启动 redis 服务再运行 go 程序；macos 用 brew install redis + redis-server，ubuntu 用 apt 安装并 systemctl 启动，windows 推荐 wsl2；go 客户端首选 github.com/redis/go-redis/v9，addr 为必填项，需调用 ping 验证连通性。
必须先让 Redis 服务跑起来，再让 Go 连上它；缺一不可，且顺序不能颠倒。
Redis 服务怎么装、怎么起
本地开发最省事的方式是直接用包管理器安装并启动服务，不建议手动下载 ZIP 或编译源码——容易版本错配、权限异常、端口冲突。
-
macOS：执行
brew install redis，然后redis-server启动（默认监听localhost:6379） -
Ubuntu/Debian：运行
sudo apt update && sudo apt install redis-server，再用sudo systemctl start redis-server - Windows：强烈推荐 WSL2 + Ubuntu 环境，避免 Windows 原生版 Redis 的兼容性问题（如 TLS、信号处理异常）
- 验证是否正常：
redis-cli ping应返回PONG；若报Could not connect to Redis at 127.0.0.1:6379，说明服务没起来或 bind 配置不对
Go 客户端库选哪个、怎么装
目前主流且维护活跃的是 github.com/redis/go-redis/v9（官方背书），不是旧版 go-redis/redis/v8 或更老的 gopkg.in/redis.v4。v9 是 2023 年后新项目首选，API 更一致、context 支持更彻底、错误类型更明确。
- 安装命令：
go get github.com/redis/go-redis/v9 - 导入方式：
import "github.com/redis/go-redis/v9"（注意路径里是redis/go-redis，不是go-redis/redis） - 别踩坑：
v9不兼容v8的redis.Nil判断方式——v9 用redis.Error类型做断言，不是字符串比对 - 如果项目已用 v8，升级前务必检查
ctx传参、Result()调用、以及Err()是否被正确链式调用
连接参数怎么配、哪些必须填
redis.NewClient 的 *redis.Options 结构体里，只有 Addr 是硬性必需项；其他如 Password、DB、Username（Redis 6+ ACL）、TLSConfig 全部按需填写，留空即走默认值。
立即学习“go语言免费学习笔记（深入）”；
-
Addr：格式为"host:port"，例如"localhost:6379"或"10.0.1.5:6380"；不要加redis://前缀（那是 URL 解析逻辑，v9 不认） -
Password：仅当 Redis 配置了requirepass或启用 ACL 时才填；填错会报AUTH failed错误 -
DB：默认是0，但生产环境建议显式指定，避免切换数据库时误操作其他业务库 -
Username：Redis 6+ 支持多用户，ACL 用户需同时设Username和Password，否则认证失败 - 超时建议补上：
DialTimeout、ReadTimeout、WriteTimeout，防止网络卡死阻塞整个 goroutine
连通性测试怎么做、常见失败原因
别跳过 rdb.Ping(ctx).Result()，这是唯一能确认“网络通、认证过、服务活”的三合一检测点。只测 net.Dial 没用，因为 Redis 协议握手和 AUTH 阶段可能失败。
- 典型失败信息及原因：
-
dial tcp [::1]:6379: connect: connection refused→ Redis 没启动，或bind配置为127.0.0.1但客户端连的是::1（IPv6）；解决：改redis.conf中bind 127.0.0.1 ::1或统一用 IPv4 -
redis: nil或NOAUTH Authentication required→ 密码没填或填错；注意 v9 的Password字段不能为nil，空密码也要写"" -
context deadline exceeded→ 网络延迟高或超时设太短；建议初调设5 * time.Second - 测试通过后，立刻用
rdb.Set(ctx, "test", "ok", 10*time.Second).Err()和rdb.Get(ctx, "test").Result()验证读写通路
配置本身很简单，难的是环境隔离和错误归因——本地跑通不等于线上可用，Docker 容器网络、K8s Service DNS、云 Redis 的白名单和加密开关，每个环节都可能悄无声息地切断连接。
