Redis EVALSHA 怎样复用已加载脚本

Redis 的 EVALSHA 不是“把脚本名称换成 SHA1 就能永久复用”。正确关系是：先把完全相同的 Lua 脚本文本交给 SCRIPT LOAD，Redis 返回这份脚本的 SHA1；后续再用这个 SHA1 配合同样的 KEYS、ARGV 位置调用 EVALSHA。如果服务端缓存已经被清空，就会收到 NOSCRIPT，此时应重新加载原文后再重试。

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

本文只覆盖脚本 SHA、服务端缓存和 NOSCRIPT 处理，不展开 Lua 业务逻辑设计，也不把脚本缓存当成持久化数据。

先划清 EVALSHA 的目标和边界

可以把一次复用拆成三个对象：

• 脚本文本：真正决定 SHA1 的输入。空格、换行或实现改动都可能得到不同的 SHA。
• 脚本 SHA1：Redis 根据脚本文本返回的短标识，供 EVALSHA 查找缓存。
• 脚本缓存：Redis 进程当前保存的“SHA1 到脚本文本”的关系，不等于业务数据。

所以，EVALSHA 复用的是已经在当前服务端缓存中的脚本，不是客户端本地保存了一个 SHA 就可以离线执行。第一次部署、Redis 重启、主从切换或执行 SCRIPT FLUSH 后，都要把“缓存可能不存在”当作正常分支。

从 SCRIPT LOAD 到 EVALSHA 的完整工作流

最稳妥的工作流是先固定原文，再加载并保存 SHA1，最后用同一个参数布局调用。下面的示例使用一个读取键值的 Lua 脚本，KEYS[1] 是键名，ARGV 暂不使用。

#!/usr/bin/env bash
set -euo pipefail

# 原文是 SHA1 的输入；部署时应把它作为版本化资源保存
SCRIPT='return redis.call("GET", KEYS[1])'

# SCRIPT LOAD 只加载不执行，并返回服务端脚本缓存使用的 SHA1
SHA=$(redis-cli --raw SCRIPT LOAD "$SCRIPT")

# 第一个参数是 SHA1，第二个参数 1 表示后面有一个 KEYS
redis-cli --raw EVALSHA "$SHA" 1 "user:42"

这里的数字 1 不能随便写成 0：它告诉 Redis 后面的第一个参数属于 KEYS，Lua 中才能通过 KEYS[1] 取到 user:42。在这个例子里，ARGV 位于所有 key 之后；即使暂时为空，也要把参数契约固定下来。

SCRIPT LOAD 不会执行脚本，即使同一份脚本已经在缓存中，再次加载也会返回可供 EVALSHA 使用的 SHA1。生产应用可以在启动预热阶段完成加载，也可以把脚本原文和 SHA1 的映射放在应用自己的版本化配置中，但不能只保存 SHA1 而丢掉原文。

把 NOSCRIPT 当成缓存未命中的恢复分支

脚本缓存不会像 Redis 数据那样随业务快照永久保存。服务重启、复制角色变化或手工清理脚本缓存后，旧 SHA1 仍可能写在应用内存里，但服务端已经找不到对应脚本，EVALSHA 就会返回 NOSCRIPT。

#!/usr/bin/env bash
set -euo pipefail

# 应用启动时保留原始脚本，运行时先尝试复用已有缓存
SCRIPT='return redis.call("GET", KEYS[1])'
SHA='此前保存的SHA1'
KEY='user:42'

# 先按 SHA1 调用；NOSCRIPT 只表示服务端暂时没有这份脚本
reply=$(redis-cli --raw EVALSHA "$SHA" 1 "$KEY" 2>&1 || true)
if [[ "$reply" == NOSCRIPT* ]]; then
  # 重新加载原文，不能只重试旧 SHA1
  SHA=$(redis-cli --raw SCRIPT LOAD "$SCRIPT")
  # 重新调用时继续保持 KEYS 数量和 key 位置不变
  redis-cli --raw EVALSHA "$SHA" 1 "$KEY"
else
  # 非 NOSCRIPT 的错误不能被伪装成缓存未命中
  printf '%s\n' "$reply"
fi

这个兜底分支有两个重点。第一，重新加载必须使用与原来相同的脚本文本，否则得到的 SHA1 可能改变。第二，重新加载后只建议在当前请求中重试一次；如果仍然失败，应把真实错误交给上层，而不是无限循环加载。

推荐的生产工作流与检查点

把脚本生命周期分成三个阶段，排障会更清楚：

1. 准备阶段：将 Lua 原文纳入应用发布物，启动时用 SCRIPT LOAD 预热，并记录返回的 SHA1。检查点是应用知道“原文在哪里”，而不是只有一串无法恢复的 SHA。
2. 调用阶段：正常请求使用 EVALSHA，明确传入 numkeys，并让所有调用方遵守同一个 KEYS/ARGV 约定。检查点是参数顺序和脚本契约没有被某个调用方改写。
3. 恢复阶段：只对 NOSCRIPT 重新加载并重试一次；对于 Lua 语法错误、权限错误或业务返回错误，保留原错误。检查点是恢复逻辑不会掩盖其他故障。

如果调用放在 pipeline 中，要额外谨慎：Redis 文档指出，管道里的命令可能已经执行完并返回 NOSCRIPT，客户端无法在同一批次中插入一次及时的加载和重试。因此，不能把“先 EVALSHA，失败后立刻 SCRIPT LOAD”机械塞进一个固定 pipeline；需要由客户端库采用适合管道的回退策略，或者在该场景直接发送参数化的 EVAL。

常见误区与速查表

记住一句话：EVALSHA 依赖的是“SHA1 + 当前服务端脚本缓存”，而不是 SHA1 自身。把原文作为可恢复资源保存，把 NOSCRIPT 当成缓存未命中处理，复用流程就不会被一次重启或主从切换打断。

相关问题

脚本已经用过一次，还需要 SCRIPT LOAD 吗？

不一定。一次成功的 EVAL 也会让脚本进入缓存；显式 SCRIPT LOAD 的优势是可以预热而不执行脚本，并明确拿到 SHA1。

SHA1 能否跨 Redis 实例永久复用？

不能把它当成跨实例的永久凭据。只有目标实例当前缓存了对应原文时，SHA1 才能被 EVALSHA 找到；应用仍应保留脚本原文和加载兜底。

为什么不一直使用 EVAL？

当应用已经稳定管理脚本原文和缓存未命中时，EVALSHA 可以避免每次调用都携带脚本文本；但如果场景是 pipeline 或缓存状态不易管理，参数化 EVAL 可能更简单。