企业官网建设流程全解析

1. 问题现场还原：为什么脚本突然就“消失”了

Redis 从 2.6 版本开始内置了 Lua 解释器，允许我们把一段逻辑打包成脚本发给服务端执行，最直接的好处是减少网络往返、保证一组命令的原子性。很多团队在秒杀扣库存、分布式锁续期、限流计数这些场景里都会用到它。但几乎每个用过EVALSHA的人，都遇到过同一个报错：

NOSCRIPT No matching script. Please use EVAL.

这个错误的字面意思很直白——服务端说“我这儿没有你给的那个 SHA1 对应的脚本”。可诡异的地方在于，你明明之前用EVAL或SCRIPT LOAD加载过，测试环境跑得好好的，一上生产、一扩容、一重启，脚本就找不到了。新手第一反应往往是“是不是我 SHA1 算错了”，但排查下去会发现，SHA1 计算几乎不会错，真正的问题出在脚本缓存的生命周期和客户端调用策略上。

这篇文章就是围绕这个标题展开的。我会把“找不到脚本”这件事拆成几个层面：Redis 的脚本缓存到底是怎么存的、什么情况下会被清掉、客户端（尤其是 Java 生态里的 Jedis、Lettuce、Redisson）分别是怎么处理这个问题的、以及在生产环境里怎么设计一套“永远不会 NOSCRIPT”的调用方案。内容偏向实战，适合正在用 Lua 脚本做原子操作、又被这个报错反复折磨的后端开发和运维同学。哪怕你只是刚接触 Redis 脚本，看完也能明白背后的机制，不至于再被这个报错牵着鼻子走。

先说结论，避免你带着疑问往下读：NOSCRIPT不是 bug，而是 Redis 脚本缓存机制的正常表现。脚本缓存是跟着 Redis 实例走的，实例重启、主从切换、脚本被显式清除、甚至某些内存淘汰策略触发，都会让缓存失效。客户端如果只会无脑EVALSHA，那必然会在这些时刻翻车。解决办法不是“想办法让缓存永不失效”，而是让客户端具备“发现失效就自动回退到EVAL重新加载”的能力。

2. Redis 脚本缓存机制拆解：脚本到底存在哪

2.1 EVAL 与 EVALSHA 的本质区别

要搞清楚脚本为什么会“找不到”，得先明白 Redis 是怎么管理脚本的。当你执行：

EVAL "return redis.call('GET', KEYS[1])" 1 mykey

Redis 做了两件事：第一，把这段脚本文本计算出一个 SHA1 摘要（40 位十六进制字符串）；第二，把SHA1 -> 脚本文本这个映射存进一个内部的字典结构里，这个字典就是所谓的脚本缓存（script cache）。之后你就可以用这个 SHA1 来调用：

EVALSHA "4e6d8fc8bb01276962cce5371fa795a7763657ae" 1 mykey

EVALSHA不会传输脚本文本，只传 40 字节的摘要，网络开销小得多。对于体积较大的脚本（比如几百行的限流逻辑），这个差异非常明显。但代价就是：服务端必须已经缓存过这个 SHA1 对应的脚本，否则直接返回NOSCRIPT。

这里有个容易被忽略的细节：EVAL执行时也会顺带把脚本写进缓存。也就是说，你第一次用EVAL跑通之后，后续完全可以用EVALSHA复用。很多客户端的“脚本模式”就是基于这个特性设计的——首次EVAL，之后EVALSHA。

2.2 脚本缓存不是持久化的

这是最关键的一点，也是绝大多数人踩坑的根源：Redis 的脚本缓存只存在于内存中，不会写进 RDB 或 AOF。也就是说：

• Redis 实例重启（无论是正常重启还是崩溃恢复），脚本缓存全部清空。
• 主从架构下，脚本缓存不会从主节点同步到从节点。你在主节点SCRIPT LOAD了脚本，从节点上依然是空的。
• 集群模式下，每个节点各自维护自己的脚本缓存，你往节点 A 加载的脚本，节点 B 上不存在。

我见过太多团队在单机测试时一切正常，一上主从或者集群就报NOSCRIPT，原因就在这里。测试环境是单节点，脚本加载一次全局可用；生产是多节点，客户端按 key 路由到不同节点，某些节点上根本没这个脚本。

2.3 哪些操作会清空脚本缓存

除了重启，还有几个操作会主动或被动地清掉缓存，值得单独列出来：

注意：SCRIPT FLUSH在有些客户端的连接池初始化逻辑里会被调用，如果你发现脚本“莫名其妙”没了，先排查是不是某段初始化代码干了这件事。

理解了这些，你就能明白：指望脚本缓存“一直在”是不现实的。正确的思路是让调用方具备容错能力。

3. 客户端调用策略：三种主流方案对比

不同客户端对NOSCRIPT的处理方式差别很大，选错了客户端或者用错了 API，问题就会反复出现。下面把常见的三种策略拆开讲。

3.1 纯 EVALSHA：性能最好但最脆弱

有些底层封装或者手写的工具类，为了追求极致性能，直接EVALSHA，不做任何回退。这种写法在脚本缓存稳定的前提下没问题，但一旦遇到重启、主从切换、集群路由到新节点，立刻抛NOSCRIPT。

我早期写过一个库存扣减的工具类就是这么干的，本地压测 QPS 很漂亮，结果上线第二天赶上一次主从切换，扣库存接口大面积报错。后来复盘，问题就出在“假设缓存永远存在”这个错误前提上。任何依赖服务端状态的调用，都必须考虑状态丢失的情况，这是分布式系统的基本素养。

3.2 EVAL 优先 + EVALSHA 复用：经典折中方案

更稳妥的做法是：客户端本地维护一份脚本内容 -> SHA1的映射，首次调用时用EVAL把脚本发过去（顺便让服务端缓存），拿到结果后把 SHA1 记下来，后续调用改用EVALSHA。如果EVALSHA返回NOSCRIPT，就回退到EVAL重新加载，再继续。

这个策略的核心在于本地缓存 SHA1，避免每次都重新计算摘要。Jedis 的Scripting相关封装、以及很多自研工具类都是这个思路。伪代码大概长这样：

public Object evalWithFallback(Jedis jedis, String script, List<String> keys, List<String> args) { String sha1 = localSha1Cache.computeIfAbsent(script, this::calcSha1); try { return jedis.evalsha(sha1, keys, args); } catch (JedisNoScriptException e) { // 缓存失效，回退到 EVAL 重新加载 return jedis.eval(script, keys, args); } }

这里有个细节：捕获的异常类型要对。Jedis 抛的是JedisNoScriptException，Lettuce 抛的是RedisCommandExecutionException且 message 里含NOSCRIPT，Redisson 内部已经帮你处理了。用错异常类型会导致回退逻辑根本不触发。

3.3 客户端自动管理：Redisson 与 Lettuce 的做法

Redisson 在这方面做得比较省心。它内部维护了脚本的 SHA1 缓存，并且在检测到NOSCRIPT时会自动重新加载脚本再执行，对使用者基本透明。你调用RBucket.compareAndSet这类方法时，底层用的就是 Lua 脚本，但不需要你关心加载问题。

Lettuce 则提供了RedisScriptingCommands，但自动回退需要自己实现。不过 Lettuce 的异步和响应式 API 在处理这类“先失败再重试”的逻辑时比较优雅，可以用onErrorResume做回退。

选择建议很直接：如果你不想自己处理这些细节，用 Redisson；如果你追求轻量和可控，用 Jedis 或 Lettuce 并自己封装回退逻辑。最怕的是用了一个“半自动”的封装，既没有自动回退，又隐藏了底层细节，出问题时无从下手。

4. 生产级落地方案：从代码到部署的完整实践

光讲原理不够，下面给一套可以直接抄作业的方案。这套方案我在几个项目里用过，覆盖单机、主从、集群三种部署形态，核心思路是“本地缓存 SHA1 + 自动回退 + 启动预热”。

4.1 脚本管理器的设计

先设计一个脚本管理器，职责是：加载脚本、缓存 SHA1、执行时自动回退、支持集群多节点预热。

public class RedisScriptManager { private final Map<String, String> sha1Cache = new ConcurrentHashMap<>(); private final Map<String, String> scriptCache = new ConcurrentHashMap<>(); public void register(String name, String script) { scriptCache.put(name, script); sha1Cache.put(name, DigestUtils.sha1Hex(script)); } public Object execute(JedisCluster cluster, String name, List<String> keys, List<String> args) { String script = scriptCache.get(name); String sha1 = sha1Cache.get(name); try { return cluster.evalsha(sha1, keys, args); } catch (JedisNoScriptException e) { // 集群下需要针对目标节点重新加载 return cluster.eval(script, keys, args); } } }

关键点在于sha1Cache用ConcurrentHashMap，避免多线程重复计算；scriptCache保存原文，回退时用得上。注册动作放在应用启动时执行，把所有脚本一次性登记好。

4.2 集群模式下的预热策略

集群模式是NOSCRIPT的重灾区，因为脚本要加载到每一个可能被路由到的节点上。预热逻辑不能只连一个节点，得遍历所有主节点逐个SCRIPT LOAD：

public void warmUp(JedisCluster cluster) { for (String name : scriptCache.keySet()) { String script = scriptCache.get(name); // 遍历集群所有主节点 for (JedisPool pool : cluster.getClusterNodes().values()) { try (Jedis jedis = pool.getResource()) { jedis.scriptLoad(script); } } } }

这里有个坑：cluster.getClusterNodes()返回的是节点连接池，遍历时要注意连接释放，用 try-with-resources 包住。另外预热最好放在应用启动完成、开始接收流量之前，否则预热期间进来的请求还是可能报错。

提示：集群扩容后新节点是空的，预热逻辑需要在扩容后重新执行一次。可以把这个预热接口暴露成一个运维端点，扩容后手动触发。

4.3 主从架构下的读写分离陷阱

主从架构下，如果你把脚本执行发到了从节点（比如为了分担读压力），而脚本里包含写操作，那本身就不对——从节点是只读的。但即使是只读脚本，从节点的脚本缓存也是独立的，主节点加载了不代表从节点有。

所以主从架构下要么统一走主节点执行脚本，要么对从节点也做一遍预热。我倾向于脚本执行统一走主节点，因为 Lua 脚本的原子性保证只在单节点内有效，跨节点本来就没有原子性可言，走从节点没有额外收益，反而增加缓存不一致的风险。

4.4 参数传递的常见错误

脚本找不到是一类问题，脚本找到了但执行报错是另一类。后者里最常见的是参数类型问题。Redis 的 Lua 脚本里，KEYS和ARGV传进来的都是字符串，如果你在脚本里直接做数值比较，得先tonumber：

local current = tonumber(redis.call('GET', KEYS[1]) or '0') local delta = tonumber(ARGV[1]) if current + delta < 0 then return -1 end redis.call('INCRBY', KEYS[1], delta) return current + delta

忘了tonumber的话，Lua 里字符串和数字比较会直接报错，错误信息跟NOSCRIPT完全不同，但排查时容易混淆。养成习惯：所有从 ARGV 拿的数值，一律先 tonumber。

5. 常见问题速查与避坑清单

把实际运维中遇到的高频问题整理成表，方便对照排查。

几个补充的避坑点：

• 不要用SCRIPT FLUSH做“清理”。有些同学觉得脚本缓存占内存，定期 flush 一下，结果把正在用的脚本也清了。脚本缓存占用的内存通常很小，没必要主动清。
• SHA1 计算要用标准实现。自己手写摘要算法容易出错，直接用客户端库提供的，或者DigestUtils.sha1Hex。
• 脚本里不要用随机函数和系统时间。Redis 为了保证脚本可重放（用于主从复制和 AOF），对math.random和os.time有特殊处理，写不好会导致主从数据不一致。需要随机性的话，把随机值作为参数从外部传进去。
• 注意脚本的原子性边界。Lua 脚本执行期间会阻塞其他命令，脚本越长阻塞越久。超过lua-time-limit（默认 5 秒）后，其他客户端会收到 BUSY 错误。所以脚本要尽量短小，别把一堆业务逻辑塞进去。

6. 我踩过的几个真实坑

最后分享几个我自己在项目里踩过的坑，都是文档里不会写的。

第一个坑是连接池与脚本缓存的错配。有次我们用 Jedis 连接池，每个连接是独立的，脚本加载在某一个连接上，结果下一个请求拿到的是另一个连接，虽然脚本缓存是实例级别的（跟连接无关），但当时误以为是连接问题，排查了半天。后来才确认脚本缓存是实例级的，跟连接无关，问题其实出在实例重启。这个经历告诉我：排查问题要先确认前提，别被表象带偏。

第二个坑是集群下的 key 路由。集群模式里，EVALSHA的 key 必须落在同一个 slot，否则直接报 CROSSSLOT 错误。我们有个脚本用了两个 key，没加 hash tag，结果两个 key 落在不同节点，脚本根本没法执行。解决办法是用{tag}把相关 key 强制路由到同一 slot，比如{user:1001}:balance和{user:1001}:quota。

第三个坑是升级客户端版本后行为变化。某次升级 Lettuce 版本，发现原来能自动回退的逻辑不生效了，查了半天是异常类型变了。所以升级客户端库时，涉及脚本调用的部分一定要回归测试，别只看编译通过。

这套方案落地之后，我们线上再没出现过因为NOSCRIPT导致的接口报错。核心就一句话：别假设服务端状态永远在，让客户端具备自愈能力。脚本缓存会丢是常态，回退逻辑才是保障。