Node-redis v4.1.0 get方法挂起致Express应用无响应

云上老周

2026-8-28

问题根因

redis.get()执行后无限挂起、开启legacyMode后命令无响应，本质是客户端配置和初始化逻辑存在三个明显问题：

未配置合理的重连策略，也未监听完整的连接状态事件。Redis v4.x客户端默认在网络闪断、服务端主动回收空闲连接后会进入自动重连流程，重连期间所有提交的命令会进入等待队列，既不执行也不抛错，直接表现为代码卡在await语句无限挂起。
客户端初始化时没有等待连接就绪就直接导出给业务层使用。服务启动后如果Redis连接尚未完成、或者首次连接失败进入重连循环，业务层提前发起的Redis调用会一直卡在队列里无法执行。
错误配置和错误事件绑定：legacyMode是为了兼容v3版本的回调式API设计的，全量使用async/await写法时不需要开启，开启后反而会出现命令调度异常；另外SIGINT是进程级系统事件，不属于Redis客户端实例的事件，原有监听逻辑永远不会触发，进程退出时连接无法正常关闭，会在服务端残留无效连接，后续新连接很容易被服务端拒绝。

修复方案

按以下步骤调整即可彻底解决问题：

修正Redis客户端初始化逻辑，增加重连规则、超时配置，修正事件监听逻辑：

import { createClient } from "redis";
import dotenv from "dotenv";

dotenv.config();

const redisClient = createClient({
  url: `redis://:${process.env.REDIS_PASSWORD}@${process.env.REDIS_HOST}:${process.env.REDIS_PORT}`,
  socket: {
    // 配置重连策略，避免无限制排队命令
    reconnectStrategy: (retries) => {
      if (retries > 10) {
        return new Error("Redis重连次数超限，终止连接");
      }
      return Math.min(retries * 100, 3000); // 重连间隔递增，最长3秒
    },
    connectTimeout: 10000, // 10秒连接超时直接抛错
  }
  // 无旧版回调兼容需求时，不要开启legacyMode
});

// 绑定完整的连接状态事件
redisClient.on("connect", () => console.log("Redis连接建立中"));
redisClient.on("ready", () => console.log("Redis连接就绪，可正常执行命令"));
redisClient.on("error", (err) => {
  console.log("Redis连接出错: ", err.message);
});
redisClient.on("reconnecting", () => console.log("Redis连接断开，尝试重连中"));
redisClient.on("end", () => console.log("Redis连接已关闭"));

// 正确监听进程退出事件，优雅关闭连接
process.on("SIGINT", () => {
  redisClient.quit().then(() => process.exit(0));
});

// 导出初始化方法，确保连接就绪后再给业务层使用
export const initRedis = async () => {
  await redisClient.connect();
  return redisClient;
}

export { redisClient };

调整Express服务启动流程，必须等Redis连接就绪后再监听端口，避免业务请求提前打到未就绪的客户端：

// 服务入口文件
import express from 'express';
import { initRedis } from './redis配置文件路径.js';

const app = express();
const PORT = process.env.PORT || 3000;

const startServer = async () => {
  try {
    await initRedis();
    // 此处注册中间件、路由逻辑
    app.listen(PORT, () => {
      console.log(`服务启动成功，监听端口${PORT}`);
    })
  } catch (err) {
    console.error("服务启动失败: ", err);
    process.exit(1);
  }
}

startServer();

给缓存方法增加状态判断和超时保护，极端场景下避免请求无限挂起：

// 命令超时包装
const withTimeout = (promise, timeoutMs = 3000) => {
  return Promise.race([
    promise,
    new Promise((_, reject) => 
      setTimeout(() => reject(new Error("Redis命令执行超时")), timeoutMs)
    )
  ])
}

// 调整缓存读取方法
static async getCacheData(key) {
  try {
    console.log("Get redis key: ", key);
    // 客户端未就绪时直接跳过缓存，走下游查询逻辑
    if (!redisClient.isReady) {
      console.log("Redis未就绪，跳过缓存读取");
      return null;
    }
    const redisData = await withTimeout(redisClient.get(key));
    console.log("Redis key found: ", typeof redisData);
    if (redisData != null) return JSON.parse(redisData);
    return null;
  } catch (error) {
    console.log("Error getting redis cache key: ", key, "  ", error);
    return null;
  }
}

优化建议

如果使用的是云服务商提供的Redis服务，通常默认会配置空闲连接回收规则，可以在客户端ready事件中增加定时心跳，每隔60秒执行一次redisClient.ping()，避免连接被服务端主动断开。
重连次数超限时建议接入告警，避免缓存层完全失效后所有请求打到数据库，引发服务雪崩。

内容的提问来源于stack exchange，提问作者Francois MUGOROZI