ioredis 从 v5 升级到 v6Node.js 20 要求与 RESP3 默认启用如何迁移【免费下载链接】ioredis A robust, performance-focused, and full-featured Redis client for Node.js.项目地址: https://gitcode.com/GitHub_Trending/io/ioredis如果你在维护一个使用 ioredis v5 的 Node.js 项目升级到 v6 时会遇到两个必须处理的破坏性变更v6 要求 Node.js 20 或更高版本并且默认启用 RESP3 协议连接时发送HELLO 3。本文基于仓库内的 README.md、CHANGELOG.md 与源码给出确认运行环境、切换依赖、处理 RESP3 默认行为以及验证迁移结果的完整操作路径。升级前先确认 Node.js 版本README.md 的版本表给出了两条主线的运行环境差异VersionNode.js VersionRedis Version6.x.x (latest) 206.2 ~ latest5.x.x 122.6.12 ~ latestpackage.json 中同样声明了engines: { node: 20.0.0 }当前版本 6.0.0而 CHANGELOG.md 的 6.0.0 条目把这一点写成了明确的破坏性变更ioredis now requires Node.js 20 or newer and uses RESP3 by default. Setprotocol: 2to retain the v5 wire protocol.所以第一步是检查项目实际运行的 Node.js 版本node -v输出低于 v20 时先升级运行环境包括 CI 与部署镜像中的 Node 版本再进行依赖升级v6 的 engines 声明意味着它面向 Node.js 20 的运行时。安装 v6README.md 给出的安装命令npm install ioredisREADME 版本表标注 6.x.x 为 latest 分支因此该命令在升级项目中会装到 6.x。TypeScript 项目还需要按 README 的说明补上 Node 类型声明npm install --save-dev types/nodeRESP3 默认启用保留默认还是回退 RESP2v6 的默认行为README.md「RESP3 Protocol」一节默认使用 RESP3protocol: 3连接时发送HELLO 3当服务器不支持 RESP3Redis 6时ioredis 会透明地降级回 RESP2设置protocol: 2可完全跳过 RESP3。如果你的服务器都是 Redis 6且不依赖 v5 的 RESP2 线上行为可以什么都不改直接保留默认。如果希望保留 v5 的 wire protocolCHANGELOG 建议的迁移方式显式设置const Redis require(ioredis); // 保留 v5 的 RESP2 协议行为 const redis new Redis({ protocol: 2 });降级逻辑可以在 lib/redis/event_handler.ts 中核对只有NOPROTO或UNKNOWN COMMAND针对HELLO这类协议协商错误才会触发降级到 RESP2其他握手错误按致命错误处理降级后protocol置为 2、replyMapping重置为legacy。对应的功能测试见 test/functional/protocol_downgrade.ts覆盖了 HELLO 未知、NOPROTO、服务器支持 HELLO 时保持 RESP3、以及降级后 pub/sub 按 RESP2 路由等场景。replyMapping控制 RESP3 响应形状默认情况下replyMapping: legacyRESP3 下的响应形状与 RESP2 完全一致map 类回复以扁平的[key, value, ...]数组返回double 以字符串返回。也就是说只升级不改代码的项目响应形状不会变化这是 v5 迁移的主要兼容点。如果需要原生 RESP3 的形状map 变成普通对象、double 变成数字显式开启const redis new Redis({ protocol: 3, replyMapping: resp3 }); await redis.config(GET, maxmemory); // { maxmemory: 0 } (legacy: [maxmemory, 0]) await redis.zscore(myzset, member); // 1.5 (a number; legacy: 1.5)上面两行是 README 中的文档示例用于说明两种 mapping 下响应形状的区别而不是固定预期值。replyMapping的相关约束均来自 README.mdreplyMapping只在protocol: 3下有效resp3与protocol: 2组合会在构造时抛错服务器降级到 RESP2 时即使请求过resp3响应也会回落到 legacy 形状并伴随一条警告降级警告的打印逻辑见 lib/redis/event_handler.tsgetBuffer等 Buffer 变体始终返回 buffer不受replyMapping影响唯一例外是在resp3下map 回复是普通对象且键总是 UTF-8 字符串。TypeScript 项目可以直接从类型上区分两种形状参见 test/typing/resp3.test-d.tsprotocol: 2或 legacy mapping 下zscore返回Promisestring | nullreplyMapping: resp3下返回Promisenumber | null。验证迁移结果完成升级后用以下方式核对结果连接可用监听ready事件确认客户端进入就绪状态test/functional/protocol_downgrade.ts 的验证方式即是在ready后执行命令并断言返回值。确认协商到的协议调用redis.hello()其回复包含握手信息其中proto字段等于协商后的协议版本3 或 2。在 legacy mapping 下回复是数组proto在索引 1 处取值在resp3下是对象reply.proto见 test/functional/commands/hello.ts。确认响应形状按上一节的示例执行config(GET, ...)或zscore观察返回值是扁平数组还是对象、double 是字符串还是数字判断当前实际生效的 mapping。留意降级警告若控制台出现replyMapping resp3 was requested, but the server does not support RESP3的警告说明服务器实际降级到了 RESP2响应会回落到 legacy 形状。集群客户端的写法Cluster 客户端把协议相关选项放在顶层选项的redisOptions里传递test/typing/resp3.test-d.ts 中的用法示例const c3 new Cluster([], { redisOptions: { replyMapping: resp3 } });单节点客户端的protocol/replyMapping定义见 lib/redis/RedisOptions.ts默认值为protocol: 3、replyMapping: legacy。版本支持范围与 v6 的其他变化迁移时需要同时核对服务器版本README 版本表标注 6.x 支持 Redis 6.2 ~ latest而 5.x 支持 2.6.12 ~ latest。如果你运行的是低于 6 的 RedisREADME 说明 RESP3 连接会透明降级到 RESP2但版本表给出的支持范围以 6.x 行为准升级前应先确认自己的服务器版本落在表内。除两个破坏性变更外CHANGELOG.md 的 6.0.0 条目还包含新增LMOVEM/BLMOVEM命令支持、Redis 8.10 set cardinality 命令、himport托管 fieldset实验性、stream 读命令支持MAXCOUNT和MAXSIZE、默认连接韧性改进improve default connection resilience以及 cluster MOVED 处理、重连时清理过期 socket 超时等修复。这些是增量能力而非必改项可按需评估。迁移完成的标志Node.js 20 环境中npm install ioredis装上 6.x 后ready事件正常触发、hello()返回的proto与你预期的协议版本一致、命令响应形状与所选replyMapping匹配。若目标环境无法升级 Node.jsv6 不可用应继续使用 5.x 线其支持 Node.js 12。【免费下载链接】ioredis A robust, performance-focused, and full-featured Redis client for Node.js.项目地址: https://gitcode.com/GitHub_Trending/io/ioredis创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考