因为单命令原子性不覆盖多步逻辑,而MULTI/EXEC无法隔离中间状态,只有Lua脚本在服务端单线程串行执行才能保证“读→判→写”整体原子性。

为什么不能只用单个 Redis 命令完成复合逻辑?
Redis 的单命令(如 INCR、HGET、LPUSH)确实是原子的,但一旦涉及「读取 → 判断 → 写入」多步逻辑(比如:若某个 hash 字段值大于 100,则给 list 推一个消息,并更新该字段),就无法靠 pipeline 或事务(MULTI/EXEC)保证真正原子性——因为 EXEC 中间可能被其他客户端插入操作,WATCH 又容易失败重试,且不支持跨数据类型条件跳转。
这时候必须把整个逻辑塞进 Lua 脚本里执行,因为 Redis 对 Lua 脚本的执行是严格串行、不可中断的,且脚本内可自由混合操作 KEYS[1](string)、KEYS[2](hash)、KEYS[3](zset)等不同结构。
如何正确传参并区分 key 和 value?
Lua 脚本在 Redis 中通过 EVAL 或 EVALSHA 执行时,参数被严格分为两段:前面是 keys(必须是真实 key 名),后面是 args(任意字符串值)。Redis 会校验所有 KEYS[i] 是否属于当前节点(集群模式下尤其关键),而 ARGV[i] 完全不受限制。
-
KEYS仅用于定位数据结构,不能传数值或表达式,例如不能写KEYS[1] = "user:"..ARGV[1]—— 这会导致「NOSCRIPT No matching script」或「CROSSSLOT Keys in request don't hash to the same slot」 - 所有动态 key 名(如按用户 ID 拼接)必须由客户端拼好后作为
KEYS入参传入;计算逻辑、阈值、消息内容等一律走ARGV - 示例调用:
EVAL "if redis.call('hget', KEYS[1], 'score') > tonumber(ARGV[1]) then redis.call('lpush', KEYS[2], ARGV[2]); redis.call('hincrby', KEYS[1], 'score', -10); end" 2 user:123 notify:queue 100 \"bonus_earned\"
哪些 Redis 命令在 Lua 里不能用?
不是所有 Redis 命令都支持在 Lua 中调用。最典型的是:KEYS、SCAN、SUBSCRIBE、MONITOR、EXEC、DISCARD 等管理类、订阅类、事务类命令全部被禁用,调用会直接报错 @user_script:1: @enable_strict_lua:1: user_script:1: attempt to call a nil value (field 'KEYS')。
另外要注意:
-
redis.call()是同步阻塞调用,出错会中止整个脚本;redis.pcall()可捕获错误返回 table(如{err="ERR ..."}),适合做兜底处理 - 脚本中不能使用 Lua 的
os.time()、math.random()等非纯函数(Redis 启用lua-time-limit且默认禁止非确定性行为);需用redis.call('time')替代 - 避免在脚本里做循环遍历大量 key(如 for i=1,10000 do … end),超时(默认 5 秒)会被强制 kill,返回
BUSY Redis is busy running a script
集群环境下执行 Lua 脚本的硬约束
Redis Cluster 要求同一个脚本里所有 KEYS 必须落在同一个哈希槽(slot)上,否则报错 CROSSSLOT Keys in request don't hash to the same slot。这不是 Lua 问题,而是集群路由机制决定的。
解决方案只有两个:
- 所有相关 key 使用相同哈希标签(hash tag),即用
{user:123}、{user:123}:profile、{user:123}:events这种形式,确保大括号内内容一致,从而 hash 到同一 slot - 改用
RedisLuaScript(Jedis/Lettuce 等客户端封装)+EVALSHA预加载脚本,并严格校验传入的KEYS是否同槽——客户端一般不自动检查,得自己加逻辑 - 如果业务确实需要跨 slot 操作(如全局计数器 + 用户私有数据),只能拆成多个脚本 + 外部协调,放弃单脚本原子性
真正难的不是写脚本,而是设计 key 结构让业务逻辑能落在一个 slot 里。这点常常被忽略,直到上线后遇到 CROSSSLOT 才去重构 key。


















