1. 从一次线上告警说起脚本明明存在为什么Redis说找不到凌晨两点监控群里弹出一条告警订单状态同步任务批量失败错误日志里清一色刷着同一句话——NOSCRIPT No matching script. Please use EVAL.。这个报错本身不稀奇Redis的Lua脚本机制里EVALSHA命令只认脚本的SHA1摘要不认脚本内容一旦Redis端没有缓存过这个摘要就会直接甩出NOSCRIPT。但诡异的地方在于这套逻辑在测试环境跑了三个月没出过问题上线之后前两周也一直正常偏偏那天晚上开始集中爆发。我先把结论摆在前面绝大多数lua执行redis脚本找不到脚本的问题根因都不在Lua代码本身而在于脚本缓存的生命周期管理没做对。Redis的脚本缓存是跟着实例走的实例重启、主从切换、集群扩缩容、甚至某些运维操作触发的SCRIPT FLUSH都会让缓存瞬间清空。而你的业务代码如果只会用EVALSHA不做降级兜底那缓存一没全线报错就是必然。这篇文章适合三类人看一是正在用RedisLua做原子操作、限流、分布式锁的开发者二是被NOSCRIPT报错折腾过、想彻底搞明白机制的人三是准备把Lua脚本方案上生产、想提前避坑的工程师。我会从报错的本质讲起把脚本加载、缓存、调用、降级的完整链路拆开再结合几种典型场景给出可直接抄的代码和配置最后聊聊那些文档里不会写、只有踩过才知道的经验。先明确一个基础认知Redis执行Lua脚本有两条路径。一条是EVAL直接把脚本内容传过去Redis会先算SHA1、查缓存、没有就加载再执行另一条是EVALSHA只传SHA1摘要Redis查不到缓存就直接报NOSCRIPT。前者每次都要传输整个脚本网络开销大后者省带宽但依赖缓存命中。生产环境为了性能几乎都会选EVALSHA于是缓存管理就成了绕不开的坎。2. NOSCRIPT报错背后的缓存机制Redis到底把脚本存哪儿了2.1 脚本缓存的本质是一个内存字典很多人以为脚本是注册到Redis里的像数据库建表那样持久化。其实不是。Redis内部维护了一个叫lua_scripts的字典结构key是脚本内容的SHA1十六进制字符串value是脚本原文。这个字典纯粹在内存里不落盘、不持久化、不参与主从复制。你执行SCRIPT LOAD或者第一次EVAL时脚本被塞进这个字典执行SCRIPT FLUSH或者实例重启时字典清空。理解这一点非常关键。它意味着脚本缓存是实例级的不是集群级的也不是持久级的。你有三个Redis节点就得保证三个节点都加载了脚本你重启了一次实例之前加载的脚本就全没了。我见过有团队在A节点SCRIPT LOAD完就以为万事大吉结果请求被负载均衡打到B节点照样NOSCRIPT。2.2 SHA1摘要才是真正的钥匙EVALSHA的参数是40位十六进制字符串也就是脚本内容的SHA1。这里有个容易踩的细节SHA1是对脚本原文逐字节计算的任何空白字符、换行符的差异都会导致摘要不同。我遇到过一种情况开发在本地用编辑器写脚本保存时自动把换行符从\n转成了\r\n结果本地算出来的SHA1和线上代码里硬编码的SHA1对不上EVALSHA一直报找不到。排查了半天才发现是换行符的锅。所以正确做法是永远不要在代码里硬编码SHA1而是运行时动态计算。大多数Redis客户端都提供了scriptLoad方法返回的就是服务端算好的SHA1拿这个值去调EVALSHA才靠谱。如果你非要自己算务必保证脚本字符串和传给Redis的完全一致。2.3 主从与集群下的缓存分布单机模式下缓存问题还简单一旦上了主从或集群复杂度直接翻倍。主从架构里SCRIPT LOAD默认只在主节点执行从节点不会自动同步脚本缓存。虽然从节点通常只读但如果你的读请求走了从节点、又恰好用了EVALSHA那从节点没缓存就会报错。集群模式更麻烦脚本要加载到所有持有相关slot的节点上否则请求路由到哪个节点哪个节点就可能报NOSCRIPT。这里给一个判断原则只要你的架构不是单实例就必须假设任何一次EVALSHA都可能失败并为此准备降级路径。这不是悲观而是分布式系统的基本素养。3. 三种典型触发场景缓存是怎么被弄丢的3.1 实例重启与故障转移这是最常见的一种。Redis进程重启内存里的lua_scripts字典自然清空。主从切换时新的主节点如果是刚从从节点提升上来的它之前可能根本没加载过脚本缓存同样是空的。这类场景的特点是突发性——平时好好的某个运维动作或故障一发生报错瞬间铺满日志。我印象很深的一次某业务做限流用的Lua脚本平时QPS不高缓存命中率100%。结果有天机房网络抖动触发了一次主从切换新主节点缓存为空限流逻辑全部失效请求直接打穿到后端数据库。后来复盘发现代码里只有EVALSHA没有任何兜底这就是典型的把缓存当持久化用。3.2 运维脚本误执行SCRIPT FLUSHSCRIPT FLUSH会清空当前节点的所有脚本缓存。有些运维同学为了清理环境或者释放内存会习惯性地执行这个命令殊不知它会把正在使用的脚本一并干掉。更隐蔽的是某些云厂商的Redis控制台提供了清空脚本缓存的按钮点一下就是全量清空。这类问题的排查有个特征报错时间点和某个运维操作高度吻合。如果你发现NOSCRIPT是整点或某个特定时刻集中爆发的先去查那个时间点有没有人动过Redis。3.3 客户端连接池与节点路由错配还有一种容易被忽略的情况客户端连接池里混着多个节点的连接或者集群模式下路由到了没加载脚本的节点。比如你启动时只对主节点做了SCRIPT LOAD但连接池里有些连接指向了其他节点请求随机分配就会间歇性报NOSCRIPT。这种问题的表现是时好时坏排查起来最费劲因为不是必现。判断方法很简单看报错是否集中在部分请求上。如果同一时刻有的请求成功、有的失败大概率是节点路由问题如果全部失败那就是缓存整体没了。4. 从根上解决脚本加载与调用的正确姿势4.1 启动时预加载但别只加载一个节点最基础的做法是在应用启动阶段把所有用到的Lua脚本通过SCRIPT LOAD加载到Redis拿到返回的SHA1缓存到本地。这样后续调用直接用EVALSHA省去每次传输脚本的开销。但关键在于如果你的Redis不是单节点就要对所有可能被路由到的节点都执行加载。以集群为例可以遍历所有master节点逐个SCRIPT LOAD。伪代码大概是这样# 假设已有一个能返回所有master节点的客户端 masters get_all_master_nodes() script_sha_map {} for node in masters: for name, script in SCRIPTS.items(): sha node.script_load(script) script_sha_map[name] sha注意这里每个节点返回的SHA1理论上是一样的因为脚本内容相同但为了保险还是以最后一次加载返回的为准。加载完成后把script_sha_map存到应用的全局配置里供后续调用。4.2 调用时永远带降级EVALSHA失败就回退EVAL预加载能解决99%的问题但解决不了运行中缓存被清空这1%。所以调用层必须做降级。标准模式是先试EVALSHA捕获NOSCRIPT异常然后回退到EVAL直接传脚本内容同时重新SCRIPT LOAD把缓存补上。def execute_script(redis_client, script_name, keys, args): script SCRIPTS[script_name] sha script_sha_map.get(script_name) try: if sha: return redis_client.evalsha(sha, len(keys), keys args) else: return redis_client.eval(script, len(keys), keys args) except NoscriptError: # 缓存失效回退并重新加载 new_sha redis_client.script_load(script) script_sha_map[script_name] new_sha return redis_client.eval(script, len(keys), keys args)这段逻辑看起来简单但有几个细节要注意。第一NoscriptError要精确捕获别把其他异常也吞了。第二重新加载后这次请求用EVAL执行下次请求就能用新的SHA1走EVALSHA了。第三script_sha_map的更新要考虑并发多个线程同时触发降级时别互相覆盖用线程安全的字典或者加锁。4.3 用连接池的初始化钩子做加载更优雅的做法是把脚本加载绑定到连接池的初始化流程里。很多客户端支持连接建立时执行一段初始化逻辑你可以在这里对当前连接对应的节点做SCRIPT LOAD。这样每个连接都保证它连的节点有脚本缓存从根上避免路由错配。不过这个方案有个前提你的客户端要支持这种钩子。如果不支持退而求其次在应用启动时把所有节点加载一遍然后依赖4.2的降级逻辑兜底也够用了。5. 不同客户端和架构下的差异化处理5.1 单机Redis预加载加降级就够了单机场景最简单启动时SCRIPT LOAD一次调用时EVALSHA加NOSCRIPT降级基本不会出问题。唯一要注意的是实例重启后应用如果没重启本地缓存的SHA1还在但Redis端缓存没了第一次调用会触发降级之后恢复正常。这个第一次的延迟可以接受不用特殊处理。5.2 主从架构读请求慎用EVALSHA主从架构下写请求走主节点读请求可能走从节点。如果你的Lua脚本是只读的比如批量GET并且走从节点执行那从节点必须有脚本缓存。但SCRIPT LOAD默认不会同步到从节点所以要么对从节点也执行加载要么读请求干脆不走Lua改用pipeline。我的建议是主从架构下Lua脚本尽量只在主节点执行。因为Lua的原子性保证只在单节点内有效跨主从本来就没有原子性可言走从节点执行Lua意义不大还徒增缓存管理的复杂度。5.3 集群模式按slot路由加载集群模式最麻烦。脚本执行时所有key必须在同一个slot否则会报CROSSSLOT错误。所以加载脚本时理论上只需要加载到持有相关slot的节点即可。但实际操作中为了简单很多团队选择对所有master节点全量加载。这里有个性能考量如果你的集群有几十个节点启动时逐个加载脚本会拖慢启动速度。可以做成异步加载或者懒加载——第一次用到某个节点时再加载。但懒加载又回到了第一次可能失败的问题所以还是要配合降级逻辑。架构类型加载策略调用策略主要风险点单机启动时全量加载EVALSHA 降级实例重启后首次调用降级主从主节点加载从节点可选尽量只在主节点用EVALSHA从节点缓存缺失集群所有master节点加载EVALSHA 降级 slot校验节点路由错配、扩缩容5.4 云托管Redis的特殊性用云厂商的托管Redis时有些操作你是做不了的。比如某些托管实例禁用了SCRIPT LOAD命令只允许EVAL有些实例的故障转移是秒级的缓存清空你根本来不及反应。这种情况下降级逻辑就不是可选项而是必选项。我见过有团队在托管实例上硬用EVALSHA结果每次主从切换都炸一片最后老老实实改成了EVAL加本地缓存脚本内容。6. 排查NOSCRIPT问题的完整链路6.1 第一步确认报错是全量还是部分拿到NOSCRIPT报错先别急着改代码。第一步是统计报错分布是所有请求都失败还是部分失败是持续失败还是某个时间点集中失败这个信息决定了排查方向。全量失败基本是缓存整体清空查实例是否重启、是否执行过SCRIPT FLUSH。部分失败大概率是节点路由问题查连接池配置和集群拓扑。集中失败看时间点对应的运维操作或故障事件。6.2 第二步用SCRIPT EXISTS确认缓存状态Redis提供了SCRIPT EXISTS sha1 [sha1 ...]命令返回每个SHA1是否存在于缓存中。排查时可以直接连上Redis执行看报错的那个SHA1到底在不在。redis-cli SCRIPT EXISTS 4e6d8f2a1b3c5d7e9f0a2b4c6d8e0f1a3b5c7d9e返回1表示存在0表示不存在。如果返回0说明缓存确实没了走降级逻辑即可。如果返回1但业务还是报NOSCRIPT那就要怀疑是不是连错了节点或者客户端算的SHA1和服务端不一致。6.3 第三步核对SHA1计算是否一致前面提过换行符、空格、编码都会影响SHA1。排查时可以写个小脚本把代码里的脚本原文和Redis里SCRIPT LOAD返回的SHA1对比一下。如果对不上就是脚本内容有差异。import hashlib script open(limit.lua, rb).read() print(hashlib.sha1(script).hexdigest())注意用二进制模式读取避免编码转换引入差异。算出来的值和Redis返回的对比一致才说明脚本内容没问题。6.4 第四步检查客户端连接的实际节点如果是集群或主从用CLIENT LIST或者客户端自带的诊断命令看报错的那个连接到底连的是哪个节点。然后对这个节点执行SCRIPT EXISTS确认它有没有缓存。这一步能定位出路由错配的问题。7. 几个文档不会写的实操心得7.1 别把SHA1硬编码进配置文件我见过有团队把SHA1写在配置中心里觉得这样稳定。结果脚本一改SHA1变了配置没同步更新全线报错。SHA1是脚本内容的派生值应该跟着脚本走运行时计算或者启动时加载获取绝不能当成静态配置。7.2 降级逻辑要打日志和监控降级逻辑本身是好事但如果它频繁触发说明你的缓存管理有问题。所以每次降级都要打WARN日志并上报监控指标。如果降级次数突然飙升那就是缓存被清空的信号得赶紧查原因。我一般会设个告警5分钟内降级超过10次就报警这样能在问题扩大前介入。7.3 脚本加载失败要有明确处理启动时加载脚本如果某个节点加载失败怎么办是启动失败还是跳过继续我的建议是核心业务的脚本加载失败应用启动就应该失败。因为带着缺失的缓存启动运行时报错更难排查。非核心脚本可以降级为警告但要有日志记录。7.4 测试环境要模拟缓存清空测试环境往往一切正常因为没人去重启Redis或者执行SCRIPT FLUSH。建议在测试环境定期做混沌测试手动清空脚本缓存看应用能不能自动恢复。这个测试能提前暴露降级逻辑的bug比上线后踩坑强得多。7.5 脚本别写太大加载有开销SCRIPT LOAD和EVAL都要传输脚本内容脚本越大网络开销和解析开销越大。我见过有人把几百行的Lua脚本塞进去每次降级回退EVAL时都卡一下。建议单个脚本控制在几十行以内复杂逻辑拆成多个脚本或者把部分逻辑挪到应用层。8. 写在最后的一点个人体会折腾过几次NOSCRIPT之后我现在的习惯是任何用EVALSHA的地方旁边必须跟着降级代码没有例外。这不是对Redis不信任而是对分布式环境的基本敬畏。缓存这东西天生就是可能不在的把它当持久化用迟早要还债。另外脚本加载这件事最好封装成统一的工具类或者中间件别让每个业务模块自己写一套。统一封装的好处是降级逻辑、日志、监控都能集中管理出问题时排查路径也清晰。我见过项目里五六个地方各自实现脚本调用有的带降级有的不带最后排查起来像破案一样。如果你现在正被这个问题困扰按这个顺序来先确认报错分布再查缓存状态然后核对SHA1最后检查节点路由。大部分情况下前三步就能定位到根因。定位之后把降级逻辑补上基本就能一劳永逸。至于那些为什么测试环境没事的疑问答案通常很简单——测试环境没人去动Redis的缓存。