Redis Lua脚本无法实现SCAN分页，因脚本无状态且无法维护游标；唯一可行方案是客户端驱动SCAN分页，Lua仅负责单次结果的模式匹配与截取。
Redis Lua 脚本里不能直接用 SCAN 分页模糊查
Redis 的 Lua 环境不支持 SCAN 命令的游标状态维护，脚本执行是原子、无状态的，每次调用都是全新上下文。你没法在 Lua 里“记住上次游标”，也就没法靠 SCAN 实现真正的分页。常见错误是写个循环反复调 SCAN，结果每次从 0 开始扫，数据重复、漏掉、性能爆炸。
实际能走通的路只有一条：把模糊匹配逻辑下推到 Lua，用 KEYS 或 SCAN（由客户端驱动）预捞出候选 key，再在 Lua 里做字符串匹配和切片。但注意：KEYS 阻塞主线程，生产禁用；SCAN 必须由客户端分页调用，Lua 只负责单次结果过滤。
- 适用场景：key 名本身含业务标识（如
user:123:profile），且模糊规则简单（前缀/包含/后缀） - 不要在 Lua 里尝试模拟分页逻辑，游标管理必须交还客户端
- 如果 value 里存了要模糊查的字段（比如 JSON 字符串），Lua 可以用
string.find或string.match提取，但别指望它比 Redis 模块或外部索引快
用 SCAN + Lua 过滤实现安全分页
客户端控制分页节奏，每次传入游标和 page size，Lua 只做两件事：拉一批 key，按 pattern 过滤，再截取指定数量。这是唯一兼顾安全与可控的方式。
示例脚本（保存为 filter_scan.lua）：
local cursor = tonumber(ARGV[1])
local count = tonumber(ARGV[2])
local pattern = ARGV[3]
local limit = tonumber(ARGV[4])
<p>local keys, new_cursor = redis.call('SCAN', cursor, 'MATCH', pattern, 'COUNT', count)
local result = {}</p><p>for _, key in ipairs(keys) do
if string.find(key, pattern, 1, true) then -- 全字面匹配，关闭通配
table.insert(result, key)
if #result >= limit then break end
end
end</p><p>return {new_cursor, result}-
SCAN的MATCH是 glob 模式（*、?），不是正则；Lua 里的string.find才支持更灵活匹配 - 传入的
pattern要前后一致：如果SCAN用user:*:info，Lua 里string.find就别再加^或$，否则失配 -
count不是返回条数，只是 SCAN 每次扫描的槽位上限，设太小会导致多次迭代；建议设为 limit × 2～5
为什么不用 redis.call('GET', key) 查 value 再匹配？
因为性能会断崖下跌。每次 GET 都是 O(1) 但有网络/序列化开销，批量查 N 个 key 就是 N 次操作。而 key 名模糊查，99% 场景只需要 key 本身——value 数据量大、结构深时尤其明显。
- 如果必须查 value，优先考虑在 key 设计阶段冗余信息，比如把用户名塞进 key：
user:123:alice:profile - 实在要解析 value，确保它是紧凑格式（如 msgpack 或短 JSON），并用
cjson.decode（需 Redis 7.0+ 启用lua-time-limit和loadmodule支持） - 避免在 Lua 里用
string.match解析长文本或嵌套 JSON，容易超时或 OOM
分页游标处理最容易被忽略的细节
SCAN 返回的 new_cursor 是字符串，不是数字。虽然多数情况是整数字符串（如 "0"、"12345"），但当遍历结束时，它可能返回 "0" —— 这和起始游标一样。仅靠 new_cursor == "0" 判断结束是错的，必须结合本次是否拿到结果来定。
- 客户端必须保存上一次的
cursor和本次返回的new_cursor，即使 new_cursor 是"0"，只要本次result非空，就得继续下一轮 - Redis 官方 SCAN 文档强调：“游标为 0 仅表示‘可能’结束”，真实结束条件是：new_cursor == "0" 且 本次返回 key 数为空
- Lua 脚本里别对游标做算术运算（比如 +1），它本质是内部编码，不是序号
事情说清了就结束。
