ioredis

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ioredis v5 — Node.js Redis Client

ioredis v5 — Node.js Redis 客户端

ioredis v5.x. Requires Node.js >= 12, Redis >= 2.6.12. 100% TypeScript.

ioredis v5.x 版本，要求 Node.js >= 12，Redis >= 2.6.12，完全基于 TypeScript 开发。

Critical: Import Style

重要提示：导入方式

// CORRECT — named import (required for NodeNext / moduleResolution: "nodenext")
import { Redis } from "ioredis";

// For Cluster:
import { Redis, Cluster } from "ioredis";

// CORRECT — named import (required for NodeNext / moduleResolution: "nodenext")
import { Redis } from "ioredis";

// For Cluster:
import { Redis, Cluster } from "ioredis";

When to Load References

何时查阅参考文档

Need	Reference file
Connection setup, RedisOptions, TLS, retryStrategy, lifecycle	references/connection-options.md
Core API: pipelines, transactions, Pub/Sub, Lua scripting, scanning, events	references/core-api.md
Streams, auto-pipelining, transformers, binary data, error handling, debugging	references/advanced-patterns.md
Redis Cluster setup, ClusterOptions, Sentinel config, failover	references/cluster-sentinel.md

需求	参考文档路径
连接设置、RedisOptions、TLS、retryStrategy、生命周期	references/connection-options.md
核心API：管道、事务、发布/订阅、Lua脚本、扫描、事件	references/core-api.md
流、自动管道、转换器、二进制数据、错误处理、调试	references/advanced-patterns.md
Redis Cluster设置、ClusterOptions、Sentinel配置、故障转移	references/cluster-sentinel.md

Quick Reference

快速参考

Operation	Code
Connect	`new Redis()` or `new Redis(6379, "host")` or `new Redis("redis://...")`
Get/Set	`await redis.set("key", "val")` / `await redis.get("key")`
Pipeline	`await redis.pipeline().set("a","1").get("a").exec()`
Transaction	`await redis.multi().set("a","1").get("a").exec()`
Pub/Sub	`sub.subscribe("ch")` / `sub.on("message", cb)` / `pub.publish("ch", msg)`
Lua script	`redis.defineCommand("name", { numberOfKeys: 1, lua: "..." })`
Scan	`redis.scanStream({ match: "prefix:*", count: 100 })`
Graceful close	`await redis.quit()`
Force close	`redis.disconnect()`

操作	代码示例
连接	`new Redis()` 或 `new Redis(6379, "host")` 或 `new Redis("redis://...")`
获取/设置	`await redis.set("key", "val")` / `await redis.get("key")`
管道	`await redis.pipeline().set("a","1").get("a").exec()`
事务	`await redis.multi().set("a","1").get("a").exec()`
发布/订阅	`sub.subscribe("ch")` / `sub.on("message", cb)` / `pub.publish("ch", msg)`
Lua脚本	`redis.defineCommand("name", { numberOfKeys: 1, lua: "..." })`
扫描	`redis.scanStream({ match: "prefix:*", count: 100 })`
优雅关闭	`await redis.quit()`
强制关闭	`redis.disconnect()`

Common Gotchas

常见注意事项

Named import: Always
```
import { Redis } from "ioredis"
```
with NodeNext resolution
Pub/Sub isolation: A subscribed client cannot run other commands — use separate instances
maxRetriesPerRequest
: Default is 20. Set to
```
null
```
for infinite retries (required by BullMQ)
Pipeline errors:
```
pipeline.exec()
```
never rejects — errors are in each result's
```
[0]
```
position
showFriendlyErrorStack
: Performance cost — never enable in production
Cluster pipelines: All keys in a pipeline must hash to slots served by the same node
enableAutoPipelining
: 35-50% throughput improvement, safe to enable globally

命名导入：在 NodeNext 解析模式下，请始终使用
```
import { Redis } from 'ioredis'
```
发布/订阅隔离：已订阅的客户端无法执行其他命令 — 请使用单独的实例
maxRetriesPerRequest
：默认值为20。设置为
```
null
```
可实现无限重试（BullMQ 要求此设置）
管道错误：
```
pipeline.exec()
```
永远不会拒绝 — 错误存在于每个结果的
```
[0]
```
位置
showFriendlyErrorStack
：会带来性能开销 — 生产环境切勿启用
集群管道：管道中的所有键必须哈希到同一节点处理的槽位
enableAutoPipelining
：可提升35-50%的吞吐量，全局启用是安全的