延迟任务发不进去且报redis: nil错误，根本原因是Redis连接未建立成功就调用client.Enqueue；必须初始化asynq.Client后主动执行client.RedisClient.Ping()校验连通性，避免因连接失败导致任务静默丢失。
延迟任务发不进去，asynq.Client 报 redis: nil 错误
这不是 Asynq 本身的问题，而是 Redis 连接没建好就急着发任务。Asynq 的 asynq.Client 依赖底层 redis.Conn，如果传入的 redis.UniversalClient 没成功 ping 通，client.Enqueue 会直接 panic 或返回 redis: nil 错误。
- 务必在初始化
asynq.Client后，主动调用client.RedisClient.Ping(context.Background()).Err()校验连接 - 不要复用 web server 启动前未校验的 Redis client —— 微服务里常见错误是把 Redis client 和 Asynq client 都塞进全局变量，但启动顺序没控制好
- 延迟任务要用
asynq.Task{}+asynq.QueueOpt{Delay: 5 * time.Minute}，不是靠time.Sleep或外部定时器“等时间到了再发”
asynq.ServeMux 注册 handler 时类型不匹配导致任务静默失败
Asynq 要求每个 handler 必须实现 asynq.HandlerFunc 类型（即 func(context.Context, *asynq.Task) error），但微服务中常因结构体方法绑定或闭包捕获出错，导致注册后任务进队列却无日志、无执行。
- 避免写成
mux.HandleFunc("send_email", s.sendEmail)，其中s.sendEmail是带 receiver 的方法 —— Go 方法值不是函数，类型不匹配 - 正确写法是显式转换：
mux.HandleFunc("send_email", func(ctx context.Context, t *asynq.Task) error { return s.sendEmail(ctx, t) }) - handler 内部别直接用
log.Printf，优先用asynq.LogEntry（通过asynq.GetLogger(ctx)获取），否则在重试、失败归档时日志上下文丢失
微服务部署时多个实例争抢同一任务，或重复消费
Asynq 默认用 Redis List + BRPOPLPUSH 实现队列，天然支持多 worker 并发消费；但延迟任务依赖 ZSET（按 scheduled_at 排序），若多个服务实例共用同一 asynq:{queue} 前缀且没做隔离，会导致任务被不同服务误认、重复执行。
Redis Skill - 高性能缓存管理
下载
Redis 缓存和数据结构管理技能。通过自然语言操作 Redis，支持 String、Hash、List、Set、ZSet、Stream 等数据结构操作。当用户提到 Redis、缓存、消息队列、会话存储时使用此技能。
- 每个微服务必须配置独立的
asynq.Serverredis.Namespace，比如redis.Namespace = "svc-order:"，避免和其他服务混用 key 空间 - 延迟任务的
QueueName不要硬编码为"default"，建议按业务域命名，如"order_delay"，并在asynq.Server初始化时显式指定Queues: map[string]int{"order_delay": 10} - 任务失败后默认重试 25 次，对幂等性差的操作（如扣款）很危险 —— 必须在 handler 开头校验业务唯一 ID（如
t.Payload里的order_id+event_id），或用 Redis SETNX 做简单去重
本地开发调试时 asynq.RedisClient 连不上 Docker 中的 Redis
Go 进程跑在宿主机，Redis 在 Docker 容器里，默认用 localhost:6379 会连到宿主机的 Redis（通常没有），而不是容器。
- Docker Compose 场景下，Go 服务应连
redis:6379（服务名），而非localhost:6379 - 纯 Docker run 场景，加
--network host或用host.docker.internal（Mac/Windows）；Linux 需手动添加--add-host=host.docker.internal:host-gateway - 延迟任务在本地调试时，别设太长 delay（如 1h），建议先用
time.Now().Add(5 * time.Second)测试路径是否通畅
延迟队列真正难的不是发任务，而是确保 Redis 连接生命周期、任务唯一性、跨服务命名空间这三件事不出岔子 —— 尤其当多个微服务共享一套 Redis 时，namespace 和 queue name 的粒度控制稍一松懈，问题就会藏到上线后才爆发。
