当前位置：首页 > 文章列表 > 数据库 > Redis > Redis SCAN 使用 MATCH 和 COUNT 时为什么仍会返回重复键

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

来源：17golang原创 2026-09-15 01:18:28 0浏览收藏

你用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/

要点速览

cursor=0 开始，只有返回游标再次为 0 才表示一轮结束。
MATCH 在取出元素后过滤，COUNT 是每次调用的工作量提示，不是固定页大小。
全量遍历若要求唯一副作用，用幂等设计或 seen 集合兜底；数据持续变化时不要把 SCAN 当快照。

先确认重复键来自哪一层

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

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

Redis SCAN 游标、匹配过滤与返回键集合的静态关系示意图 — 图1：SCAN 游标、MATCH 过滤和返回键集合的静态关系示意图；这是解释性插图，不是实际 Redis 截图。

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

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

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

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

Redis SCAN 重复键与幂等消费、应用侧去重之间的静态关系示意图 — 图2：重复返回、幂等副作用和应用侧 seen 集合之间的静态关系示意图；这是结果解释图，不是运行证据。

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

如果动作本身可以安全重做，优先做成幂等。例如删除同一个键两次，第二次仍得到“键不存在”并不会破坏结果；重建一条带固定主键的索引记录，也可以用覆盖写。相反，发送通知、追加账单、递增计数等动作不能直接放在 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 或外部存储，并设置生命周期。若任务允许重复，就只记录“动作已幂等”的证据，不必为了消除所有重复而无限增大缓存。