Redis SCAN 使用 MATCH 和 COUNT 时为什么仍会返回重复键

你用SCAN遍历Redis的键集合时，哪怕同时指定了MATCH过滤正则、给COUNT参数设了合理的数值，最终拿到的返回结果里也可能出现重复的键，这并不是你参数用错了，也不是Redis的bug，完全是SCAN本身的迭代设计带来的正常现象。

SCAN命令本身只会保证不遗漏所有存在的键，不保证迭代过程中不会出现重复返回同一个键的情况，这个特性是Redis官方明确说明的，业务侧拿到返回结果后自行做一次去重处理，就可以完全解决这类重复键的问题。

在 Redis 中用 SCAN 0 MATCH order:* COUNT 1000 清理或重建索引时，看到同一个键返回两次，并不代表 MATCH 失效，也不代表 COUNT 没有生效。SCAN 是低状态的渐进式遍历，服务端只保留游标，因此一次完整迭代允许返回重复元素。真正需要修的是消费逻辑：游标必须按返回值推进，副作用必须可重复执行，必要时再在应用侧去重。

官方地址：https://redis.io/docs/latest/commands/scan/

先确认重复键来自哪一层

先把一次调用的两个返回值分开记录：第一个是下一次调用要使用的游标，第二个才是本轮返回的键数组。常见错误是把“本轮数组为空”当成结束，或者每次循环都重新传入 0。正确的停止条件只有一个：服务端返回的下一游标等于 0。

还要确认日志是否在客户端重试时重复打印。网络超时后，如果客户端不知道服务端是否已经处理完请求，直接重发同一个游标可能再次得到一批结果。把请求序号、传入游标、返回游标和本批键数一起记下来，通常很快就能区分“服务端允许重复”和“客户端重复调用”。

不要把 MATCH 和 COUNT 当成去重参数

MATCH order:* 只规定哪些键最终可以返回，过滤发生在遍历内部元素之后，所以匹配很少时某些调用返回空数组是正常的。COUNT 1000 也只是告诉 Redis 每次大致多做一些工作，返回数量可能少于、接近或暂时多于这个数字，不能据此切页或判断结束。

重复的根因在于 SCAN 不建立完整快照，只用一个游标描述当前位置。官方文档明确说明，同一个元素可能返回多次，应用必须自行处理。小型内部编码结构还可能在一次调用中返回全部元素，这也会让“COUNT 等于固定批量”的假设失效。

因此不要用“本次返回数量小于 COUNT”作为结束条件，也不要因为开启了 MATCH 就省掉唯一性保护。MATCH 缩小的是结果集合，COUNT 调整的是单次工作量，两者都没有改变重复返回语义。

让消费逻辑能安全遇到重复键

如果动作本身可以安全重做，优先做成幂等。例如删除同一个键两次，第二次仍得到“键不存在”并不会破坏结果；重建一条带固定主键的索引记录，也可以用覆盖写。相反，发送通知、追加账单、递增计数等动作不能直接放在 SCAN 循环里。

cursor := uint64(0)
seen := make(map[string]struct{})
for {
    keys, next, err := r.Scan(ctx, cursor, "order:*", 1000).Result()
    if err != nil {
        // 中文注释：记录传入游标后退出，避免从 0 重启造成重复副作用。
        return err
    }
    for _, key := range keys {
        if _, ok := seen[key]; ok {
            // 中文注释：同一轮任务内已处理过的键只跳过副作用。
            continue
        }
        seen[key] = struct{}{}
        // 中文注释：这里调用幂等的清理、同步或索引重建动作。
        if err := handleKey(ctx, key); err != nil {
            return err
        }
    }
    cursor = next
    if cursor == 0 {
        break
    }
}

seen 适合一次任务规模可控的场景；键很多时，维护完整集合会占用内存，更稳妥的做法是把处理记录写入带任务标识的 Redis Set 或外部存储，并设置生命周期。若任务允许重复，就只记录“动作已幂等”的证据，不必为了消除所有重复而无限增大缓存。

数据在遍历期间变化时要降低预期

如果遍历期间不断新增或删除键，某个键出现或不出现都不能简单解释为实时快照结果。持续存在的键在一次完整迭代中会被返回，但临时出现的键可能被返回，也可能被漏掉；结构扩容、收缩和重排还会增加观察到重复的机会。

后台过期清理、缓存索引重建、低优先级巡检通常适合 SCAN：接受最终一致，用幂等动作收敛结果。若业务要求“某一时刻的全部键且只处理一次”，应在写入侧建立版本边界，暂停相关写入，或改用专门的任务表、Stream 和快照式数据模型，不要只把 COUNT 调大。

最后做一次反向检查：记录每次传入和返回的游标、去重前后的键数、业务副作用次数以及任务开始后的新增删除量。若游标没有回到 0，先查循环；若游标正常但唯一键数稳定、重复键只增加计数，通常是 SCAN 的正常语义；若副作用次数超过唯一键数，则补上幂等或去重边界。

常见追问

COUNT 设得越大，重复键会消失吗？

不会。COUNT 影响单次调用的工作量和返回规模，不能改变 SCAN 允许重复返回的契约。它可以减少往返次数，但不能替代去重和幂等设计。

SCAN 能保证每个键都只返回一次吗？

不能。一次完整迭代不会返回从头到尾都不存在的键，但对持续存在的键仍不承诺只出现一次；数据变化期间新增或删除键的结果也不适合当作快照。