在Next.js中使用Redis时出现构建时连接错误

你的问题根源在于模块导入阶段就直接实例化了Redis客户端，而Next.js在执行next build时会加载并执行项目中的页面、组件及关联模块代码，此时即使你没有主动使用Redis，实例化代码也会被触发，尝试连接Redis，进而在Redis不可用时抛出连接拒绝错误。

解决方案：延迟Redis客户端初始化 #

将Redis客户端的实例化逻辑改为懒加载模式，只在实际需要使用Redis的时候才创建连接，避免构建阶段触发连接操作。

修改你的Redis单例代码如下：

import Redis from 'ioredis';

// 声明客户端变量，初始为null
let redisClient: Redis | null = null;

export const getRedisClient = (): Redis => {
  // 如果客户端已存在，直接返回
  if (redisClient) {
    return redisClient;
  }

  // 实例化Redis客户端
  redisClient = new Redis({
    host: process.env.REDIS_HOST || 'localhost',
    port: Number.parseInt(process.env.REDIS_PORT ?? '6379', 10),
    db: Number.parseInt(process.env.REDIS_DB ?? '6', 10),
    keyPrefix: process.env.REDIS_PREFIX ?? ''
  });

  // 监听错误事件，避免未处理异常导致程序崩溃
  redisClient.on('error', (err) => {
    console.error('Redis连接异常:', err);
  });

  // 开发环境下挂载到global，避免重复创建实例
  if (process.env.NODE_ENV === 'development') {
    (global as any).redis = redisClient;
  }

  return redisClient;
};

使用方式 #

在所有需要操作Redis的地方，调用getRedisClient()获取客户端实例，比如：

• API路由中：

// app/api/data/route.ts
import { getRedisClient } from '@/lib/redis';

export async function GET() {
  const redis = getRedisClient();
  const value = await redis.get('demo-key');
  return Response.json({ data: value });
}

• 服务端数据获取函数中（如getServerSideProps）：

export async function getServerSideProps() {
  const redis = getRedisClient();
  const userData = await redis.hgetall('user:123');
  
  return {
    props: { userData }
  };
}

额外说明 #

如果你的页面使用getStaticProps在构建阶段需要获取Redis数据，那么构建环境必须保证Redis可用；如果不需要在构建阶段访问Redis，建议改用getServerSideProps或客户端请求API的方式获取数据，避免构建时触发Redis连接。

内容的提问来源于stack exchange，提问作者Sam Arjmandi