ioredis是目前Node.js生态中使用最广泛的Redis客户端之一，它的出现解决了早期redis客户端在异步处理、集群支持和自动重连方面的短板。ioredis完全基于Promise和async/await设计，这意味着你不再需要嵌套回调，代码的可读性和可维护性大幅提升。同时，ioredis内置了连接池管理、离线命令队列、Lua脚本、管道、事务以及Redis Cluster和Sentinel的完整支持。对于需要连接生产级Redis服务的Node.js应用来说，ioredis几乎提供了开箱即用的能力。

ioredis的基础用法与连接管理

安装ioredis非常简单，执行npm install ioredis即可。创建客户端实例时，可以传入一个Redis连接字符串，也可以传入配置对象。最基本的用法如下：

const Redis = require('ioredis');
const redis = new Redis({
  host: '127.0.0.1',
  port: 6379,
  password: 'your_password',
  db: 0,
  retryStrategy(times) {
    const delay = Math.min(times * 50, 2000);
    return delay;
  }
});
redis.set('foo', 'bar').then(() => {
  return redis.get('foo');
}).then(value => {
  console.log(value); // 输出 bar
});

这段代码创建了一个Redis连接，并定义了一个简单的重试策略。retryStrategy函数根据重试次数返回下一次重试的延迟时间，超过2000毫秒后不再增加延迟。ioredis在连接断开时会自动尝试重连，并且在重连期间所有发往Redis的命令都会进入离线队列，一旦连接恢复，这些命令会按照发送顺序依次执行。这个特性对于保证数据一致性非常重要，避免了命令丢失导致的业务异常。

除了配置对象，ioredis也支持直接传入Redis URL，例如new Redis('redis://:password@127.0.0.1:6379/0')。在实际项目中，建议使用环境变量或配置中心来管理连接信息，避免硬编码。此外，ioredis还提供了lazyConnect选项，当设置为true时，客户端不会在创建时立即连接，而是等到第一个命令发出时才建立连接，这对于某些需要延迟初始化的场景很有用。连接建立后可以通过redis.status属性查看当前状态，常见状态包括wait、connecting、connect、ready、close和end。

集群模式与哨兵模式的落地实践

对于数据量较大或者需要高可用的场景，Redis Cluster和Sentinel是两种主流方案。ioredis对这两种模式都提供了内置支持，不需要额外安装其他包。使用Redis Cluster时，只需要将客户端换成Cluster类，并传入集群中任意一个或多个节点的地址即可。ioredis会自动获取整个集群的拓扑信息，并在后续操作中根据key的哈希槽将命令路由到正确的节点。下面是一个集群客户端的示例：

const Redis = require('ioredis');
const cluster = new Redis.Cluster([
  { host: '192.168.1.10', port: 7000 },
  { host: '192.168.1.11', port: 7001 },
  { host: '192.168.1.12', port: 7002 }
], {
  redisOptions: {
    password: 'cluster_password'
  },
  scaleReads: 'slave'
});
cluster.set('user:1001', JSON.stringify({ name: 'Alice', age: 30 }));
cluster.get('user:1001').then(console.log);

在上面的配置中，scaleReads设置为slave表示读操作会优先路由到从节点，从而减轻主节点的读压力。ioredis集群客户端会自动处理MOVED和ASK重定向错误。当集群发生节点切换或扩缩容时，ioredis会重新拉取最新的槽位映射，不需要手动干预。需要注意的是，集群模式下有些命令需要确保key落在同一个槽位才能使用，比如多key操作，可以通过使用哈希标签（hash tag）把相关的key强制映射到同一个槽。

哨兵模式则是通过监控Redis主从节点，在主节点故障时自动完成故障转移。ioredis提供了Redis.Sentinel类来连接哨兵集群，客户端会从哨兵获取当前主节点地址，并在故障转移后自动切换到新的主节点。使用方式如下：

const Redis = require('ioredis');
const sentinel = new Redis({
  sentinels: [
    { host: '192.168.1.20', port: 26379 },
    { host: '192.168.1.21', port: 26379 }
  ],
  name: 'mymaster',
  password: 'master_password',
  sentinelPassword: 'sentinel_password'
});
sentinel.set('key', 'value');

在实际生产环境中，哨兵模式通常配合keepalive和连接超时配置一起使用，以减少网络抖动带来的误判。ioredis还支持在哨兵模式下设置preferredSlaves来优先连接某个从节点进行读操作。这些配置项可以大幅提升系统在故障场景下的恢复速度。

性能优化与高频避坑指南

ioredis的性能优化可以从多个维度入手。首先是管道（pipeline）和事务（transaction）。管道允许客户端一次性发送多个命令而不等待每个命令的响应，从而减少网络往返时间。ioredis提供了redis.pipeline()方法，返回一个Pipeline对象，可以链式添加命令，最后通过exec()统一执行。事务则使用redis.multi()，它的行为类似管道，但保证命令的原子性执行。下面是一个批量写入的示例：

const pipeline = redis.pipeline();
for (let i = 0; i < 1000; i++) {
  pipeline.set(`key:${i}`, `value:${i}`);
}
pipeline.exec((err, results) => {
  if (err) {
    console.error('Pipeline执行失败', err);
  } else {
    console.log('批量写入完成');
  }
});

注意代码中的反引号和${}是JavaScript模板字符串，ioredis的key支持任意字符串。使用管道时，如果某个命令报错，不会影响其他命令，但事务会全部回滚。另一个常见的优化点是使用Lua脚本减少服务端交互。ioredis提供了defineCommand方法可以自定义命令，把多个Redis操作封装成一个原子脚本，避免多次网络请求和竞态条件。

避坑方面，最常见的问题是连接数过多。ioredis默认每个实例只维护一个连接，但在集群模式下，每个节点都会有一个连接，如果集群节点很多，可能产生不少连接。生产环境建议使用连接池复用连接，但ioredis本身不提供连接池，可以借助generic-pool等库封装，或者直接创建多个ioredis实例。另一个高频坑是回调中没有处理错误导致未捕获的Promise rejection。由于ioredis基于Promise，如果调用命令后不写catch，一旦网络异常可能直接导致进程崩溃。建议每个命令链上加上catch，或者全局监听redis.on('error')事件。

还有一点需要特别注意：ioredis的key和value参数会被转换为字符串，如果传入对象或数组，需要先JSON序列化。此外，当使用Redis Cluster时，键的哈希标签必须成对出现，例如{user:1001}:profile，否则可能会因为槽位不一致导致命令执行失败。最后，ioredis的自动重连虽然方便，但在极端情况下可能产生雪崩效应，比如Redis服务器长时间不可用，积累的离线队列过大可能导致内存飙升。可以通过maxRetriesPerRequest选项限制重试次数，或者设置enableOfflineQueue为false来关闭离线队列，避免内存无限增长。