Redis Lua 脚本返回数组时客户端为什么出现 nil

Redis Lua 脚本返回数组后，客户端看到 nil，通常不是 Redis 把数组“随机清空”了，而是同一份数据经过了两次类型映射：Redis 回复先进入 Lua，再由 Lua 返回到 RESP，最后才被客户端解码。最容易踩坑的是 Lua table 中间出现 nil：在 RESP2 下，Redis 转换数组时会在第一个 nil 处停止，后面的元素根本不会进入客户端。

先判断 nil 位于 Lua table、RESP 空回复，还是客户端对象；如果数组中允许缺失值，优先返回字段化结构或显式占位值，不要依赖 Lua 数组保留空洞。

先定位 nil 出现在哪一层

排查时不要只打印客户端最终对象。把问题拆成三段：脚本从 Redis 读到什么，Lua 的 return 产生什么，以及客户端按 RESP2 还是 RESP3 解码成什么。比如下面的脚本从两个键取值，并把结果组成数组：

-- 只演示类型边界，不把缺失值直接塞进序列
local first = redis.call('GET', KEYS[1])
local second = redis.call('GET', KEYS[2])

-- RESP2 下 GET 不存在时会得到 false，而不是可安全保留的 nil
return { first, second }

如果两个键都存在，客户端一般能得到两个成员；如果脚本改成主动返回 { "left", nil, "right" }，结果就不同了。这里的关键不是客户端语言，而是 Lua table 到 RESP 数组的转换规则：第一个 nil 之后的 right 被截断。另一方面，redis.call() 出错会直接抛异常，想把错误作为返回值处理应使用 redis.pcall()，不要把错误对象和缺失值混为一谈。

修复 Lua 数组遇到 nil 后被截断

如果返回值是有顺序的列表，最稳妥的做法是把“缺失”编码成协议能稳定携带的值。例如用空字符串表示未命中，并在接口文档中写清楚空字符串不是业务真实值：

-- 将 Redis 的 false 显式归一化，保证数组每个位置都存在
local function value_or_empty(value)
  if value == false then
    return '' -- 业务上必须约定：空字符串代表没有值
  end
  return value
end

local first = value_or_empty(redis.call('GET', KEYS[1]))
local second = value_or_empty(redis.call('GET', KEYS[2]))
return { first, second }

如果空字符串也可能是合法业务值，就不要继续扩展“魔法占位符”。更适合返回字段化结构，例如 { first = ..., second = ... } 在 RESP2 下并不会按关联键传给客户端，因此应改成明确的顺序字段数组，或把结果序列化成 JSON 字符串：

-- 用 JSON 保留每个字段的语义，客户端只需解码一个字符串
local result = {
  first = redis.call('GET', KEYS[1]) or false,
  second = redis.call('GET', KEYS[2]) or false
}
return cjson.encode(result)

注意，Lua 里的 or false 只是在当前脚本中把缺失状态表达清楚；客户端仍应把 JSON 中的 false 当作“未找到”，而不是把它转换成空字符串后再猜测。

确认 RESP2 与 RESP3 的空值差异

Redis Lua API 默认在脚本执行上下文使用 RESP2。官方映射中，RESP2 的 bulk string、array 和 null bulk 分别进入 Lua string、table 和 false；Lua table 再转回 RESP2 数组时会在第一个 nil 截断。Redis 6.0 以后可以在脚本内部用 redis.setresp(3) 选择脚本调用 Redis 命令时的 RESP3 回复，而客户端连接是否使用 RESP3 则由 HELLO 3 等连接协商决定。

因此，看到 nil 时至少记录两项：脚本是否调用过 redis.setresp(3)，客户端连接是否切换到了 RESP3。RESP3 的 null 在 Lua 中才是 nil，Lua 返回 nil 时也会编码成 RESP3 null；如果连接仍是 RESP2，Redis 还会做相应的协议转换。

实际排错可以先用固定字面量隔离协议，而不是立即怀疑业务查询：

-- 用两个不同的返回槽位区分 false 和普通字符串
redis.setresp(3)
local missing = redis.call('GET', KEYS[1])
return { missing, 'probe-ok' }

若协议切换后仍然是客户端 nil，重点转向客户端库的类型映射和泛型声明；若数组第二项消失，则先回到脚本中的 table 构造位置检查空洞。

让客户端按稳定契约解码

跨语言调用时，不要把“数组第几个元素为 nil”当作字段协议。推荐让脚本返回一个固定长度的数组，并为每个槽位定义类型；或者返回 JSON 对象，让客户端通过字段名读取。对 Go 客户端来说，可以先保留原始结果或使用明确的字符串/布尔分支，再映射到业务结构，不要直接把未知值断言成字符串。

发布前至少覆盖三组用例：两个键都存在；一个键不存在但后续槽位有值；脚本执行出错。分别确认数组长度、缺失值表示和错误分支。这样就能区分“Redis 没返回”“Lua 截断了”“客户端把 null 解码成 nil”三种完全不同的问题。

常见误区与速查

• 把 Lua 的 nil 当成普通数组成员：Lua table 不是可以随意存洞的 JSON 数组，先选占位值或改用序列化对象。
• 只在客户端打印最终对象：同时记录脚本协议、返回长度和原始错误分支，才能确定断点。
• 把 RESP2 与 RESP3 混用：统一连接协商和客户端解码约定；需要切换时把 redis.setresp 的范围写进脚本说明。

Redis 官方的 Lua API 类型转换说明是排查这类问题的基准。记住一条简单规则：先固定返回契约，再讨论客户端如何表示 nil。

相关问题

Redis Lua 返回 false，客户端为什么不是 nil？

在默认 RESP2 脚本上下文里，Redis 的 null bulk 会映射为 Lua false；客户端最终是否显示 nil，还取决于脚本返回后的协议解码和客户端库约定。

Lua 返回关联 table，为什么客户端看不到字段名？

RESP2 的 Lua table 关联键不会作为对象字段发送，通常只转换索引部分。需要字段名时可返回 JSON 字符串，或在 RESP3 下使用官方支持的 map 结构并确保客户端连接按 RESP3 解码。