Redis Lua 脚本中 key 参数为什么必须显式传入

Redis Lua 脚本里的 key 不是普通字符串参数。调用 EVAL 时，必须先用 numkeys 声明 key 的数量，再把这些 key 逐个放在参数前面；脚本通过 KEYS[1]、KEYS[2] 读取它们，业务值则放在 ARGV 中。这样写既能让单机脚本语义清楚，也能让 Redis Cluster 在执行前判断路由和同槽条件。

官方地址：https://redis.io/docs/latest/

先看懂 EVAL 的参数边界

EVAL 的调用形态是 EVAL script numkeys [key ...] [arg ...]。例如下面的脚本把第一个 key 的值设置为一个普通参数，并返回两组变量，最容易看出边界：

-- 通过显式参数区分 key 和业务值
return {KEYS[1], ARGV[1]}

# numkeys=1，所以 user:42 进入 KEYS，active 进入 ARGV
redis-cli EVAL 'return {KEYS[1], ARGV[1]}' 1 user:42 active

这里的 1 不是“总参数数量”，而是 key 参数数量。把它误写成 0 后，user:42 会变成 ARGV[1]，脚本中的 KEYS[1] 就不存在；把它误写成 2，又会把 active 当成第二个 key。

显式传 key 是执行契约，不是写法偏好

Redis 需要在脚本执行前知道脚本会访问哪些 key。这样做可以保持脚本的 key 访问范围明确，也让集群能够依据 key 计算路由。把 key 塞进 ARGV 后再调用 redis.call('GET', ARGV[1])，在某些单机测试中可能看起来正常，但它违反了脚本的声明约定；如果脚本还会访问多个 key，迁移到集群时就可能无法正确路由。

因此，业务值放在 ARGV，key 名放在 KEYS。不要把 KEYS[1] 当作前缀再拼接出另一个 key，也不要先读一个集合，再根据集合里的内容决定下一个 key。需要访问的名字应由调用方先算好并完整传入。

多 key 场景：声明之后还要检查同槽

如果脚本同时操作两个 key，调用时应将二者都声明。例如同一个用户的资料和锁可以使用相同的 hash tag：

-- 两个 key 必须先声明，ARGV 只保存业务值
local profile = redis.call('HGET', KEYS[1], 'name')
redis.call('SET', KEYS[2], ARGV[1])
return profile

# 两个 key 共享 {user:42}，便于落在同一哈希槽
redis-cli EVAL "local p=redis.call('HGET',KEYS[1],'name'); redis.call('SET',KEYS[2],ARGV[1]); return p" 2 user:{42}:profile user:{42}:lock online

发布前可以用下面的命令检查槽位；两个结果相同，才满足这个多 key 设计的基础条件：

# 分别检查两个显式 key 的槽位
redis-cli CLUSTER KEYSLOT 'user:{42}:profile'
redis-cli CLUSTER KEYSLOT 'user:{42}:lock'

发布前用四项检查排除参数错位

1. 数参数：确认 numkeys 等于脚本实际访问的 key 数量。
2. 看索引：逐个核对 KEYS[n] 与调用命令中的 key 顺序，业务值从 ARGV[1] 开始。
3. 查动态访问：搜索脚本里的字符串拼接和从 Redis 返回值生成 key 的逻辑，改成由调用方显式传入。
4. 查集群槽位：多 key 使用 CLUSTER KEYSLOT 检查；出现 CROSSSLOT 时先调整命名或拆分操作，不要只改 numkeys。

最小验证脚本只需要返回 KEYS 和 ARGV，先证明参数边界正确，再加入真正的读写逻辑。这样排查时能把“参数错位”和“槽位不一致”分成两个独立问题。

常见问题

只有一个 key，也必须放入 KEYS 吗？

是。只要脚本访问它，就应作为 key 参数传入，即使当前部署是单机。

ARGV 里传入 key 名一定马上报错吗？

不一定。单机上可能执行成功，但声明信息不完整，集群路由和后续维护都会留下隐患。

两个 key 名不同就一定不能一起执行吗？

不一定，关键是它们是否落在同一槽。使用相同 hash tag 可以让相关 key 共享槽位，但仍要把每个 key 显式声明。